API Reference

Source: apps/ios-sdk/Sources/OneSygnal/Api/OneSygnal.swift, singleton OneSygnal.shared.

Most methods that do meaningful async work ship as two overloads of the same name: a completion-handler version and an async version (withCheckedContinuation wrapping the former). Swift’s overload resolution picks the right one per call site — a call with a trailing closure resolves to the completion-based version; an awaited call or one with no completion argument resolves to the async version. Kotlin can’t do this (a suspend fun can’t overload past a defaulted parameter), which is why Android uses …Await suffixes instead — a language constraint, not an inconsistency between the two SDKs.

Configuration

Method	Signature	Notes
`setApiKey`	`(_ apiKey: String) -> Void`	Overrides the Info.plist key. Must be called before `initialize()`. Blank string is a silent no-op.
`setLocale`	`(_ locale: String) -> Void`	Live-reactive after `initialize()` — re-fetches config/surveys under the new locale.

Lifecycle

Method	Signature	Notes
`initialize`	`(completion: ((Bool) -> Void)? = nil) -> Void`	Completion fires once config is fetched, user is ensured, surveys are fetched, and the rules engine is loaded — `true` on success. Already-initialized calls resolve `true` immediately. Resolves `false` if the API key can’t be resolved (see Troubleshooting).
`initialize`	`() async -> Bool`	Async overload of the above.
`isInitialized`	`() -> Bool`	Reads back whether `initialize` has completed.
`shutdown`	`(completion: (() -> Void)? = nil) -> Void`	Flushes pending events, tears down timers/listeners, marks uninitialized. No-op (completion still fires) if not initialized.
`shutdown`	`() async -> Void`	Async overload of the above.

Identity

Method	Signature	Notes
`identify`	`(_ userId: String, attributes: [String: Any]? = nil, completion: ((Bool) -> Void)? = nil) -> Void`	No-op (completion resolves `false`) if not initialized. Re-fetches surveys if more than 60s have elapsed since the last fetch.
`identify`	`(_ userId: String, attributes: [String: Any]? = nil) async -> Bool`	Async overload of the above.
`logout`	`(completion: (() -> Void)? = nil) -> Void`	Clears the identified user, reverting to anonymous tracking. Re-fetches surveys. No-op if not initialized.
`logout`	`() async -> Void`	Async overload of the above.
`reset`	`(completion: (() -> Void)? = nil) -> Void`	Mints a new anonymous ID and re-fetches surveys — distinct from `logout()`. No-op if not initialized.
`reset`	`() async -> Void`	Async overload of the above.

Tracking and surveys

Method	Signature	Notes
`track`	`@discardableResult (_ eventName: String, properties: [String: Any?] = [:]) -> Bool`	Returns `false` if not initialized or surveys are disabled; otherwise delegates to `EventTracker.track` and returns its result.
`setSurveysEnabled`	`(_ enabled: Bool) -> Void`	Globally suppresses/re-enables survey overlays without affecting event tracking.
`areSurveysEnabled`	`() -> Bool`	Reads back the flag set by `setSurveysEnabled`. Defaults `true`.

Events

Method	Signature	Notes
`on`	`@discardableResult (_ event: String, callback: @escaping (Any?) -> Void) -> Registration`	See Events for names and payloads. `"ready"` replays immediately to a listener registered after it already fired.
`Registration.cancel`	`() -> Void`	Stops that specific registration. Double-cancel is a no-op. There is no free-standing `off(event, callback)` — `Registration` is the only unsubscribe mechanism, because Swift closures aren’t `Equatable` (so there’s nothing to match by reference the way web’s `off()` does).

`flush` is absent

Web exposes a flush() that forces pending events/responses to send immediately. iOS does not: EventTracker and ResponseFlusher’s periodic timers (event flush, response flush) are internal, with nothing exposed for a caller to trigger early. Same on Android.

Not part of the supported surface

setSdkWrapper(library:version:) — public, but exists only for wrapper SDKs (the Flutter plugin calls it at registration to override $lib/$lib_version device-context fields). Not intended for direct use by native app integrators.
emit(_:_:) — internal visibility, widened only so the same-module test target can drive it directly. Not part of the public surface.

See Platform Parity for what exists on every platform.