iOS SDK API

Functions, options, parameters, return values, and propagation helpers for the Teml Swift SDK.

This is the public Swift API for the native Teml iOS SDK. It supports iOS 15 and later. Public calls never throw into the host application; calls made before configuration are safe no-ops with a log warning. Event/error network work runs off the calling thread.

Use a project key with ingest:write and analytics:write. The native SDK does not record replay.

Configure the SDK

import Teml

Teml.configure(
    TemlOptions(
        apiKey: "tm_...",
        environment: "production",
        release: "com.acme.Shop@2.4.1+318",
        dist: "318"
    )
)

API	Parameters	Returns	Behavior
`Teml.configure(options)`	`TemlOptions`	`Void`	Configures identity, sessions, event queue, error transport, crash handlers, lifecycle hooks, and timers. Repeated calls are ignored. A blank key leaves the SDK unconfigured.
`Teml.flush(completion:)`	optional callback	`Void`	Starts an asynchronous diagnostic-event flush and calls completion after the attempt.
`Teml.shutdown(completion:)`	optional callback	`Void`	Stops timers/hooks, flushes queued events, releases state, and permits later reconfiguration.

`TemlOptions`

Only apiKey is required. Invalid numeric values are clamped to safe ranges during resolution.

Option	Type/default	Purpose
`apiKey`	`String`; required	Key sent to error and event endpoints.
`endpoint`	`String`; `https://api.teml.io`	Base URL for `/v1/traces` and `/api/v1/capture`.
`environment`	`String`; `development`	`deployment.environment` resource value.
`release`	`String?`; service version when real	Regression and symbol-artifact identifier.
`dist`	`String`; empty	Build/artifact discriminator.
`serviceName`	`String?`; bundle ID	`service.name`.
`serviceVersion`	`String?`; bundle marketing version	`service.version`.
`flushAt`	`Int`; `20`	Event-count flush threshold.
`flushIntervalMs`	`Int`; `5000`	Periodic event flush; zero disables the timer.
`maxStackTraceFrames`	`Int`; `50`	Maximum frames per error.
`breadcrumbCapacity`	`Int`; `100`	Ring-buffer capacity.
`maxQueueSize`	`Int`; `10000`	Diagnostic-event queue cap; oldest entries drop at the cap.
`errorSampleRate`	`Double`; `1`	Non-fatal error sampling in the inclusive range 0–1.
`enableCrashReporting`	`Bool`; `true`	Install uncaught `NSException` and fatal-signal handlers.
`debug`	`Bool`; `false`	Emit SDK diagnostics through Apple logging.

Identity, accounts, and events

Method/property	Parameters	Returns	Behavior
`Teml.identify(distinctId, set:)`	stable ID; optional person properties	`Void`	Links the anonymous ID to a known person and queues identify.
`Teml.group(type:key:set:)`	account type/key; optional properties	`Void`	Records membership and queues `$groupidentify`.
`Teml.capture(event, properties:)`	event name; properties	`Void`	Queues a diagnostic event with current person/session/groups.
`Teml.screen(name, properties:)`	screen name; properties	`Void`	Queues `$screen` with `$screen_name`.
`Teml.reset()`	—	`Void`	Logout: creates a new anonymous ID, clears groups, and rotates the session.
`Teml.distinctId`	property	`String?`	Current known/anonymous ID, or nil before configuration.
`Teml.sessionId`	property	`String?`	Current durable session ID without extending its idle window.

Errors, messages, users, and breadcrumbs

Method	Parameters	Returns	Behavior
`Teml.captureError(error, options:)`	Swift `Error`; optional `CaptureOptions`	`String`	Captures a caught error and returns its ID, or `""` before configuration.
`Teml.captureError(exception, options:)`	`NSException`; optional options	`String`	Captures an Objective-C exception without changing app behavior.
`Teml.captureMessage(message, level:options:)`	message; level default `info`; options	`String`	Captures a diagnostic message and returns its ID.
`Teml.addBreadcrumb(category:message:level:data:)`	strings; level default `info`; data	`Void`	Adds trail context attached to a later error.
`Teml.setUser(user)`	`TemlUser`	`Void`	Sets global error user context. Cross-signal identity still comes from `identify`.
`Teml.clearUser()`	—	`Void`	Clears global error user context.
`Teml.captureRawError(...)`	type, message, frame JSON, fatal, mechanism, tags	`String`	Bridge API for React Native/Flutter pre-parsed stacks. Native Swift apps should use `captureError`.

CaptureOptions fields are tags: [String:String], extra: [String:Any], optional user, optional level, and optional fingerprint: [String]. Fingerprint components are comma-joined; do not put commas inside components. TemlUser supports id, email, username, ipAddress, and segment.

Fatal native crashes are persisted and delivered on the next application launch. Keep the exact archive dSYM and upload its DWARF binary using the same release/build identifiers.

Backend propagation

API	Parameters	Returns	Behavior
`Teml.propagationHeaders()`	—	`[String:String]`	Creates a fresh `traceparent` and identity baggage when configured.
`TemlPropagation.apply(to:&request)`	`inout URLRequest`	`Void`	Applies propagation while preserving unrelated baggage.
`TemlPropagation.newTraceparent()`	—	`String`	Creates a sampled W3C traceparent.
`TemlPropagation.baggageWithDistinctId(id, existing:)`	ID; existing baggage	`String`	Replaces the Teml member and preserves unrelated baggage.
`TemlPropagation.percentEncode(value)`	string	`String`	Encodes a W3C baggage value.

Apply identity baggage only to application backends you trust. A backend must authenticate the mobile request rather than treating the baggage value itself as proof of identity.