# Integrate the VPN SDK

## Prerequisites

1. [Complete the Getting Started Guide](https://docs.sudoplatform.com/guides/getting-started)
2. [Integrate the User SDK](https://docs.sudoplatform.com/guides/users/integrate-the-user-sdk)
3. [Integrate the Entitlements SDK](https://docs.sudoplatform.com/guides/entitlements/end-user-api/integrate-the-entitlements-sdk)

## Get Started

* [Integrate the iOS SDK](#integrate-the-ios-sdk)
* [Integrate the Android SDK](#integrate-the-android-sdk)
* [Integrate the JS SDK](#integrate-the-js-sdk)

## Integrate the iOS SDK

{% hint style="success" %}
To gain access to the iOS SDK and iOS sample app providing a reference for integrating the SDK, please [contact us](https://sudoplatform.com/#lets-chat)..
{% endhint %}

{% hint style="warning" %}
Apple Macs running on Apple Silicon are currently not supported. This means that iOS simulators on these machines are currently not supported.

Use either a real device, or an Intel Mac system for Sudo Platform VPN application development.
{% endhint %}

{% hint style="warning" %}
**It is recommended to use a real iOS device as the simulator does not support VPN configurations.**
{% endhint %}

### Client Initialization

{% hint style="info" %}
When setting up, ensure that you include a `PersonalVPN`entitlement capability on the application id.
{% endhint %}

To instantiate a client in your application, add the following

{% tabs %}
{% tab title="Swift" %}

```swift
import SudoVPN

let userClient = // ... see "Users" docs

do {
    let vpnClient = DefaultSudoVPNClient(userClient: userClient)
} catch {
    // Handle initialization error. An error might be thrown due to invalid
    // or missing configuration file.
}
```

{% endtab %}
{% endtabs %}

{% hint style="success" %}
You only need one client instance for a given user per device. Instantiating multiple clients with the same configuration and using them at the same time may cause unexpected runtime errors to occur.
{% endhint %}

### Client Preparation

To ensure that the correct data is returned from API calls in the iOS client, please ensure that the prepare method is called.

{% hint style="warning" %}
This method must be called once after the following sequence **\*\*has occurred: registration, sign in, and redeem entitlements**.\*\* This method must be called on each initialized VPN Client.
{% endhint %}

To call the prepare method:

```swift
vpnClient.prepare { result in
    switch result {
    case .success:
        // Handle success result
    case .failure(let error):
        // Handle failure result
}
```

### User Sign Out

To prevent re-use of user credentials, when the user signs out of the VPN application, ensure that the iOS profile is uninstalled.

{% tabs %}
{% tab title="Swift" %}

```swift
import SudoVPN

do {
    if try await vpnClient.isProfileInstalled() {
        try await vpnClient.uninstallProfile()
    }
} catch {
    // errors returned specifically by the profile management interface include:
    // SudoVPNError.profileStale: the profile has been changed since last read
    // SudoVPNError.profileReadWriteFailed: the system was unable to read or write the profile
    // SudoVPNError.unknown: an unexpected or unknown error occurred when uninstalling the profile (includes an error message)
}
try await userClient.signOut()
```

{% endtab %}
{% endtabs %}

## Integrate the Android SDK

The Android SDK is compatible with Android 6 (API level 23) and above.

{% hint style="success" %}
To gain access to the Android SDK and Android sample app providing a reference for integrating the SDK, please [contact us](https://sudoplatform.com/#lets-chat).
{% endhint %}

### Client Initialization

{% hint style="info" %}
In order to instantiate a VPN client, make sure you have followed instructions for [Getting Started](https://docs.sudoplatform.com/guides/getting-started) and [User SDK](https://docs.sudoplatform.com/guides/users/integrate-the-user-sdk) (see Prerequisities above)
{% endhint %}

To instantiate a client in your application, add the following:

{% tabs %}
{% tab title="Kotlin" %}

```kotlin
val userClient = // ... see "Users" docs

val vpnClient = SudoVPNClient.builder()
    .setContext(appContext)
    .setSudoUserClient(userClient)
    .build()
```

{% endtab %}
{% endtabs %}

{% hint style="warning" %}
You only need one client instance for a given user per device. Instantiating multiple clients with the same configuration and using them at the same time may cause unexpected runtime errors to occur.
{% endhint %}

## Integrate the JS SDK

{% hint style="success" %}
To gain access to the JS SDK for use on Windows or MacOS (Intel or Apple silicon), please [contact us](https://sudoplatform.com/#lets-chat).
{% endhint %}

### Client Initialization

{% hint style="info" %}
When setting up on macOS, ensure that you include a `PersonalVPN`entitlement capability on the application id.
{% endhint %}

To use the VPN SDK in a Web or Node.js project, you must add `@sudoplatform/sudo-vpn` and `@sudo-platform/sudo-vpn-provider` as dependencies to your project. This provider package provides native binaries for 64-bit Windows, and Intel and Apple silicon macOS.

<pre><code><strong>yarn add '@sudoplatform/sudo-vpn'
</strong><strong>yarn add '@sudoplatform/sudo-vpn-provider'
</strong># or
npm install --save '@sudoplatform/sudo-vpn'
npm install --save '@sudoplatform/sudo-vpn-provider'
</code></pre>

In order to instantiate a VPN client, make sure you have followed instructions for [Getting Started](https://docs.sudoplatform.com/guides/getting-started), [User SDK](https://docs.sudoplatform.com/guides/users/integrate-the-user-sdk) and [Sudo Entitlements SDK](https://docs.sudoplatform.com/guides/entitlements) (see [Prerequisites](#prerequisites) above).

To instantiate and initialize a client in your application, add the following:

{% tabs %}
{% tab title="Typescript" %}

```typescript
import { DefaultSudoVPNClient } from '@sudoplatform/sudo-virtual-cards'
import { DefaultSudoKeyManager } from '@sudoplatform/sudo-common'
import { DefaultSudoUserClient } from '@sudoplatform/sudo-user'
import { WebSudoCryptoProvider } from '@sudoplatform/sudo-web-crypto-provider'
// OR
import { NativeSudoCryptoProvider } from '@sudoplatform/sudo-native-crypto-provider'

const sudoUserClient = new DefaultSudoUserClient(/* refer to Users documentation */)
const sudoKeyManager = environment == 'web' ? /* if using browser 'secure storage' */
    new WebSudoCryptoProvider('your.keymanager.namespace', 'your.servicename') :
    new NativeSudoCryptProvider('your.keymanager.namespace', 'your.servicename')
const logPath = 'your path to log files'

const vpnClient = new DefaultSudoVpnClient({
    userClient,
    logPath,
    sudoKeyManager
)
```

{% endtab %}
{% endtabs %}

{% hint style="warning" %}
You only need one client instance for a given user per device. Instantiating multiple clients with the same configuration and using them at the same time may cause unexpected runtime errors to occur.
{% endhint %}

### Client Preparation

Once the user has been entitled, call `sudoVpnClient.registerWithService()` to complete the registration process and permit access to all vpnClient interfaces.

## Entitlement Redemption

Before VPN SDK APIs can be called, the user must be entitled. To ensure the user is entitled first call the [`redeemEntitlements`](https://docs.sudoplatform.com/guides/entitlements/end-user-api/redeeming-entitlements) API in the Sudo Entitlements SDK.