Developers SDK

VPN Unlimited SDK v2.0 for macOS

Getting started

Overview

VPN Unlimited SDK for iOS/macOS is shipped as a static framework. It is written in Objective-C and C++ and is available for iOS 9.0 and OS X 10.11 and later.

Setup

Drag and drop VPNUnlimitedSDK.framework into your project.

After the setup is complete, you should be able to use all classes from the SDK by including it with #import <VPNUnlimitedSDK/VPNUnlimitedSDK.h> directive.

Note:

The current version of VPN Unlimited SDK uses the following libraries under the hood:

  • libcrypto
  • libssl
  • libcares
  • libjansson
  • libcurl

If your project uses one of these libraries and you get conflicts, please contact VPN Unlimited team for further investigation.

App Sandbox Mode

You must set Incoming Connections (Server), Outgoing Connections (Client) checkboxes when using Apple's App Sandbox mode.

VPN protocols

The current version of VPN Unlimited SDK supports the following VPN protocols:

  • IPSec IKEv2
  • OpenVPN
  • KeepSolid Wise 1
  • KeepSolid Wise 2
  • WireGuard (currently not available for general servers)
Classes

This SDK is designed in classical OOP style. We provide a handful of classes which you can use in any desired combination. All network calls are synchronous.

Here is the full list of classes:

  • KSVPNUFacade
  • VPNULocation
  • VPNULocationInfo
  • VPNUAccountStatus
  • VPNUAccountUserInfo
  • VPNUAccountDevice
  • VPNUPersonalServer
  • VPNUServerItem
  • VPNUStorage
  • VPNUAuthDelegate
  • VPNUConnection
  • VPNUManager
  • VPNUErrorCodes
  • VPNUPacketTunnelProvider
  • VPNUWireguardTunnel
  • VPNUResponseContainer

macOS additional headers:

  • VPNUServiceDelegate
  • VPNUSystemService

You can see the complete documentation for each class on the Reference page. Here we just briefly describe the standard workflow.

Bitcode

Currently Bitcode for iOS is not supported.

SDK initialization

Use the following method to initialize VPN Unlimited SDK:

[KSVPNUFacade.defaultFacade
initializeSettingsWithAppID:<#Application id#>
appSecret:<#Application secret#>
applicationGroupIdentifier:<#Application group identifier#>
appVersion:<#Application version#>
sharedKeychainGroupID:<#Shared keychain group#>
providerBundleIdentifier:<#Provider bundle identifier#>
wgProviderBundleIdentifier:nil profileName:<#VPN profile name#> completion:<#Completion block#>];
  • AppId - application identifier
  • AppSecret - key/secret that provides access to VPN Unlimited API
  • ApplicationGroupIdentifier - log group identifier (for example OpenVPN)
  • AppVersion - app version
  • SharedKeychainGroup - shared Keychain group, mandatory parameter
  • ProviderBundleIdentifier - bundle identifier from Network Extension Packet Tunnel Provider. Without this identifier, OpenVPN and KeepSolid Wise protocols will not work.
  • ProfileName - the name of a VPN profile, which will be displayed in the system network settings.

In case after the initialization you get the 501 error for each request, check the AppId and AppSecret.

To initialize and set up Standalone macOS SDK, please contact VPN Unlimited team.

Multithreading

As stated previously, all network calls in this SDK are performed synchronously. This means that you should perform them all in a non-main thread, otherwise they will be blocked and never come back. Each method which falls into this category is explicitly documented.

In order to achieve asynchronous behavior, you can use any multithreading technique you prefer. We recommend Grand Central Dispatch. When the operation is finished you can move back to the main thread. You can stay on the secondary thread and perform more networking actions serially, if you like.

KSVPNUFacade

KSVPNUFacade is a class which serves as a 'facade' to other VPN Unlimited SDK classes. It hides the complexity of VPN Unlimited SDK by encapsulating most of the needed features.

If you do not want to construct API requests and the VPN configurator by yourself you can use KSVPNUFacade singleton. Please check the documentation for this class, it is suitable for most applications.

FAQ

How to register a new user?

Use the following method to register a new user:

registerWithLogin:password:marketingEmails:partnerId:completion

The email address should be a valid one, not generated by a temporary email service.

The password should match the below requirements:

  • it should be at least 8 characters long
  • it should contain ASCII characters only.

In case of a successful registration, the user will be automatically logged in the system. 

BOOL doNotReceiveMarketingEmails = YES;
[KSVPNUFacade.defaultFacade registerWithLogin:email
                                     password:password
            		  marketingEmails:doNotRecieveMarketingEmails
	                  partnerId:nil
       completion:^(NSError *error) {}];
How to log in an existing user?

Use the following method to log in:

 [KSVPNUFacade.defaultFacade authorizeWithLogin:login
                 				password:password
     completion:completion];
How to log out a user?

To log out a user, use the method signOutWithCompletion:

The following properties of the object will be cleared: KSVPNUFacade.defaultFacade - currentUserInfo, currentDeviceInfo, currentAccountStatus, currentServersList

[KSVPNUFacade.defaultFacade signOutWithCompletion:^(BOOL successful, NSError *error) {}];
How to retrieve account status of a logged in user?

How to retrieve account status of a logged in user?

(void)accountStatusWithCompletion:(void(^)(VPNUAccountStatus *accountStatus, NSError *error))completion;

We recommend to request the account status at the start of the application, after the successful connection, or when disconnecting from a VPN server. The account status includes the following important parameters:

  • Server location
  • User location
  • Status of the user’s subscription
  • Whether the user is in the trial period.
How to retrieve the list of available VPN servers?

Use the below method to get the full list of VPN servers:

(void)serverListWithOptions:(KSVPNUServerListOptions)mask
                   completion:(void(^)(NSArray<VPNUServerItem *>
                     *serversList, NSError *error))completion

Description of options:

  • KSVPNUServerListOptionsNonAuthorized - get the list of servers without authorization
  • KSVPNUServerListOptionsOptimal - the list of Optimal servers (contains a partial list of information about a server)
  • KSVPNUServerListOptionsSquareFlags - square-shaped images of flags

As a result of the command execution, you get an array of VPNUServerItem objects.

How to connect to the selected VPN server?

To connect to a VPN server, you need to select a server and a connection protocol.

[KSVPNUFacade.defaultFacade startVPNTunnelWithServerItem:selectedServer protocol:protocol completion:completion];

If you want to reconnect or change protocol, you need to stop the VPN connection first:

[KSVPNUFacade.defaultFacade stopVPNWithCompletion:^(NSError *error) {}];

After the VPN connection is stopped, establish the connection again, using the required parameters.

Note:Before establishing the connection, it is recommended to check if the user has a subscription. You can find this information in the user’s account status. In case there is no active subscription, the user will lose access to the internet after the connection, HTTPS websites will not open, and HTTP websites will redirect the user to our website with the offer to get a subscription.

How to monitor the VPN connection status?

Subscribe for the notification VPNUConnectionStatusDidChangeNotification and check the status of VPN connection by the property: 

VPNUConnectionStatus connectionStatus = KSVPNUFacade.defaultFacade.connection.status;
Validation of a purchase

After a successful purchase, you need to call the method of purchase validation on our server.

In the countryCode parameter you need to pass nil

(void)validatePurchaseWithCountryCode:(NSString *)countryCode
  completion:(void(^)(NSError *error))completion;

After the purchase validation, you need to check the account status. The expiry date of the subscription should be updated - expiredDate.

How to use a temporary account?

A temporary account is required to use the VPN service without registration.

Generation and registration of a temporary account

To generate and register a temporary account, use the following method

(void)registerFakeAccountWithCompanyDomain:(NSString *)companyDomain completion:(void(^)(NSString *login, NSString *password, NSError *error))completion;

It will return the login/password pair, which should be saved in a secure storage (for example, Keychain). The credentials can be used for a login in the future.

Merging a temporary and permanent accounts

All purchases made with a temporary account are tied to this account. If a user registers a permanent account by themselves, all information and purchases from the temporary account can be transferred to the permanent one. To do this, you need to call the below method:

(void)mergeLogin:(NSString *)login
     withFakeLogin:(NSString *)fakeLogin
      fakePassword:(NSString *)fakePassword
          password:(NSString *)password
        completion:(void(^)(NSError * error))completion;

Note:After the merge, it is not possible to log in to the temporary account, as it is deleted.

Synchronization of a temporary account between iOS devices

To synchronize a temporary account between iOS devices, iCloud is used. iCloud Drive must be enabled in the device settings.

Saving account:

(void)saveAccountInCloudLogin:(NSString *)login password:(NSString *)password;

Getting an account from iCloud:

(NSDictionary *)loadAccountFromCloud;
Using VPN protocols

To use OpenVPN/KeepSolid Wise protocols, you need to add the Network Extension to the project:

In the XCode select Project file -> Add new target (+) -> Network Extension Provider Type - Packet Tunnel Embedded in application - choose your application target

In the header file, make sure the class your created from VPNUPacketTunnelProvider is inherited.

#import 
@interface PacketTunnelProvider : VPNUPacketTunnelProvider
@end

All predefined methods in the .m file should be deleted.

Other versions: 1.1 / 1.2 / 1.9 / 1.9.2 / 2.0.1 / 2.1.0 / 2.2.0