13. SDK API

The same surface on every platform, so cross-platform layers (React Native, Flutter) can bridge it one to one. Each SDK documents its own idioms (names in the language’s style, builders, async variants); the behavior is this table.

Call	Does
start(key, options)	Starts the SDK. Crashes, launches, screens, network and lifecycle are on by default
setUser(idHash, attributes) / clearUser()	Identifies the user with a hash the app provides (user.hash)
setAttribute(key, value)	A global attribute added to every record
log(level, message, attributes)	A log record
recordError(error, attributes, fingerprint?)	A handled error (section 6.2)
addBreadcrumb(message, attributes)	A manual breadcrumb next to the automatic ones
startSpan(name)	A custom span; children nest under the current span
trackScreen(name) / reportFullyDrawn()	Manual screen names and TTFD (section 8.2)
setFeatureFlag(name, variant)	A feature flag evaluation (feature_flag.key, feature_flag.result.variant), attached to the session and to crashes (section 13.4)
setConsent(granted)	Pauses or resumes collection; withdrawing consent drops the queue (section 13.5)
flush()	Sends what is queued

13.1 Start options

Every SDK accepts at least:

Option	Default	Section
endpoint	Derived from the key	1.3
installationId	On	2.3
firstPartyHosts	Empty	8.4
replay.enabled	Off, until the app turns replay on	10.2
replay.textMasking	all (or inputs)	10.3
replay.touches	show (or hide)	10.3
replay.maskClasses, replay.unmaskClasses, replay.hideClasses	Empty	10.4
redact	None	11

13.2 Per-view replay settings

replayMask, replayUnmask and replayHide on a view instance, plus the apsio-mask, apsio-unmask and apsio-hide tokens as words of the accessibility identifier or view tag (section 10.4). Declarative UI frameworks expose them as modifiers (for example SwiftUI .apsioReplayMask() and the equivalent Jetpack Compose modifiers).

A debug-only mask preview SHOULD show what replay records, the same way on every platform:

• the call is showReplayMaskPreview(on): it turns an overlay on or off over the app’s windows (on Android, every window replay walks, following the resumed activity);
• the overlay fills with 35% opacity and strokes 1 point (1 dp) each node’s area: red (#FF3B30) where replay.mask decides masked, containers included; grey (#555555) where it decides hidden, including web views, maps, video and the keyboard where the platform can see it; and a green outline over the areas whose touches are recorded (10.3);
• it works whether or not the session records replay, or replay was started, with the app’s masking options and the policy’s tightening (10.5);
• it is never drawn in a release app. On iOS it is compiled only in debug builds; on Android, whose library ships as one release artifact, the call exists and does nothing unless the app is debuggable (FLAG_DEBUGGABLE). The overlay itself is never captured.

13.3 Breadcrumbs

A breadcrumb is a log record with event name apsio.breadcrumb and apsio.breadcrumb.category (navigation, network, user, lifecycle, manual). SDKs keep the last breadcrumbs of the session in memory and on disk, so a crash report on the next launch can reference them by session and time.

13.4 Feature flags

setFeatureFlag(name, variant) records the variant of a flag the app evaluated:

• MUST send a log record with event name feature_flag.evaluation, carrying feature_flag.key (the name) and feature_flag.result.variant (the variant).
• MUST from then on add feature_flag.<name> set to the variant to every record it sends, like a global attribute (setAttribute), so the session’s records carry the flag. A later call for the same name replaces the variant.
• MUST keep those attributes with the context of a crash report, so the crash the next launch sends (section 6.1) carries the flags of the process that crashed.
• A backend reads a session’s flags from its records: the evaluation records, or feature_flag.<name>. Names the OpenTelemetry and OpenFeature conventions use under feature_flag. are not flags: key, variant, version, provider and anything under result., provider., context., set. or evaluation.. An app SHOULD NOT give a flag one of those names.
• The vector sessions/sdk-feature-flags checks it.

13.5 Consent

setConsent(granted) records the app user’s choice (section 11):

• setConsent(false) MUST stop collection at once and drop everything not yet sent: the queue, the batches on disk and the uploads handed to the operating system.
• The choice MUST persist across launches: a launch after consent was withdrawn starts withdrawn, until the app calls setConsent(true). An app that asks for consent before it starts the SDK withdraws it from the first launch by calling setConsent(false) right after start.
• While consent is withdrawn the SDK records nothing: no records, spans, metrics or session summaries. A crash, hang or exit of a run that ended with consent withdrawn is never reported, even once consent returns.
• setConsent(true) MUST resume collection with a new session, whose session.start carries the session in progress as session.previous_id (section 3.1). The session during which consent was withdrawn reports nothing more: no summary and no end.
• Withdrawing consent does not delete what was already sent. A backend offers erasure by user.hash for that.
• The vectors privacy/sdk-consent-pause-resume and privacy/sdk-consent-persists check it.