Skip to main content

Getting Started

This guide walks you through the complete flow: initializing the SDK, authenticating, browsing VPN servers, and establishing a VPN connection.

1. Initialize the SDK​

All configuration lives in res/xml/kape_sdk_settings.xml (see Installation). Initialization is three lines:

import com.kape.platformsdk.core.KapeSDKSettings
import com.kape.platformsdk.core.KapeSdkHandle
import com.kape.platformsdk.auth.KapeAuthClient

val settings = KapeSDKSettings.fromXml(context, R.xml.kape_sdk_settings)
val handle = KapeSdkHandle(settings, context)     // initializes the Low Level SDK
val auth = KapeAuthClient(handle)

Keep handle alive for the lifetime of your app (e.g. in your Application class or a singleton). All other SDK objects reference it.

2. Authenticate​

import com.kape.platformsdk.auth.LoginResult

// In a coroutine (e.g. viewModelScope.launch):
when (val result = auth.login(context)) {
    is LoginResult.Success -> { /* navigate home */ }
    is LoginResult.AuthCancelled -> { /* user dismissed */ }
    is LoginResult.AuthError -> { /* handle result.message */ }
}

// Check the session after login — displayName is null when there is nothing to show (a guest, say)
val session = auth.currentAuthenticationSession()
if (session != null) {
    println("Logged in as ${session.displayName ?: "an unnamed user"}")
}
warning

Your AndroidManifest.xml must declare an intent filter for net.openid.appauth.RedirectUriReceiverActivity with your redirect URI scheme. The OpenID Connect redirect will not complete otherwise. See Authentication for the required declaration.

3. Observe Auth State​

import com.kape.platformsdk.core.KapeAuthState

viewModelScope.launch {
    auth.authState.collect { state ->
        when (state) {
            is KapeAuthState.Authenticated -> showHome()
            is KapeAuthState.Unauthenticated -> showLogin()
            is KapeAuthState.Initializing -> showLoading()
        }
    }
}

4. Subscription​

Nothing to call: the handle activates a VPN subscription itself, off the authentication change, and every SDK call waits for that pick to settle. To check for one before using VPN features:

handle.awaitSdkManager()
val active = handle.activeSubscriptionId.isNotEmpty()

5. Browse VPN Locations​

The location list is scoped to the VPN protocol, so it comes from the VPN manager:

import com.kape.platformsdk.vpn.KapeVpnManager
import com.kape.platformsdk.vpn.lightway.bridge.KapeLightwaySupport
import com.kape.platformsdk.vpn.openvpn.bridge.KapeOpenVpnSupport
import com.kape.platformsdk.vpn.wireguard.bridge.KapeWireGuardSupport

val vpn = KapeVpnManager(
    handle,
    protocols = listOf(KapeWireGuardSupport, KapeLightwaySupport, KapeOpenVpnSupport),
)

val locations = vpn.createLocationService()
locations.fetchLocations()

// Locations grouped by continent
locations.locationsByContinent.value.forEach { (continent, servers) ->
    println("$continent:")
    servers.forEach { println("  ${it.name} (${it.country})") }
}

6. Connect to VPN​

Reuse the vpn manager from step 5.

import com.kape.platformsdk.vpn.KapeConnectionMode

// Grant one-time system VPN consent (shows a dialog on first use)
// prepare(...) must be called from an Activity context (see VPN > Connecting)
val consentIntent = vpn.prepare(activity)
if (consentIntent != null) {
    consentLauncher.launch(consentIntent)   // an ActivityResultLauncher
}

// Connect — auto picks the highest-rated location, or pass a specific id
vpn.connect(KapeConnectionMode.Auto)

// Observe connection status
viewModelScope.launch {
    vpn.connectionStatus.collect { status ->
        println(status) // Connecting, Connected, Disconnecting, Disconnected
    }
}
info

prepare(...) returns an Intent only when consent is required (null if already granted). Launch it from an ActivityResultLauncher and call connect(...) once the result is RESULT_OK. See Connecting for the full pattern.

7. Disconnect​

vpn.disconnect()

8. Log Out​

auth.logout()

Example App​

The SDK repository includes a working example:

  • VpnDemo — Authentication flow with KapeAuthClient, AuthViewModel, and Jetpack Compose UI

See the android/Examples/ directory in the SDK repository.

Next Steps​

  • Authentication — login, logout, sessions, and error handling
  • Subscriptions — activating entitlements before connecting
  • VPN — server discovery, connection management, and KapeVpnService setup
  • Logs Collector — uploading logs to support, or exporting them to a zip