iOS SDK API

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

This is the public Swift API for the native Anectico 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 Anectico

Anectico.configure(
    AnecticoOptions(
        apiKey: "an_...",
        environment: "production",
        release: "com.acme.Shop@2.4.1+318",
        dist: "318"
    )
)

API	Parameters	Returns	Behavior
`Anectico.configure(options)`	`AnecticoOptions`	`Void`	Configures identity, sessions, event queue, error transport, crash handlers, lifecycle hooks, and timers. If the app is already active, emits its missed `$app_opened` exactly once. Repeated calls are ignored. A blank key leaves the SDK unconfigured.
`Anectico.flush(completion:)`	optional callback	`Void`	Starts an asynchronous diagnostic-event flush and calls completion after the attempt.
`Anectico.shutdown(completion:)`	optional callback	`Void`	Stops timers/hooks, flushes queued events, releases state, and permits later reconfiguration.

`AnecticoOptions`

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.anectico.com`	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`	Foreground-only 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
`Anectico.identify(distinctId, set:)`	stable ID; optional person properties	`Void`	Links the anonymous ID to a known person and queues identify.
`Anectico.group(type:key:set:)`	account type/key; optional properties	`Void`	Records membership and queues `$groupidentify`.
`Anectico.capture(event, properties:)`	event name; properties	`Void`	Queues a diagnostic event with current person/session/groups.
`Anectico.screen(name, properties:)`	screen name; properties	`Void`	Queues `$screen` with `$screen_name`.
`Anectico.reset()`	—	`Void`	Logout: creates a new anonymous ID, clears groups, rotates the session, and clears global error-user context and breadcrumbs.
`Anectico.distinctId`	property	`String?`	Current known/anonymous ID, or nil before configuration.
`Anectico.sessionId`	property	`String?`	Current durable session ID without extending its idle window.

Errors, messages, users, and breadcrumbs

Method	Parameters	Returns	Behavior
`Anectico.captureError(error, options:)`	Swift `Error`; optional `CaptureOptions`	`String`	Captures a caught error and returns its ID, or `""` before configuration.
`Anectico.captureError(exception, options:)`	`NSException`; optional options	`String`	Captures an Objective-C exception without changing app behavior.
`Anectico.captureMessage(message, level:options:)`	message; level default `info`; options	`String`	Captures a diagnostic message and returns its ID.
`Anectico.addBreadcrumb(category:message:level:data:)`	strings; level default `info`; data	`Void`	Adds trail context attached to a later error.
`Anectico.setUser(user)`	`AnecticoUser`	`Void`	Sets global error user context. Cross-signal identity still comes from `identify`.
`Anectico.clearUser()`	—	`Void`	Clears global error user context.
`Anectico.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. AnecticoUser 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 the bundle or its DWARF binary with anectico symbols upload-dsym MyApp.dSYM. Anectico matches organisation-scoped dSYM slices by exact Mach-O image UUID; release and distribution are not dSYM lookup keys.

For native symbolication, each frame carries its image UUID and load address. The complete loaded image set stays in the private crash sidecar; only a bounded table of frame-referenced images rides the recovered occurrence, so large simulator processes cannot exceed the ingest attribute cap.

Every iOS error occurrence automatically carries severity, handled state, an honest capture mechanism, release/distribution, SDK/platform, hardware model code/family, OS version, and app version/build. Caught Swift and explicitly captured Objective-C errors are handled and nonfatal; uncaught Objective-C exceptions and signals are unhandled and fatal. Signal crashes use the crash-time snapshot after relaunch.

These SDK-owned fields take precedence over colliding CaptureOptions.tags. The SDK records a model code such as iPhone15,4, not a unique phone: it never collects IDFV, the user-assigned device name, a serial number, or an installation ID.

The SDK-owned $app_opened lifecycle event carries the same privacy-safe release, app/build, platform, OS, and device-family context. It is emitted once per real foreground transition, while duplicate notifications in one active period are ignored. Backgrounding emits one $app_backgrounded, pauses recurring flushes, and performs one explicit flush; foregrounding recreates exactly one timer without rotating the session by itself. Anectico uses its versioned lifecycle marker to count canonical-person release adoption and the adopted-person error-free rate; host properties cannot override the marker context.

Backend propagation

API	Parameters	Returns	Behavior
`Anectico.propagationHeaders()`	—	`[String:String]`	Creates a fresh `traceparent` and identity baggage when configured.
`AnecticoPropagation.apply(to:&request)`	`inout URLRequest`	`Void`	Applies propagation while preserving unrelated baggage.
`AnecticoPropagation.newTraceparent()`	—	`String`	Creates a sampled W3C traceparent.
`AnecticoPropagation.baggageWithDistinctId(id, existing:)`	ID; existing baggage	`String`	Replaces the Anectico member and preserves unrelated baggage.
`AnecticoPropagation.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.