SDK keys & config refresh
One key identifies your app; one config fetch decides what your app does. Both are designed so a bad network never breaks a launch.
The SDK app key
Format gk_ + 48 hex characters. It rides as x-api-key on every SDK call — config, events, errors, surveys, push registration — and on the server-side entitlements check. It identifies your app rather than authenticating a person: treat it like a publishable key, not a private one. The genuinely secret credential is the Links API key (fk_live_…), which is shown once and stored hashed.
The config fetch
GET /api/v1/sdk/config returns everything server-driven in one payload: which tools are on, the live paywall and onboarding config for each placement, the disabled_events kill list, the web-checkout URL (or null, meaning show the store sheet), and a shadow entitlement verdict.
- When it refreshes — at launch, on every foreground, and it's re-checked on every
logEvent. A fetched config is considered fresh for 5 minutes; a failed fetch retries after 10 seconds. - ETags — the SDK sends
If-None-Match; a304costs almost nothing and counts as fresh. - Offline — the last good config is cached on device and rehydrated on cold start. Precedence is network → cache → the
defaultsyou can bundle at build time. - Failure — fails open to the last known config. Your app never blocks on Fictura being reachable.
Why 'next config refresh' is the unit of change
Every dashboard action — flipping a tool, setting a paywall live, disabling an event, turning web checkout off — lands on devices at the next launch, foreground, or within about five minutes. No release, no review.
Locale changes
If you supply getLocale, a change in its value invalidates the cached config immediately — a user who switches language mid-session gets re-served without a restart.