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.
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()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.