Expo / React Native

The complete public surface of @fictura/sdk — three members on Growth, the core components, and the helpers around them.

Growth

Growth.init(config)

function

Configures the SDK, installs press and error capture (each can be disabled), starts lifecycle tracking, hydrates the cached config, and fetches a fresh one.

Growth.isSubscribed()

() => boolean

The client-side gate — see Client-side gating. Fails closed before the first config.

Growth.captureError(e, ctx?)

function

Explicit error report; context is serialized into the message.

init config

apiBase

string · required

Your Fictura host.

apiKey

string · required

The SDK app key (gk_…) from Dashboard → Setup. Sent as x-api-key.

purchases

PurchasesAdapter

Your store wrapper: getPackages(), purchase(id), restore(), optional isSubscribed(). Without it, paywalls render with no packages and nothing can be purchased (block designs disable the CTA; locked templates surface a configuration error on tap). mockPurchasesAdapter ships for development.

getAccountId

() => Promise<string | null>

Your user id — joins events, errors and entitlements to a person.

getRevenueCatId

() => Promise<string | null>

The RevenueCat app user id, for identity stitching with billing webhooks.

defaults

Partial<SdkConfigPayload>

A bundled fallback config. Precedence: network > cache > defaults.

getLocale

() => string | null

A change in the returned value triggers a config refetch without a restart.

onWebCheckoutOpened

() => void

Fires just before the user leaves for the browser — the place to arm a subscription re-check.

onEvent

(name, status, props) => void

Observe every event as it queues.

enablePressCapture

boolean · default true

Automatic element_tapped capture.

enableErrorCapture

boolean · default true

Crash / rejection / console.error capture.

flushMs / maxBatch

number · 4000 / 25

Event batching: flush interval and batch-size trigger.

Components

<GrowthProvider> — mounts screen tracking and tap capture (both gated on the event-tracking tool) and the cancel-survey modal (gated on cancel-survey).
<GrowthPaywall placement onClose onPurchaseComplete fallback assets /> — renders whatever is live for the placement; see Served designs and Native templates.
<GrowthOnboarding placement onComplete onStepView onAnswer fallback assets /> — see Onboarding flows.
<CancelSurveyModal /> — polls for a pending cancel survey 4s after mount and on each foreground, throttled to five minutes.

Events

TypeScript

import { logEvent, setUserContext, setAttributes, flush } from "@fictura/sdk";

logEvent("generation_success", "success", { model: "large" });

// Super-properties merged into every event:
setUserContext({ plan: "trial" });

// Targeting attributes — max 20 keys, values ≤200 chars:
setAttributes({ onboarding_cohort: "b" });

Events batch on device — 25 events or 4 seconds, whichever first, plus a flush on background — and POST to /api/v1/events/log. Status is one of success, failure, info. Events disabled on the dashboard are dropped before they're sent.

Automatic events

Event	When
`first_open`	Once per install.
`app_open`	Launch and every foreground.
`screen_viewed` / `screen_closed`	Route changes, with `screen`, `from`/`to`, and `duration_ms`.
`element_tapped`	Any pressable, named by testID → accessibility label → child text → icon name → component name; dead taps fall back to coordinates.
`paywall_shown` / `paywall_screen_viewed` / `paywall_cta_tapped` / `paywall_dismissed`	The paywall funnel.
`purchase_completed`	With status `success` or `failure` from the block, flow and served-design renderers; single-screen locked templates (v3 configs) log it as `info` from the subscribe callback — filter on status with that in mind.
`onboarding_started` / `_step_viewed` / `_question_answered` / `_completed` / `_skipped`	The onboarding funnel.
`web_checkout_opened` / `web_checkout_open_failed`	The hand-off to the browser.

Everything else

Web checkout — openWebCheckout(), isWebCheckoutAvailable(), tryWebCheckoutFirst() — the intercept the block (v1/v2), flow (v4) and served-design buy buttons run first. Single-screen locked templates (v3 configs) purchase directly through the adapter and skip it.
Push — registerForPush() (a top-level export) prompts and registers an Expo push token; the SDK never prompts on its own.
Attribution — claimAttribution(clickId), onConversionData(fn), onDeepLink(fn), getConversionData(); late subscribers are replayed the last payload.
Surveys — checkPendingSurvey(), submitCancelSurvey().
Errors — captureError(), flushErrors(); see React Native.
Preview — isPreviewMode(); in dashboard previews, events, surveys, errors and push are all suppressed.