# Integrate the VPN SDK

## Prerequisites

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

## 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](/guides/getting-started.md) and [User SDK](/guides/users/integrate-the-user-sdk.md) (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](/guides/getting-started.md), [User SDK](https://docs.sudoplatform.com/guides/users/integrate-the-user-sdk) and [Sudo Entitlements SDK](/guides/entitlements.md) (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 VPN Client interfaces.

After registering the client with the VPN service, you can verify whether the current device has successfully completed registration using the `sudoVpnClient.isRegisteredWithService()` API. This API will return:

* `true` if the device has successfully completed registration with the VPN service.
* `false` if registration has not yet completed or the service is still reconciling provisioning state.

## Entitlement Redemption

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.sudoplatform.com/guides/virtual-private-network/integrate-the-vpn-sdk.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.