Pango Platform
HomeConsole
  • What is Pango Developer Platform
  • Getting started
    • Sign up on the Management Console
    • Create a new project
    • Switch projects
    • Change console settings
    • Edit your profile
    • Try out the demo app
    • Keep exploring
    • Deprecation and Sunset
  • Console details
    • Dashboard
      • General
      • Location loading
    • Users
      • User page
    • Active sessions
    • Network
      • Countries
      • Locations
      • Pools
        • Optimal location
        • Location rules
    • Settings
      • General
        • Project config description (JSON format)
          • Server selector (JSON format)
          • Request selector (JSON format)
      • Authentication methods
        • Auth Plugin requirements
      • VPN
        • General
        • VPN Bypass list
        • Client Networks
      • Member
    • Export Data
    • Log
  • SDK
    • Unified VPN SDK for Android
      • Setup
        • Application Setup
        • Proguard Rules, Notification, and Analytics Configurations
        • Backend URL Configuration
      • Usage
        • Initialization
        • VPN Interface
        • Backend interface
      • Features
        • Hydra Protocol
          • Location profile (Hydra only)
        • Custom sdk dependencies
        • Deferred VPN Service Initialization
        • Authentication
        • Client Network List (CNL)
        • OpenVPN transport
        • Wireguard Transport
        • Reconnection strategy
        • Single Protocol SDK
        • Killswitch
        • Domain route via VPN
        • Process route via VPN
        • Process Bypass
        • Domain Bypass
        • Traffic rules
        • VPN Node DNS Configuration
        • Multihop
          • Optimal Location
      • Exceptions
      • Version migration
      • Changelog
    • Unified VPN SDK for Apple
      • Setup
        • Application Setup
        • Network Extension Setup
          • Network Extension Setup for tvOS
        • Backend URL Configuration
      • Usage
        • Single Protocol SDK
        • Unified SDK
        • Logging
        • Decoding Encoded VPN SDK Logs
      • Features
        • Deferred VPN Service Initialization
        • Authentication
        • Wireguard Transport
        • Reconnection strategy
        • Killswitch
        • Domain Bypass
        • Multihop
          • Optimal Location
        • Client Network List (CNL)
        • Domain route via VPN
      • Changelog
      • API Reference
    • IPSEC VPN SDK for Apple
    • Unified VPN SDK for Windows
      • Setup
        • Backend URL Configuration
        • Service command line arguments
        • ARM Platform Support
      • Usage
        • CoreAPI
        • Events
        • Generating a Unique Device Identifier
        • Error processing
        • Pipe Messaging
      • Features
        • Traffic protection
          • Killswitch
          • Prevent IP Leaks
          • Block Local Networks
        • Other
          • Firewall
            • DNS Monitor
            • Process Bypass
            • Domain Bypass
            • Process route via VPN
            • Domain route via VPN
          • Throttling
          • Optimal Location
          • Common issues
        • Hydra Protocol
          • CustomDNS, UserDNS, MultiHop, VpnProfiles
        • OpenVPN Protocol
        • Wireguard Protocol
        • IPSec Protocol
      • Collecting Debug Logs
      • Changelog
    • Unified VPN SDK for Routers
      • SDK. Shared library.
      • Configuration Interface (CI)
        • Unix Domain Sockets CI
        • REST API CI
    • Unified VPN SDK Feature Comparison By Platform
    • Unified VPN SDK
      • Features
        • Personal Bridge
    • Tunnel Vision and Tunnel Crack Prevention
  • REST API
    • Partner API
  • Sample applications
    • Unified VPN SDK demo for Windows
    • Hydra VPN SDK demo for iOS
    • IPSEC VPN SDK demo for iOS
    • Unified VPN SDK demo for Android
    • Hydra VPN SDK demo for OpenWRT
    • OpenVPN configuration file
  • Resources
    • Use cases
      • Public VPN
      • Business VPN
        • Creating a Business VPN Project
        • Wi-Fi Security for Business
      • Application anti-blocking
    • How-to
      • Create a Firebase project for User Authentication
      • AWS CloudFront Distribution of the Platform URL
      • How can I get Shared Secret key from iTunes Connect for In-App Purchase
  • FAQ
    • General
      • VPN Platform Flow
      • What data is collected by the Platform?
      • What analytic data is collected by your SDK?
      • How the Platform restricts access to our data?
      • Why DNS Leak tests often indicate positive result?
      • Do we need to perform endpoint health checks?
      • How is the VPN exit node found?
      • How are streams re-marked if VPN is enabled/disabled on an active flow?
      • Is there a maximum number of supported devices?
      • Are both IPv4 and IPv6 supported?
      • What is the MTU of the tunnel?
      • Are any redundancy measures in terms of reliability provided?
      • Is there any load balancing?
      • Do you block broadcast and multicast to/from the VPN?
    • List of Open Source libs
Powered by GitBook
On this page
  • Table of Contents
  • class VPNSDK: NSObject
  • class HydraSDK: VPNSDK
  • struct OnDemandConfiguration
  • struct NetworkConfiguration
  • struct BypassConfiguration
  • struct ModulesConfiguration
  • struct HydraConfiguration
  • class IPSecSDK: VPNSDK
  • struct IPSecConfiguration
  • class WireguardSDK: VPNSDK
  • struct WireguardConfiguration
  • class ComposedVPNSDK: NSObject
  • class ManualSwitchingVPNSDK: ComposedVPNSDK
  • class AutoSwitchingVPNSDK: ComposedVPNSDK
  • struct ComposedConfiguration
  • struct VPNGroupData
  • struct AuthMethod
  • enum AuthMethodType
  • struct User
  • struct Subscriber
  • struct Bundle
  • struct SubscriberPurchase
  • struct VirtualLocation
  • struct TrafficCounters
  • struct RemainingTraffic
  • protocol BaseNetworkExtensionDelegate
  • enum VPNSDKError
  • enum PartnerAPI.APIError
  • enum VPNTransportError
  • enum VPNTunnelError
  • VPNTunnelError.HydraInternalErrorCode
  • enum VPNLogShareHelper
  • enum RFC1918Result

Was this helpful?

  1. SDK
  2. Unified VPN SDK for Apple

API Reference

PreviousChangelogNextIPSEC VPN SDK for Apple

Last updated 2 days ago

Was this helpful?

Table of Contents

class VPNSDK: NSObject

static func sdkVersion() -> String

Version of SDK.

var protocolType: VPNProtocolType

VPN protocol type of SDK.

var deviceID: String

Device ID in string representation.

var carrierID: String

Carrier ID provided to SDK config.

var isLoggedIn: Bool

Checks if user is logged in.

var token: String?

Current access token if user is logged in.

var state: VPNState

Current state of VPN connection.

var connectedDate: Date?

Date when VPN connection was established.

var connectedServerCountry: String?

Country code of connected VPN server

var connectedServerCity: String?

City name of connected VPN server

var remoteConfig: RemoteConfig?

Last received remote config. Can be nil if remote config wasn't successfully received yet.

var trafficCounters: TrafficCounters?

Local traffic counters. Some SDKs can provide local counters directly from tunnel provider (e.g. Hydra), but it's not the case for every SDK type. For instance, IPSecSDK doesn't support local counters and this property will be populated only if you pass non-nil value for trafficCountersFetchInterval parameter to SDK configuration on init. Property also will be updated automatically after successful getTrafficCounters(completion:) call.

var lastTunnelError: VPNTunnelError?

Last error that occured in current/last app extension session. Always returns nil for IPSecSDK because app extension for this protocol is handled by Apple internally.

var isBypassEnabled: Bool

Checks is VPN in bypass mode.

var connectionFailureBehaviour: ConnectionFailureBehaviour?

Currect connection failure behaviour. If nil returned, it means that connection is started without any issues.

var clientNetworkList: ClientNetworkList?

Current CNL. SDK updates CNL as part of credentials loading.

var isIPInRFC1918Range: Bool

Indicates if the current device IP address falls into RFC1918 subnet range.

func login(method: AuthMethod, completion: @escaping UserCompletion)

Logins and obtains User object that describes VPN user. Returns User on success.

func logout(completion: @escaping LogoutCompletion)

Logouts current user.

func currentUser(completion: @escaping UserCompletion)

Gets current user data from server. Returns User on success.

func virtualLocations(completion: @escaping VirtualLocationsCompletion)

Gets a list of countries that you can connect to. Returns [VirtualLocation] on success.

func installProfile(completion: @escaping ProfileCompletion)

Triggers iOS VPN subsystem to create/update VPN profile, showing user permission "Allow / Don't Allow" dialog. Calling this method is not required. Useful for custom tutorial implementation. NOTE: If you're using onDemand VPN feature, this installed profile WILL be triggered by system and VPN will be enabled.

func removeProfile(completion: @escaping ProfileCompletion)

Removes previous installed system VPN profile. NOTE: VPN services with different protocols can use different VPN profiles (e.g., Hydra and IPSec), and this method will remove all installed profiles related to app.

func loadCredentials(location: VirtualLocation?, proxy: VirtualLocation?, completion: @escaping CredentialsCompletion)

Gets credentials for specified location and proxy. Usually you don't want to call this method manually, because it's called automatically as part of start flow. Parameters:

  • location: Virtual location provided by virtualLocations(completion) method. Pass nil or .optimal() to let SDK pick proxy automatically.

  • proxy: Virtual location provided by virtualLocations(completion) method. Proxy allows to connect to multiple VPN servers in chain and provides extra layer of encryption and IP address masking. Currently supported only by Hydra, for other protocols this parameter will be ignored. Pass nil to disable proxy. Pass .optimal() to let SDK pick proxy automatically.

  • completion: Handler that's called upon completion. Returns Credential on success.

func fetchRemoteConfig(completion: @escaping RemoteConfigCompletion)

Gets remote config from server. Last loaded config is accessible through remoteConfig property. Returns RemoteConfig on success.

func start(location: VirtualLocation?, proxy: VirtualLocation?, completion: @escaping StartStateCompletion)

Starts VPN with specified location and proxy. On first VPN connection, SDK will ask user to Allow or Deny VPN connection. Parameters:

  • location: Virtual location provided by virtualLocations(completion) method. Pass nil or .optimal() to let SDK pick proxy automatically.

  • proxy: Virtual location provided by virtualLocations(completion) method. Proxy allows to connect to multiple VPN servers in chain and provides extra layer of encryption and IP address masking. Currently supported only by Hydra, for other protocols this parameter will be ignored. Pass nil to disable proxy. Pass .optimal() to let SDK pick proxy automatically.

  • completion: Handler that's called upon completion. Returns Credential on success.

func stop(completion: @escaping StateCompletion)

Stops connected VPN.

func getTrafficCounters(completion: @escaping TrafficCountersCompletion)

Gets current traffic counters from server. Returns TrafficCounters on success.

func remainingTraffic(completion: @escaping RemainingTrafficCompletion)

Gets current traffic limits from server. Returns RemainingTraffic on success.

func purchase(purchaseToken: String?, type: String, completion: @escaping PurchaseCompletion)

Validates purchase on server and updates user data that related to subscription (e.g., limits). Returns Purchase on success.

class HydraSDK: VPNSDK

init(configuration: HydraConfiguration)

Designated initializer. SDK instance should be a singleton instance. Use HydraConfiguration type instance to initialize HydraSDK.

var configuration: HydraConfiguration

Passed Hydra configuration.

func applyLocationIfConnected(_ newLocation: VirtualLocation?, completion: @escaping ApplyLocationCompletion)

This function switches the location in the active network extension without killing and restarting it. It returns an error if the VPN is not currently connected. Changing the Virtual Location without killing the active network extension is supported only for Hydra and WireGuard protocols.

Warning:

  • The applyLocationIfConnected function will throw an error when used with the IPSec protocol. It is designed to work only with Hydra and WireGuard protocols.

  • It's important to note that iOS and macOS may have leaks by default, potentially exposing the device's real IP address even when the VPN tunnel is active. To prevent such leaks, set the includeAllNetworks flag to true. This ensures that all network interfaces are routed through the VPN, blocking any potential leaks through other interfaces. Setting includeAllNetworks = true is the only way to guarantee that no IP leaks occur while the tunnel is active.

func updateConfiguration(_ configuration: HydraConfiguration) throws

Updates Hydra configuration without creating a new instance of SDK. Configuration can't be updated if the connection is started, you need to call stopVPN function before updating configuration, otherwise VPNSDKError.updateWhileConnected error will be thrown. Please note if you want to change the main parameters of configuration (hostURL, carrierID, extensionBundleID, groupData), you need to create new instance HydraSDK with this configuration, otherwise VPNSDKError.configurationMismatch error will be thrown.

struct OnDemandConfiguration

isEnabled

Enables On Demand VPN feature. VPN will be triggered automatically by the System after startVPN is triggered. Calling stop from application is required to disable On Demand VPN. If VPN connection could not be established because of network environment or interrupted by out of traffic error code, then VPN will switch to bypass mode automatically until user reconnects VPN from main application, VPN icon will not be visible in the status bar.

onDemandRules

On demand rules to be used for the VPN connection.

struct NetworkConfiguration

tunnelDNSServers: [String]?

Your preferred DNS servers to use. If not set, a default ones will be used. Should be in format xxx.xxx.xxx.xxx (eg. 1.1.1.1).

struct BypassConfiguration

isBypassEnabled: Bool

Enables bypass mode.

bypassDomains: [String]?

A list of domains to bypass VPN. Wildcards accepted. Example: ["*google.com"] means that Google domain and it's subdomains will be accessed directly, without VPN.

bypassDNSServer: String?

A dns server to bypass VPN. Should be in format xxx.xxx.xxx.xxx (eg. 1.1.1.1).

struct ModulesConfiguration

debugLogging: Bool

Enables or disables debug logging. Don't forget to disable for release build!

isAnalyticsEnabled: Bool

Enables or disables internal event tracking (like start, stop, etc.).

isClientListEnabled: Bool

Indicates will CNL functionality take part in VPN connection logic.

isVPNProtocolLabelEnabled: Bool

Indicates VPN Protocol Label will be postfixed to the profile name or not.

struct HydraConfiguration

carrierID: String

Your unique service identifier.

extensionBundleID: String

Network Extension target's Bundle Identifier.

groupData: VPNGroupData

App group info that is used for data sharing.

profileName: String

Sets the name for VPN profile that is visible in iOS Settings > General > VPN (Title of profile, subtitle will always be the application name).

serverAddressDisplayName: String?

Sets the name for VPN server address that is visible in iOS Settings > General > VPN (Server field).

isVPNIconFixEnabled: Bool

Enables fixing of VPN Icon (LTE + VPN when on Wi-Fi) when it detects that it's broken.

onDemandConfiguration

On Demand configuration behaviour.

networkConfiguration

Network configuration.

bypassConfiguration

Bypass mode configuration.

modulesConfiguration

Modules configuration.

deviceType: String?

If value is nil, device type will be detected automatically. Otherwise provided value will be used. This string can be used as a parameter for some network requests.

class IPSecSDK: VPNSDK

init(configuration: IPSecConfiguration)

Designated initializer. SDK instance should be a singleton instance. Use IPSecConfiguration type instance to initialize IPSecSDK.

func updateConfiguration(_ configuration: IPSecConfiguration) throws

Updates IPSec configuration without creating a new instance of SDK. Configuration can't be updated if the connection is started, you need to call stopVPN function before updating configuration, otherwise VPNSDKError.updateWhileConnected error will be thrown. Please note if you want to change the main parameters of configuration (hostURL, carrierID, extensionBundleID, groupData), you need to create new instance IPSecSDK with this configuration, otherwise VPNSDKError.configurationMismatch error will be thrown.

struct IPSecConfiguration

carrierID: String

Your unique service identifier.

trafficCountersFetchInterval: TimeInterval?

Interval that will be used for timer that fetches traffic counters periodically and write it to trafficCounters property of SDK instance. Pass nil to disable the timer.

profileName: String

Sets the name for VPN profile that is visible in iOS Settings > General > VPN (Title of profile, subtitle will always be the application name).

onDemandConfiguration

On Demand configuration behaviour.

networkConfiguration

Network configuration.

bypassConfiguration

Bypass mode configuration.

modulesConfiguration

Modules configuration.

deviceType: String?

If value is nil, device type will be detected automatically. Otherwise provided value will be used. This string can be used as a parameter for some network requests.

class WireguardSDK: VPNSDK

init(configuration: WireguardConfiguration)

Designated initializer. SDK instance should be a singleton instance. Use WireguardConfiguration type instance to initialize WireguardSDK.

func setSessionPingInterval(_ newValue: TimeInterval?, completion: @escaping (Error?) -> Void)

Changes Wireguard session ping interval if VPN is connected. Returns error if VPN is not currently connected.

func updateConfiguration(_ configuration: WireguardConfiguration) throws

Updates Wireguard configuration without creating a new instance of SDK. Configuration can't be updated if the connection is started, you need to call stopVPN function before updating configuration, otherwise VPNSDKError.updateWhileConnected error will be thrown. Please note if you want to change the main parameters of configuration (hostURL, carrierID, extensionBundleID, groupData), you need to create new instance WireguardSDK with this configuration, otherwise VPNSDKError.configurationMismatch error will be thrown.

struct WireguardConfiguration

carrierID: String

Your unique service identifier.

extensionBundleID: String

Network Extension target's Bundle Identifier.

groupData: VPNGroupData

App group info that is used for data sharing.

profileName: String

Sets the name for VPN profile that is visible in iOS Settings > General > VPN (Title of profile, subtitle will always be the application name).

sessionPingInterval: TimeInterval?

Enables or disables internal event tracking (like start, stop, etc.). Fixed interval that will be used by timer that checks session state. If there is any error received during verification (for example, traffic exceeded), session will be closed with VPNTunnelError.invalidSession or VPNTunnelError.trafficExceeded error. When nil is passed, interval will be determined depending on session TTL.

serverAddressDisplayName: String?

Sets the name for VPN server address that is visible in iOS Settings > General > VPN (Server field).

onDemandConfiguration

On Demand configuration behaviour.

networkConfiguration

Network configuration.

bypassConfiguration

Bypass mode configuration.

modulesConfiguration

Modules configuration.

deviceType: String?

If value is nil, device type will be detected automatically. Otherwise provided value will be used. This string can be used as a parameter for some network requests.

class ComposedVPNSDK: NSObject

var activeProtocolType: VPNProtocolType

VPN protocol type of active SDK.

var deviceID: String

Device ID in string representation.

var carrierID: String

Carrier ID provided to SDK.

var isLoggedIn: Bool

Checks if user is logged in.

var token: String?

Current access token if user is logged in.

var state: VPNState

Current state of VPN connection. Gets corresponding property value from active SDK.

var connectedDate: Date?

Last connected date of active SDK.

var remoteConfig: RemoteConfig?

Last received remote config. Can be nil if remote config wasn't successfully received yet.

var trafficCounters: TrafficCounters?

Local traffic counters of active SDK.

var isBypassEnabled: Bool

Checks is VPN in bypass mode.

var connectionFailureBehaviour: ConnectionFailureBehaviour?

Currect connection failure behaviour. If nil returned, it means that connection is started without any issues.

var clientNetworkList: ClientNetworkList?

Current CNL. SDK updates CNL as part of credentials loading.

var isIPInRFC1918Range: Bool

Indicates if the current device IP address falls into RFC1918 subnet range.

var hydraConfiguration: HydraConfiguration?

Configuration of HydraSDK.

lastTunnelError(for protocolType: VPNProtocolType?) -> VPNTunnelError?

Last error that occured in current/last app extension session for specified protocol type. If protocolType is nil returns error for active protocol type. Always returns nil when protocolType is ipsec because app extension for this protocol is handled by Apple internally.

func login(method: AuthMethod, completion: @escaping UserCompletion)

Logins and obtains User object that describes VPN user. Login is shared between VPN SDKs with different protocols. Returns User on success.

func logout(completion: @escaping LogoutCompletion)

Logouts current user.

func currentUser(completion: @escaping UserCompletion)

Gets current user data from server. Returns User on success.

func virtualLocations(completion: @escaping VirtualLocationsCompletion)

Gets a list of countries that you can connect to. Returns [VirtualLocation] on success.

func installProfile(completion: @escaping ProfileCompletion)

Triggers iOS VPN subsystem to create/update VPN profile, showing user permission "Allow / Don't Allow" dialog. Calling this method is not required. Useful for custom tutorial implementation. NOTE: If you're using onDemand VPN feature, this installed profile WILL be triggered by system and VPN will be enabled.

func removeProfile(completion: @escaping ProfileCompletion)

Removes previous installed system VPN profile. NOTE: VPN services with different protocols can use different VPN profiles (e.g., Hydra and IPSec), and this method will remove all installed profiles related to app.

func loadCredentials(location: VirtualLocation?, proxy: VirtualLocation?, completion: @escaping CredentialsCompletion)

Gets credentials for specified location and proxy. Usually you don't want to call this method manually, because it's called automatically as part of start flow. Parameters:

  • location: Virtual location provided by virtualLocations(completion) method. Pass nil or .optimal() to let SDK pick proxy automatically.

  • proxy: Virtual location provided by virtualLocations(completion) method. Proxy allows to connect to multiple VPN servers in chain and provides extra layer of encryption and IP address masking. Currently supported only by Hydra, for other protocols this parameter will be ignored. Pass nil to disable proxy. Pass .optimal() to let SDK pick proxy automatically.

  • completion: Handler that's called upon completion. Returns Credential on success.

func fetchRemoteConfig(completion: @escaping RemoteConfigCompletion)

Gets remote config from server. Last loaded config is accessible through remoteConfig property. Returns RemoteConfig on success.

func start(location: VirtualLocation?, proxy: VirtualLocation?, completion: @escaping StartStateCompletion)

Starts VPN with specified location and proxy. On first VPN connection, SDK will ask user to Allow or Deny VPN connection. Parameters:

  • location: Virtual location provided by virtualLocations(completion) method. Pass nil or .optimal() to let SDK pick proxy automatically.

  • proxy: Virtual location provided by virtualLocations(completion) method. Proxy allows to connect to multiple VPN servers in chain and provides extra layer of encryption and IP address masking. Currently supported only by Hydra, for other protocols this parameter will be ignored. Pass nil to disable proxy. Pass .optimal() to let SDK pick proxy automatically.

  • completion: Handler that's called upon completion. Returns Credential on success.

func stop(completion: @escaping StateCompletion)

Stops connected VPN.

func getTrafficCounters(completion: @escaping TrafficCountersCompletion)

Gets current traffic counters from server. Returns TrafficCounters on success.

func remainingTraffic(completion: @escaping RemainingTrafficCompletion)

Gets current traffic limits from server. Returns RemainingTraffic on success.

func purchase(purchaseToken: String?, type: String, completion: @escaping PurchaseCompletion)

Validates purchase on server and updates user data that related to subscription (e.g., limits). Returns Purchase on success.

func applyLocationIfHydraConnected(_ newLocation: VirtualLocation?, completion: @escaping ApplyLocationCompletion)

Switches location in the active network extension (without killing it and starting new one). Returns error if VPN is not currently connected. NOTE: Does nothing if Hydra isn't active protocol.

func setWireguardSessionPingInterval(_ newValue: TimeInterval?, completion: @escaping (Error?) -> Void)

Changes Wireguard session ping interval if VPN is connected. Returns error if VPN is not currently connected. Does nothing if Wireguard isn't active protocol.

func updateHydraConfiguration(_ configuration: HydraConfiguration) throws

Updates Hydra configuration without creating a new instance of HydraDSK. NOTE Configuration can't be updated if the connection is started, you need to call stopVPN function before updating configuration, otherwise VPNSDKError.notPermitted error will be thrown. Please note if you want to change the main parameters of configuration (carrierID, extensionBundleID, groupData), you need to create new instance HydraSDK with this configuration, otherwise VPNSDKError.configurationMismatch error will be thrown.

func updateIPSecConfiguration(_ configuration: IPSecConfiguration) throws

Updates IPSec configuration without creating a new instance of SDK. Configuration can't be updated if the connection is started, you need to call stopVPN function before updating configuration, otherwise VPNSDKError.updateWhileConnected error will be thrown. Please note if you want to change the main parameters of configuration (hostURL, carrierID, extensionBundleID, groupData), you need to create new instance IPSecSDK with this configuration, otherwise VPNSDKError.configurationMismatch error will be thrown.

func updateWireGuardConfiguration(_ configuration: WireguardConfiguration) throws

Updates Wireguard configuration without creating a new instance of SDK. Configuration can't be updated if the connection is started, you need to call stopVPN function before updating configuration, otherwise VPNSDKError.updateWhileConnected error will be thrown. Please note if you want to change the main parameters of configuration (hostURL, carrierID, extensionBundleID, groupData), you need to create new instance WireguardSDK with this configuration, otherwise VPNSDKError.configurationMismatch error will be thrown.

func updateConfiguration(_ configuration: ComposedConfiguration) throws

Updates Composed configuration without creating a new instance of SDK. Configuration can't be updated if the connection is started, you need to call stopVPN function before updating configuration, otherwise VPNSDKError.updateWhileConnected error will be thrown. Please note if you want to change the main parameters of configuration (hostURL, carrierID, extensionBundleID, groupData), you need to create new instance ComposedVPNSDK with this configuration, otherwise VPNSDKError.configurationMismatch error will be thrown.

class ManualSwitchingVPNSDK: ComposedVPNSDK

init(configuration: ComposedConfiguration, initialProtocolType: VPNProtocolType)

Designated initializer. SDK instance should be a singleton instance. Use ComposedConfiguration type instance to initialize ManualSwitchingVPNSDK. Use initialProtocolType parameter to specify what VPN protocol should be active right after inititalization.

func switchToProtocol(_ newProtocolType: VPNProtocolType, completion: ((_ error: Error?, _ activeSDK: VPNSDK?) -> Void)?)

Switches VPN procolol type by user requirement. If VPN is connected at the moment of call, it will be stopped and then reconnected to the same location after protocol change. Returns new active SDK on success.

class AutoSwitchingVPNSDK: ComposedVPNSDK

init(manualSwitchingSDK: ManualSwitchingVPNSDK, priorityProvider: @escaping PriorityProvider)

Designated initializer. SDK instance should be a singleton instance. Use ManualSwitchingVPNSDK instance with corresponding config to initialize AutoSwitchingVPNSDK. Use priorityProvider parameter to specify which VPN protocol priority will be used during start flow.

struct ComposedConfiguration

availableTypes: ComposedConfiguration.SDKType

Available VPN protocols that will be used by Composed SDK. At least two different protocols should be provided.

carrierID: String

Your unique service identifier.

groupData: VPNGroupData

App group info that is used for data sharing.

trafficCountersFetchInterval: TimeInterval?

Interval that will be used for timer that fetches traffic counters periodically and write it to trafficCounters property of SDK instance. Pass nil to disable the timer. Works only for active SDKs that can't provide traffic counters directly from tunnel provider (e.g. IPSec).

profileName: String

Sets the name for VPN profile that is visible in iOS Settings > General > VPN (Title of profile, subtitle will always be the application name).

wireguardSessionPingInterval: TimeInterval?

Fixed interval that will be used by timer that checks wireguard session state. If there is any error received during verification (for example, traffic exceeded), session will be closed with VPNTunnelError.invalidSession or VPNTunnelError.trafficExceeded error. When nil is passed, interval will be determined depending on session TTL.

serverAddressDisplayName: String?

Sets the name for VPN server address that is visible in iOS Settings > General > VPN (Server field).

onDemandConfiguration

On Demand configuration behaviour.

networkConfiguration

Network configuration.

bypassConfiguration

Bypass mode configuration.

modulesConfiguration

Modules configuration.

isVPNIconFixEnabled: Bool

Enables fixing of VPN Icon (LTE + VPN when on Wi-Fi) when it detects that it's broken.

deviceType: String?

If value is nil, device type will be detected automatically. Otherwise provided value will be used. This string can be used as a parameter for some network requests.

struct VPNGroupData

Represents app group information that is used for data sharing.

groupID: String

App Group ID that is created for the current application.

usesSystemExtension: Bool

Pass true if you use system network extension on macOS. Pay attention that:

  • Shared user folder will be used for data storing in this case, but groupID should be provided anyway, that will provide unique folder name.

  • App sandbox capability should be disabled.

struct AuthMethod

static func anonymous() -> AuthMethod

Default auth method that does not require any authentication.

init(type: AuthMethodType, token: String?)

Main initializer. Use this initializator if you want to use non-anonymous auth method.

enum AuthMethodType

case anonymous

Allows to login without authentication.

case oauth

Most popular OAuth authentication method. OAuth flow should be implemented by your application. After finishing OAuth flow and obtaining OAuth access token, provide it to AuthMethod init function like this: AuthMethod(type: .oauth, token: "OAUTH_TOKEN")

case facebook

Authenticate with Facebook SDK.

case google

Authenticate with Google SDK.

case twitter

Authenticate with Twitter SDK.

case github

Authenticate with GitHub SDK.

case firebase

Authenticate with Firebase SDK.

case custom(String)

Custom auth. If you are using custom authentication scheme, use this case.

struct User

Describes VPN user.

let accessToken: String?

VPN SDK access token.

let subscriber: Subscriber

User's subscription information.

struct Subscriber

Describes user's subscription information.

let subscriberID: Int

Subscriber identifier.

let activatedDevices: Int

Subscriber activated devices.

let activeSessions: Int

Subscriber active sessions.

let name: String

Subscriber name.

let extref: String

let carrierID: String

Subscriber carrier ID.

let bundle: Bundle

Subscription bundle.

let socialProfiles: [String: String]

Subscriber hash of social profiles with information.

let purchases: [SubscriberPurchase]

Array of subscriber purchases.

struct Bundle

Describes subscription bundle information.

let licenseName: String

Name of user's license.

let bundleID: Int

Name of a purchased bundle.

let devicesLimit: Int

Number of devices limit.

let sessionsLimit: Int

Number of sessions limit.

struct SubscriberPurchase

Describes subscription information.

let id: Int

Subscription identifier.

let type: String

Subscription type on server.

let time: Date

Date of last subscription validation date. Usually server validates subscription 1 time per day.

let isActive: Bool

Checks is subscription currently valid and active.

struct VirtualLocation

Describes VPN server location information.

let type: LocationType

Location type from server: standard location, private group or profile.

let name: String?

Location name from server.

let description: String?

Location description from server.

let privateGroup: String?

Name of private server group name (can be empty).

let subdivision: String?

Subdivision name if provided.

let city: String?

City name if provided.

let countryCode: String?

Country location code if provided.

let country: String?

Country description based on country code.

let isAvailable: Bool

Determines could location be used.

let isOptimal: Bool

Determines is location optimal.

let isPrivate: Bool

Determines is location private.

let title: String?

Location's more suitable title.

static func optimal() -> VirtualLocation

Creates optimal location.

struct TrafficCounters

let received: UInt64

Bytes received in current session.

let transmitted: UInt64

Bytes transmitted in current session.

struct RemainingTraffic

Represents traffic limits information.

let sessionStartTime: UInt64

UNIX timestamp when current session was started.

let trafficUsageLimit: UInt64

Amount of bytes available to current User.

let trafficUsed: UInt64

Amount of bytes user utilized.

let trafficRemaining: UInt64

Amount of bytes that is available to User.

protocol BaseNetworkExtensionDelegate

Your app's Network Extension provider must implement this protocol. You can override methods from this protocol in order to be able to track certain actions like VPN start or errors inside Network Extension.

func vpnWillStart(with options: StartupOptions)

Called right before VPN start attempt.

public struct StartupOptions {
    public let isAppStart: Bool
    public let isOnDemand: Bool
    public let isStartedFromSleep: Bool

    /// ConnectionFailureBehaviour that is selected for the current start attempt. `nil` means success
    public let failureBehaviour: ConnectionFailureBehaviour?

    /// Errors from the previous on-demand sessions
    public let lastOnDemandConnectionErrors: [VPNTunnelError]
}

Options that can be applied to vpnWillStart function as call conditions.

func vpnDidStart()

Called after successful VPN start.

func vpnWillStop(withError error: VPNTunnelError?, availableRestartCompletion: ((_ shouldRestart: Bool) -> Void)?)

This method will be called with non nil availableRestartCompletion parameter if VPN is about to stop with an error. In this case until completion closure will be called, the extension will be in killswitch feature (no out/in going network packets will be delivered/received). If VPN is about to stop without any error, then this method will be called with nil availableRestartCompletion without killswitch feature. Parameter error: Tunnel error that caused stop. nil value means user initiated stop. Parameter availableRestartCompletion - if it's not nil, pass true to the completion block if you want to restart the VPN extension without killing and using the same delegate object, otherwise, the new delegate object will be created.

func vpnWillGoToSleep()

Called when current vpn session is going to sleep because of OS requirement.

func vpnWillWakeUpFromSleep()

Called when vpn session was waked up from sleep.

func vpnDidReceiveError(_ error: VPNTunnelError)

Called when VPN error occured. Do not call long-running async operations here as the process will shut down.

func vpnDidReceiveTrafficCounters(_ counters: TrafficCounters)

Called when VPN traffic counters did update.

enum VPNSDKError

Reflects various errors that can be thrown by SDK operations.

case emptyToken

Token is required for operation, but it's missing.

case invalidToken

Saved token is invalid.

case alreadyConnected

VPN is already connected.

case inProgress

Operation is already in progress.

case notConnected

VPN status isn't connected but it's required by operation.

case logoutWhileConnected

Logout attempt while VPN is connected.

case notPermitted

Operation isn't permitted by SDK.

case configurationMismatch

Static configuration properties were changed during dynamic reconfiguring.

case invalidConnection

Received connection data isn't valid.

case timeout

Connection start timeouted.

enum PartnerAPI.APIError

Reflects errors that can be thrown by operations with network call.

case unauthorized

This user is unauthorized or login operation is still pending.

case notAuthorized

The token of user is expired.

case vpnServerUnavailable

Selected server or country code is not available.

case userSuspended

This user is suspended.

case sessionExceed

Amount of allowed sessions for this user is exceed.

case trafficExceed

Amount of allowed traffic for this user is exceed.

case internalServerError

Server was unable to fetch credentials for this country code.

case deviceExceed

The amount of allowed devices for this user is exceed.

case invalidPurchase

The purchase could be validated.

case unknownServerResponse

This response could mean you don't have latest VPN SDK. Please report to developers.

case badRequest(message: String?)

Bad request server error.

case failedResult(resultString: String)

Result in server response wasn't successful, but error is unknown.

case networkError(Error)

Internet connection is not available or network request has failed. Feel free to try again.

case invalidCredentials

Credentials verification failed.

case sessionNotFound

Session with the specified ID doesn't exist on server or it's expired.

enum VPNTransportError

Reflects errors that can be thrown by VPN transport operations (like start, stop, app message sending, etc.).

case statusChangedToInvalid

Incorrect VPN status sequence.

case canceled

Connection attempt was canceled.

case unknown

Unknown error.

case connectFailed

General connection attempt error if nothing was reported by tunnel provider.

case startInProgress

Start is already in progress.

case stopInProgress

Stop is already in progress.

case timeout

Connection attempt timeout.

case wrapped(Error)

Wrapped error (usually from NetworkExtension framework)

case tunnelError(VPNTunnelError)

Error reported by tunnel provider.

case rateLimit

App messages rate limit reached.

case notConnected

VPN status isn't connected but it's required by operation.

case notReady

SDK is not ready to receive app message.

case unableToEncodeMessage

Failed to encode app message.

case emptyData

Received app message data is empty.

case unableToDecodeResponse

Failed to decode app message.

case appMessageFailureResult(reason: String)

App message sending failed with some reason.

enum VPNTunnelError

Reflects errors that can be thrown by custom tunnel provider from network extension side.

case notConfigured

VPN SDK is not configured properly.

case interfaceChange

Network interface was changed during connected state.

case tunInterfaceFailure

Failed to start packet flow.

case systemCalledStop

OS called stop.

case systemCalledSleep

OS called sllep.

case badConfiguration

Configuration decoding failed.

case connectionTimeout

Connection timeouted.

case connectionCanceled

Connection was canceled by user.

case hydraInternalError(code: Int, name: String?)

SDK has catched custom error from Hydra.

case failedToSetNetworkSettings

Can't prepare network settings.

case delegateRestrictsConnect

Can't connect because of invalid configuration.

case failedToReconfigure

Hydra reconfiguration initiated by user failed.

case unknown

Unknown error.

case authenticationFailure

Connection can't continue because of authentication failure.

case cryptoFailure

Data decoding/encoding failed.

case tlsFailure

Some TLS operation failed.

case dnsFailure

DNS related problem (usually resolution failed).

case connectionCouldNotBeEstablished

Connection process was aborted by some other reason (e.g. routing error, server shutdown).

case invalidSession

Current session has become invalid.

case trafficExceeded

VPN connection disrupted because the user is out of traffic. NOTE: If on-demand feature is used, VPN will be switched to bypass mode until user disconnects VPN connection from the application.

case credentialsLoadingFailure(debugDescription: String)

Credentials loading failed on the tunnel provider side. debugDescription value is provided here for debug reason, it shouldn't be displayed as error message to user.

VPNTunnelError.HydraInternalErrorCode

Some codes for case hydraInternalError(code: Int, name: String?)

connectionDisrupted = 181

VPN connection disrupted by broken network connection.

connectionNotEstablished = 182

VPN client can't connect to VPN node.

tokenInvalid = 186

VPN is not established due to application error.

enum VPNLogShareHelper

Provides API for VPN debug logs sharing.

static func presentActivity(withGroupID groupID: String, usesSystemExtension: Bool, from viewController: UIViewController)

Direct sharing method for iOS. Sharing activity will be presented from passed view controller.

static func presentActivity(withGroupID groupID: String, usesSystemExtension: Bool, from sender: NSView)

Direct sharing method for macOS. Sharing activity will be presented below passed view.

static func allLogFileURLs(withGroupID groupID: String, usesSystemExtension: Bool) -> [URL]

Method returns log file URLs without any sharing activity presenting.

enum RFC1918Result

Provides result of RFC1918 detection

inRange

Indicates that current IP address of interface falls into RFC1918 range.

outOfRange

Indicates that current IP address of interface out of RFC1918 range.

invalid

Indicates that SDK unable to get or verify the current network interface ip address.

VPNSDK
HydraSDK
HydraConfiguration
IPSecSDK
IPSecConfiguration
WireguardSDK
WireguardConfiguration
ComposedVPNSDK
ManualSwitchingVPNSDK
AutoSwitchingVPNSDK
ComposedConfiguration
AuthMethod
AuthMethodType
User
Subscriber
Bundle
SubscriberPurchase
VirtualLocation
TrafficCounters
RemainingTraffic
BaseNetworkExtensionDelegate
API error
VPNTunnelError
HydraInternalErrorCode