Configuration

API key

Read from Info.plist by default — key OneSygnalApiKey:


<key>OneSygnalApiKey</key>
<string>YOUR_API_KEY</string>

Or override in code with setApiKey(), which must be called before initialize() — the key is only read once, at initialize() time, so calling it afterward is a silent no-op:


OneSygnal.shared.setApiKey("YOUR_API_KEY")
OneSygnal.shared.initialize()

A blank string passed to setApiKey() is also a silent no-op (leaves any prior override, or the plist key, in place) rather than trapping. initialize() is the one place a resolved-but-missing key is reported — see Troubleshooting.

Precedence, highest first: setApiKey() override → PlistConfig.readApiKey() (the OneSygnalApiKey Info.plist entry).

Unlike web, which takes the key as init()’s argument with no override method, iOS (like Android) reads it from platform config by default and exposes setApiKey() as an explicit override.

Locale

Defaults to the device’s preferred language (Locale.preferredLanguages.first, falling back to "en-US"). Override with setLocale():


OneSygnal.shared.setLocale("fr-FR")

Unlike setApiKey(), setLocale() is live-reactive: called after initialize() has already run, it immediately updates the Accept-Language header used for all subsequent requests and triggers a fresh config/surveys fetch under the new locale — no app restart needed. Called before initialize(), it just sets the locale that call will use. Web has no equivalent — its locale is fixed at init() time.

No init options object

Unlike web’s init(apiKey, options), initialize() takes only an optional completion — there’s no options argument. Server-driven settings (sessionTimeout, globalCooldownMinutes, dailyCap, rate limits) come from the fetched SdkConfig, with these client-side defaults applied until that fetch completes or if it fails:

Setting	Default	Notes
`sessionTimeout`	`1800` (seconds)	Used by `SessionTracker` to decide “resumed after background” vs. a new session.
`globalCooldownMinutes`	`1440`	Server-configured cooldown between survey displays.
`dailyCap`	`3`	Server-configured max displays per day.
`eventsPerSecond`	`10.0`	Rate limit on `track()` calls.
`eventsBurstLimit`	`100.0`	Burst allowance on top of the steady rate.
`cacheTTL`	`300` (seconds)	Config cache lifetime.

What exists here but not on web

reset(), setApiKey(), and setLocale() all exist on iOS (and Android) but not on web:

reset() — mints a new anonymous ID and re-fetches surveys, distinct from logout(). Web has never distinguished “clear the identified user” from “mint a new anonymous ID,” so it has no equivalent.
setApiKey() — see above; web takes the key as init()’s argument instead.
setLocale() — see above; web’s locale is fixed at init() time by design.

See the full Platform Parity table for every operation.