# Application Setup

The first step in the process is to configure your application target. This involves modifying your app's build settings, linking necessary libraries, and ensuring that your app has the required permissions and entitlements to utilize the VPN functionality.

## Installing the SDK

### Create Xcode Project

To get started, create a new Xcode application project for either iOS or macOS.

{% hint style="info" %}
**Xcode Version Requirement**

Xcode 16.1 or later is required for developing with the Unified VPN SDK.
{% endhint %}

### Add SDK to Project

The VPN SDK is provided as an `xcframework`, enabling compatibility with both iOS and macOS applications. Follow these steps to install the SDK in your Xcode project:

1. Open your Xcode project and navigate to the project settings:
   * In the project navigator, select your project at the top of the list.
   * Select your application target in the targets list.
   * Switch to the "General" tab.
2. Locate the `VPNApplicationSDK.xcframework` file on your system.

   <figure><img src="/files/Fyuo9S2jjDnFUqF3Y4ud" alt=""><figcaption></figcaption></figure>
3. Drag the `VPNApplicationSDK.xcframework` file from its location into the "Frameworks and Libraries" section of your target's "General" settings tab.

   <figure><img src="/files/iAWOuTW0eGrtV6ov82Aa" alt=""><figcaption></figcaption></figure>

   <figure><img src="/files/A3gFSFOWfAzGOPNRdcIA" alt=""><figcaption></figcaption></figure>
4. Verify that the "Embed" option for the newly added framework is set to "Embed & Sign".
   * This ensures that the framework is properly embedded and signed within your application bundle.

### Configure Build Settings

A few build settings need to be adjusted for the VPN SDK to work properly:

1. In Project -> App Target -> Build Settings:

* Set "Enable Bitcode" to NO. This option is [deprecated](https://developer.apple.com/documentation/xcode-release-notes/xcode-14-release-notes).
* Add the flag `-ObjC` to "Other Linker Flags"

2. Link the NetworkExtension system framework to your application target.

<figure><img src="https://lh7-rt.googleusercontent.com/slidesz/AGV_vUfXBFyw6z9hYPDq8Gve8wk5nyRkxkQjJcbj5pTkPAkBbJawGxgANak6_9zpiQBiTMBXR8y0SVqV-N2iOqM2f1ni_ZeDfhgSmQzAyAcSh5piRVaFXdqFk5v3WtXKpCXB0ViCRZJYAMEISzb-bCBASCgOAQR9ldV_=s2048?key=8lLFSmMU2eWkt_-3cXyC3w" alt=""><figcaption></figcaption></figure>

<figure><img src="https://lh7-rt.googleusercontent.com/slidesz/AGV_vUc5C9AdbVdZHgwBH0wv1d6MmzAsezwzrqBpdW-hWAvTBo4fAC_3afxgIDg7o_8haMoDgYnXEWQlS9GulC4dIG4DIerlvweGG571NBu4Qtz6zu9w6ldO18eE5HYzzKFMJ-UAp32wLQOJo8lTC74utTT6_D7rOFg=s2048?key=8lLFSmMU2eWkt_-3cXyC3w" alt=""><figcaption></figcaption></figure>

### Add OpenSSL Dependency

The SDK relies on the OpenSSL library. Add it to your project using Swift Package Manager:

1. In Xcode, go to File -> Add Packages...
2. Enter the OpenSSL package URL: `https://github.com/krzyzanowskim/OpenSSL.git`

For more information, please see <https://github.com/krzyzanowskim/OpenSSL>

3. Link the OpenSSL package to your application target.

<figure><img src="https://lh7-rt.googleusercontent.com/slidesz/AGV_vUf41iUkCREmPdkxP80fgjbU_4FxkG2eCmVSfDc1W_9dYXaGE5chY9v-tUhiK31YUt3vttgnG3B12gp7MeGf0YMqS4SWhz2M26HgAzVICsLJUc_Xik-78I7ZN4w04TvkHIs38caTH6rEEjx7MYkTg9wQpBQsw5sX=s2048?key=8lLFSmMU2eWkt_-3cXyC3w" alt=""><figcaption></figcaption></figure>

<figure><img src="https://lh7-rt.googleusercontent.com/slidesz/AGV_vUcoq8S0csDQ8CVmXyBa9KfJf6VxJ7Ziky5IViykMANUpMGa7sVgq6ngu3MTYFYPKQWze_OVTe5FtfjcAZsJgSwtAqNoK1JBa1Ygy4brcJ90YjCwwkccJboxsuyUpjO_hnvpxHUeW2x8BKAxOnYMzX7jIgCJ656-=s2048?key=8lLFSmMU2eWkt_-3cXyC3w" alt=""><figcaption></figcaption></figure>

<figure><img src="https://lh7-rt.googleusercontent.com/slidesz/AGV_vUemX1xlv-1JVsQrqyIYozp1kVR_QKTKrx5aYuHgPvcBMs2uRGR86wJscy2mN4zQD49J5AZDe4je5tvTzs0S9PqoV2hVa8lWiiPRQCJIyGvvfbjxyCcrvQESgQn8NT4Naf7VWefv-yYk5BP4n0fvq-hMTn6jv0Hp=s2048?key=8lLFSmMU2eWkt_-3cXyC3w" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/IP2H4147vo88aqVNE16k" alt=""><figcaption></figcaption></figure>

## Configure App ID and Capabilities

### Developer Portal Setup

On the [Apple Developer portal](https://developer.apple.com/), go to Certificates, Identifiers & Profiles -> Identifiers.

Create a new App ID for your application or use an existing one. Enable the "Personal VPN" capability for this App ID.

* Access WiFi Information
* App Groups
* Network Extensions
* Personal VPN

<figure><img src="/files/ttFon92Ljufar0Vl4UrK" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/Axp5sjnyV801eee8tUgj" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/GTmZPa3d7p99vnxH2VCv" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/gXE8Dw0c3FVAhbruvSoQ" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/hizKjDMOIVygWvchzKF3" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
**Apple Developer Account**

If you already have an Apple Developer ID, you can skip this step.

Why do you need an Apple Developer Account:

You need to join the Apple Developer Program to access the necessary tools and resources for developing, testing, and distributing your app on the App Store, ensuring it meets Apple's security and quality standards. You will need to get the paid version of an Apple Developer account to be able to sign and publish your app.

Here is a link to the broad overview from Apple of the resources you will get when you join the Apple Developer program: <https://developer.apple.com/programs/>

Here is a link that gets more specific on the need for an Apple Developer program in regards to distributing software to Apple devices: <https://developer.apple.com/support/developer-id/>

Follow this link to set up an Apple Developer Account: <https://idmsa.apple.com/IDMSWebAuth/signin>
{% endhint %}

### Xcode Project Capabilities

Back in your Xcode project, go to Project -> App Target -> Signing and Capabilities.

Add the following capabilities to your application target:

* Personal VPN
* App Groups

<figure><img src="/files/sPorRLhLNpVMuQzTXb1Y" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/vIunnYyAuDCWMTzkaeI2" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/XXr6gq4jfpo75tgdt5H7" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/fDmArURXL6Dauk2JrINJ" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/elhzTL1EyhA46RRvsJlC" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/McL7JEYgIqflSHAE6hCi" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/RN7hE41QJX1UUa79qkuC" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/3qOmi3dGtumUsv97EzxO" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/ZB7QTVsJOoh3GsEN0G2o" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/YhX0ZRSx99jwX5KScx94" alt=""><figcaption></figcaption></figure>

For macOS targets, enable Keychain Sharing capability with your Group ID. To learn more about this process, please see [Configuring Keychain Sharing](https://developer.apple.com/documentation/xcode/configuring-keychain-sharing)

{% hint style="info" %}
For macOS targets, also enable the Keychain Sharing capability using your App Group ID.
{% endhint %}

## Integration Checklist

To ensure the VPN SDK is set up correctly, verify the following:

* [ ] `VPNApplicationSDK.framework` is added to the application target
* [ ] "Enable Bitcode" is set to "No"
* [ ] `-ObjC` flag is present in "Other Linker Flags"
* [ ] Personal VPN capability is enabled for both the App ID and application target
* [ ] App Groups capability is enabled
* [ ] OpenSSL package is linked to the application target
* [ ] Keychain Sharing is enabled for macOS targets

<table><thead><tr><th width="237">Category</th><th>Description</th></tr></thead><tbody><tr><td>Application Target</td><td>Ensure it is created</td></tr><tr><td>Frameworks</td><td>VPNApplicationSDK.framework is added to the application target</td></tr><tr><td>Build Settings</td><td><p>-ObjC flag is present in "Other Linker Flags"</p><p><br></p></td></tr><tr><td>OpenSSL</td><td>OpenSSL package is added via Swift Package Manager using URL: NEED PROPER PACKAGE AND URL</td></tr><tr><td>Apple Developer Portal</td><td>You have created an Apple Developer Portal Account</td></tr><tr><td>Identifiers</td><td><p>On the Apple Developer Portal, you have created an Application Identifier with the following enabled:</p><ul><li>Access Wi-Fi Information</li><li>App Group</li><li>Network Extensions</li><li>Personal VPN</li></ul></td></tr><tr><td>Xcode Project Capabilities</td><td><p>You have enabled the following within the Application Target:</p><ul><li>App Group</li><li>Access Wi-Fi Information</li><li><p>Network Extensions</p><ul><li>Packet Tunnel</li></ul></li></ul></td></tr><tr><td>Keychain</td><td>Keychain Sharing is on for macOS targets</td></tr></tbody></table>

{% hint style="info" %}

* Bitcode is now deprecated.
  {% endhint %}

## Uninstalling the SDK

This guide describes the steps and considerations for fully uninstalling the VPN SDK from your application. With these steps, you can ensure a complete removal of the SDK and its associated data when your app is uninstalled. Proper cleanup prevents unused data from being left behind on the user's device.

### Uninstalling the SDK in macOS

To fully uninstall the VPN SDK in macOS:

1. Remove any app-specific data, configurations, and credentials related to the SDK.
2. Delete the keychain item created for the SDK's `deviceUUID` using the `security` command:

`security delete-generic-password -s com.anchorfree.vpnsdk.deviceUUID`

Alternatively, you can delete the keychain item manually by opening the Keychain Access app, then search for the `com.anchorfree.vpnsdk.deviceUUID` item.

3. Remove the following directories and files associated with the app and SDK:

```sh
#!/bin/sh

ID='your-app-bundle-id'
HYDRA_ID='your-ne-app-bundle-id'
WG_ID='your-wg-ne-app-bundle-id'
APP='your-app-name'
GROUP='your-group-id' # (e.g. 3TH5R7YS88.group...)

defaults delete $ID
defaults delete $HYDRA_ID
defaults delete $WG_ID

sudo rm -rf "/Applications/$APP"
sudo rm -rf ~/Library/Containers/$ID*
sudo rm -rf ~/Library/Group\ Containers/$GROUP*
sudo rm -rf ~/Library/Caches/$ID
```

* The main application bundle: `/Applications/APP_NAME`
* The app's container: `~/Library/Containers/APP_BUNDLE_ID`
* The app group container: `~/Library/Group Containers/APP_GROUP_ID`
* The app's cache: `~/Library/Caches/APP_BUNDLE_ID`

{% hint style="info" %}

* Please note that the script will require you to input your admin password when running the sudo commands to execute tasks with elevated privileges.
* Alternatively, you can create a non-sudo version of the script that will not remove everything, but only files and directories accessible without elevated privileges. This approach allows you to clean up certain areas of the system without requiring admin rights.
* The provided shell script for app deletion is intended as a debugging tool and cannot be automatically invoked upon app deletion. The script serves as an optional resource for developers who want to ensure that all app-related data and settings are thoroughly removed, particularly on macOS.
* On iOS, the operating system automatically removes all app settings and data when an app is deleted. However, on macOS, some residual data may persist after app deletion. In such cases, running the provided script manually can help ensure a complete cleanup.
* For complete data deletion of production accounts, please contact our support team.
  {% endhint %}

### Uninstalling the SDK in iOS

To fully uninstall the VPN SDK in iOS:

**Remove any app-specific data, configurations, and credentials related to the SDK.**

Note:

* When an app is uninstalled by the user, the system automatically deletes all associated app data, including stored files. However, the app deletion process does not remove keychain data. Currently, there is no mechanism for an app to detect its own deletion or execute any clean-up logic during the uninstallation process.
* The SDK stores only the `com.anchorfree.vpnsdk.deviceUUID` item in the keychain, which may persist after app deletion (this behavior is subject to change).

  If your app relies on the deletion of this item, consider tying it to an encryption key stored in the app bundle - this will effectively render the keychain item inaccessible once the app is removed.

  Alternatively, users can manually locate this keychain item using the service name `com.anchorfree.vpnsdk.deviceUUID` and remove it from their keychain if desired.

### Considerations

Most of the data associated with the VPN SDK is generated and stored by the client application rather than the SDK itself. Therefore, the app developer is responsible for cleaning up this data as part of the uninstallation process. This includes:

* Removing any stored parameters, configurations, or credentials used with the SDK
* Deleting keychain items created for the SDK (see platform-specific details above)
* Removing any other persisted SDK-related data from the app's storage


---

# 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://pango.gitbook.io/paas/sdk/unified-vpn-sdk-for-apple/setup/application-setup.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.