Setting up the SDK

First steps before working with the SDK

Install the Kape Client SDK

Cloudsmith is used to provide ready-made packages and frameworks for different platforms. Cloudsmith acts as a package manager. Please consult the Cloudsmith documentation to learn how to configure Cloudsmith as a package manager in your environment.

The URL of our Cloudsmith repository is:

https://cloudsmith.io/~expressvpn/repos/kp_client_sdk/

Furthermore, there is a repository with "Unstable Nightly Builds" at:

https://cloudsmith.io/~expressvpn/repos/kp_client_sdk_unstable/

The use of the Unstable Build is at your own risk. Generally, we recommend using this only during the development of new features as an early preview to gather feedback on design and stability. An Unstable Build should never be used in a production environment.

The following environments are currently supported:

• Kotlin and Maven packages

• Swift and Swift Package Manager

• C# and NuGet packages

• Go and Go Package Manager

• C/C++ as Raw Binary

Configure and Initialize

The SDK Manager serves as the core hub of the SDK, handling dependencies, configurations, and offering interfaces to access various SDK modules.

Here's a detailed guide for setting up and initializing the SDK step-by-step.

1

Implementing Callback Interfaces

The SDK is cross-platform, but it relies on native apps for specific functionalities. For example, it uses the platform's native secure storage, like Apple's Keychain, to securely store sensitive information such as tokens. It will use a callback interface, to let the native apps implement the storage.

StorageCallackProtocol

Apps need to implement the StorageCallbackProtocol to let the SDK securely store credential information such as Authorization Tokens.

Swift

public protocol StorageCallbackProtocol : AnyObject {
    func storeData(storageId: String, data: Data) throws
    func retrieveData(storageId: String) throws -> Data?
}

Kotlin

Parameter	Description
storageId	Unique id for this storage item
data	Data to be stored

In case there is a problem to access the storage, the app must return a SdkException.Storage exception.

LogCallbackProtocol

Additionally apps can provide the LogCallbackProtocol to receive log events from the SDK process them.

Swift

public protocol LogCallbackProtocol : AnyObject {
   func log(logLevel: CallbackLogLevel, 
            category: String, 
            file: String, 
            line: UInt32, 
            message: String) throws
}

Kotlin

Parameter	Description
logLevel	LogLevel of that event
category	A category this event belongs to
file	Source File name this log line got triggered
message	The log message

StateCallbackProtocol

The primary use case for implementing this protocol is to receive notifications about specific state changes within the SDK. For instance, if the SDK detects that credentials have expired, prompting the user to log in again, it checks whether the state equals LibState::LoggedOut. The method can return whether the SDK should proceed in certain states; for example, when encountering LibState::LoggedOut, simply return true.

Swift

public protocol StateCallbackProtocol : AnyObject {
    func processState(state:LibState)->bool throws
}

Kotlin

2

Creating the Base Configuration

After having implemented the callback clients, you can continue to setup a base configuration.

For internal logging reasons, you will need to call setClientDetails providing an object with details about your app.

ClientDetails

Property	Type	Description
os	One of the following variants: Ios Android MacOs Windows Linux Aircove BrowserExtension	The operating system of the client.
os_version	String	The version of the Operating System
app_version	String	The version of the app
device_model	Option<String>	The model of the device e.g. "iPhone 16 Pro Max", if available.
open_id_client_id	Option<String> Required when using OpenID Authentication!	This is the OpenID client id in case you will use OpenID to authenticate the SDK. This makes sure, that the SDK can internally refresh tokens properly.

Cache File Path

The SDK will internally cache few information, like responses and other things using a file cache. Apps need to provide a location, which is read- and writable. That folder must already exist.

Swift

let sdkConfiguration = Configuration()
sdkConfiguration.setClientDetails(details: clientDetails)
//This might throw an exception in case the path is invalid or not writable
try sdkConfiguration.setCacheFilePath(cacheFilePath: <Path>)
//Activate the SDK License
try sdkConfiguration.setLicense(license:"Content of the License File we provided to you")
 
// Register the Callbacks
sdkConfiguration.setStorageCallback(callback: StorageClient())
sdkConfiguration.setLogCallback(callback: LogClient())

Kotlin

3

Loading Configuration Details

You will be provided with a custom configuration file, which contains additional configuration settings required for your specific implementation. Once you created the base configuration, you must load these additional details.

You might later adjust the log level using set_max_log_level .

Swift

sdkConfiguration.loadFromYaml(yamlContent: "content of the YAML configuration file")

Kotlin

4

Initializing the SDK Manager

Now we can continue and initialize the SDK Manager.

Swift

kapeSdkManager = try SdkManager(configuration: sdkConfiguration)

Kotlin

5

Authenticating the SDK

Before being able to call most of the methods in the SDK, the SDK needs to be authenticated, move on to the Authentication Module, to learn, which Authentication Method you need to use.