# Native SDK reference

The methods exposed by the downloadable Swift and Kotlin clients, their execution requirements, and what your application must handle.

## Client construction

Swift exposes AplynaClient as an actor. Kotlin exposes a synchronized client with blocking networking. Construct and retain a client using the hosted base URL, app SDK key, persistent installation ID, and platform-owned cache/storage. Create a new client when changing application or installation identity.

### Swift

```
import Foundation
import Aplyna

// Create once and persist; reuse this ID across app launches.
let defaults = UserDefaults.standard
let installationID = defaults.string(forKey: "aplyna.installationID")
    ?? UUID().uuidString
defaults.set(installationID, forKey: "aplyna.installationID")

let client = AplynaClient(
    baseURL: URL(string: "https://aplyna.com")!,
    apiKey: "YOUR_APP_SDK_KEY",
    installationID: installationID
)

// Run in an async context, after your consent flow permits tracking.
try await client.setConsent(true)
try await client.track(name: "app_opened")
try await client.flush()
```

### Kotlin

```
import com.aplyna.sdk.AplynaClient
import java.util.UUID

val prefs = context.getSharedPreferences("aplyna", 0)
val installationId = prefs.getString("installation_id", null)
    ?: UUID.randomUUID().toString().also {
        prefs.edit().putString("installation_id", it).apply()
    }
val client = AplynaClient(
    baseUrl = "https://aplyna.com",
    apiKey = "YOUR_APP_SDK_KEY",
    installationId = installationId,
    storageDirectory = context.filesDir
)

// After consent; call networking methods off the main thread.
client.setConsent(true)
client.track(name = "app_opened")
client.flush()
```

## Method reference

| Swift / Kotlin | Behavior |
| --- | --- |
| setConsent(_:) / setConsent(granted) | Starts false. Enables tracking when your application permits it. Setting false clears persisted queued events. |
| track(name:flowID:stepID:assignment:properties:) / track(name, flowId, stepId, assignment, properties) | Requires consent. Appends and persists a new event. Optional properties use string values in these client helpers. Does not send immediately. |
| expose(_:) / expose(assignment) | Queues experiment_exposed when the assignment has an experiment ID. Call when the assigned UI actually appears; it does not flush. |
| flush() | Requires consent. Sends queued events in batches of up to 100. Bounded retries preserve event IDs. Schedule a later call after final failure. |
| assignment(flowID:) / assignment(flowId) | Requires consent. Returns a server assignment, disk-cached assignment on request failure, or Control A with no experiment ID if there is no cache. |
| configuration(flowID:) / configuration(flowId) | Fetches a compatible published release using ETag caching. Swift requests schema 2; Kotlin requests schema 1. Throws if both delivery and compatible cache fail. |
| pendingEventCount / pendingEventCount() | Current local queue length. Useful for delivery diagnostics; it is not an ingestion acknowledgement or analytics metric. |

## Handle native errors

Swift exposes AplynaError cases consentRequired, queueFull, insecureTransport, unsupportedSchema, invalidResponse and server(status, message), alongside possible transport/storage errors. Kotlin exposes AplynaHttpException with status for HTTP failures, plus state, storage, parsing and transport exceptions. Catch errors at the integration boundary and show an appropriate native fallback.

## Application responsibilities

- Persist pseudonymous installation identity and obtain required consent.
- Map real UI lifecycle events to SDK calls without duplicate callbacks.
- Perform Kotlin networking on an executor or IO dispatcher.
- Call flush at meaningful boundaries and again after final network failure.
- Retain bundled fallback screens and handle unsupported configuration.
- Keep purchase processing and verified entitlement handling separate from journey telemetry.

## Related references

- [HTTP API](https://aplyna.com/docs/api): Wire formats, status codes, request limits and cache headers.
- [Troubleshooting](https://aplyna.com/docs/troubleshooting): Diagnose errors without exposing credentials.