Unified SDK

Allows to use different VPN protocols inside one app and switch between them more easily.

API Documentation

To see all available API, check API Reference.

Table of Contents

• Integration

• Manual switching SDK

  • Configure manual switching SDK

  • Switch VPN protocol manually

• Auto switching SDK

  • Configure auto switching SDK

• Loggin in

• Connecting VPN and obtaining status

• Active VPN protocol autocorrection

• Fireshield features

Integration

Unified SDK supports all protocols that you can use with single protocol SDK separately: Hydra, IPSec, WireGuard. So intergation process includes:

1. Setup application target

2. Setup network extension target for every protocol you want to support.

Start using Unified SDK

There are 2 ways how you can use Unified SDK: manual protocol switching (through ManualSwitchingVPNSDK) and auto switching (through AutoSwitchingVPNSDK).

Manual switching SDK

Manual switching SDK provides ability to change VPN protocol at any moment by user requirement.

Configure manual switching SDK

To start using the SDK, you need to import import VPNApplicationSDK to your file under the application target.

Unified SDK requires that at least 2 different available SDK types should be provided to configuration. For instance, in order to use Hydra and IPSec protocols together you can specify following configuration:

import VPNApplicationSDK
// ...
    
let configuration = UnifiedConfiguration(
    availableTypes: [
        .hydra(extensionBundleID: "HYDRA_NETWORK_EXTENSION_BUNDLE_ID"),
        .ipsec
    ],
    carrierID: "CARRIER_ID",
    groupData: VPNGroupData(
        groupID: "group.GROUP_ID",
        usesSystemExtension: false
    ),
    profileName: "PROFILE_NAME",
    fireshieldConfig: fireshieldConfig,
    isOnDemandEnabled: true,
    isVPNIconFixEnabled: true
)

let initialProtocolType = VPNProtocolType.hydra // This protocol will be set as active after SDK init

self.unifiedSDK = ManualSwitchingVPNSDK(configuration: configuration, initialProtocolType: initialProtocolType)

The best place to put initialization code is you AppDelegate's application:didFinishLaunchingWithOptions:.

Switch VPN protocol manually

You can use func switchToProtocol(_ newProtocolType: VPNProtocolType, completion: ((_ error: Error?, _ activeSDK: VPNSDK?) -> Void)?) method to change VPN protocol. If VPN is connected at the moment of call, it will be stopped and then reconnected to the same location after protocol change. This method also provides logic that helps to resolve some annoying problems related to protocols changing (e.g., unwanted On Demand functionality from old protocol).

Auto switching SDK

Auto switching SDK modifies VPN start flow in a way when it can fallback to different VPN protocols depending on provided protocol priority.

Configure auto switching SDK

Auto switching SDK is build upon manual switching SDK and uses it to switch between VPN protocols when needed. So you should initialize ManualSwitchingVPNSDK and use it with priority provider as parameters for AutoSwitchingVPNSDK init:

import VPNApplicationSDK
// ...
    
let manualSwitchingSDK = // ...

// This closure will be called at the beginning of start flow to determine VPN protocols order
let priorityProvider: AutoSwitchingVPNSDK.PriorityProvider = {
    return [.hydra, .ipsec]
}

self.unifiedSDK = AutoSwitchingVPNSDK(manualSwitchingSDK: manualSwitchingSDK, priorityProvider: priorityProvider)

Logging in

After SDK is initialized, you need to login to be able to start VPN. If you are using OAuth authentication, provide your own OAuth dialogs UI and receive OAuth access token. Login example with OAuth token:

import VPNApplicationSDK
// ...

let unifiedSDK: ManualSwitchingVPNSDK // or AutoSwitchingVPNSDK
// ...

let authMethod = AuthMethod(type: .oauth, token: "OAUTH_TOKEN")

unifiedSDK.login(method: authMethod) { error, user in
    print("isLogged: \(error == nil)")
}

See AuthMethod in API reference for more authentication methods.

Connecting VPN and obtaining status

To connect VPN you can use function start(location:completion:) (the same as for single protocol SDKs). When VPN is started or an error occurred, completion handler will be called. To obtain VPN connection status you need to subscribe to vpnStateDidChange notification provided by SDK. For example:

NotificationCenter.default.addObserver(forName: .vpnStateDidChange, object: nil, queue: nil) { notification in
    // ...
}

When you receive notification, get updated VPN status from SDK instance state property and handle this status as designed by your app.

Active VPN protocol autocorrection

Sometimes you can face situation when value of active protocol type inside SDK became out of sync with actual active protocol type (for example, if you did set active protocol to .hydra, but then user started IPSec connection from iOS settings). In such cases SDK will automatically change value of active protocol type to the actual value.

Detection of protocol change

You can observe VPN protocol changes (both manual and auto) by subscribing to vpnProtocolDidChange notification. When you receive notification, get updated protocol type from activeProtocolType SDK instance property.