Fictura
SDK reference

Expo / React Native

@fictura/sdk 0.23.0

The public surface of @fictura/sdk — the Growth object, every init option, the components, and the helpers around them.

Growth

Growth.init(config)
(GrowthConfig) => void

Configures the SDK, installs press, error and trace 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.setLocale(tag)
(string | null) => Promise<void>

Paywalls in this language from now on ("de", "pt-BR"), whatever the phone is set to. Beats getLocale and the device. null goes back to them. The config is refetched straight away.

Growth.screen(name, properties?)
function

Logs screen_closed for the previous screen and screen_viewed for this one, and stamps $screen_name on every later event. Repeating the current screen does nothing.

Growth.identify(accountId, options?)
Promise<void>

The user logged in. options.set and options.set_once set attributes in the same call.

Growth.reset(options?)
Promise<void>

The user logged out: account id, super properties, attributes, assignments and occurrence history are cleared, with a new seed and a new session. { newDevice: true } also starts a new device id.

Growth.setAttributes(attrs) / setOnce(attrs) / unsetAttribute(key)
function

Attributes on the user. At most 100 keys, keys up to 40 characters, strings up to 1024. setOnce only writes where the user has no value yet.

Growth.registerSuperProperties(properties) / unregisterSuperProperty(key)
function

Properties on every later event, kept across launches.

Growth.optOut() / optIn() / isOptedOut()
Promise

Stop or resume capturing anything about this user. The choice is stored and survives restarts and reset(). See Privacy.

Growth.register(args)
(RegisterArgs) => Promise<void>

Runs a placement: { placement, params?, feature?, handler? }. Resolves once the placement has finished and never rejects. See Placements and campaigns.

Growth.getPresentationResult(placement, params?)
Promise<PresentationResult>

What register would do right now, with no side effects.

Growth.presentIfNeeded(args)
Promise<PresentIfNeededResult>

Shows the placement's paywall unless the user already has requiredEntitlement. Answers PURCHASED, RESTORED, CANCELLED, NOT_PRESENTED or ERROR.

Growth.getPaywallForPlacement(placement, params?)
Promise<PaywallForPlacement | null>

The paywall a placement would show, for your own UI. null for a holdout or no match.

Growth.preloadPaywalls(placements?)
Promise<void>

Fetches paywall designs ahead of time. No list: every campaign paywall, prioritized first and the rest 5 seconds later.

Growth.handleDeepLink(url)
(string) => boolean

Hand the SDK a deep link. ?fictura_debug=true&paywall_id=<id> previews that paywall and returns true. Any other link fires the deep_link_open placement and returns false.

Growth.captureError(error, contextOrOptions?)
function

Explicit error report. Options are tags, extra, level and fingerprint; a plain object is kept as extra.

Growth.captureMessage(message, levelOrOptions?)
function

Reports a message with no exception. Levels are fatal, error, warning and info.

Growth.setTag(key, value) / setTags(tags)
function

Tags on every later error report. null removes one.

Growth.ErrorBoundary / Growth.reactErrorHandler()
component / function

Reports render crashes in a subtree, or through React 19's root options.

Growth.reportFullyDisplayed()
() => boolean

Ends the current screen's time-to-full-display span. Call once per screen visit, within 30 seconds of the navigation.

Growth.unregister(key) and Growth.register(properties) still work for super properties, with a one-time warning. Use the named calls above.

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(offeringId?), purchase(packageId, offeringId?, context?), restore(). Leave it out if the app has react-native-purchases: the SDK detects it and uses a built-in adapter (revenueCatAdapter). With neither, paywalls render with no packages and nothing can be purchased. mockPurchasesAdapter ships for development.

Optional on the adapter: isSubscribed(), isTrialEligible(), hasEntitlement(id), setAttributes(), trackCustomPaywallImpression(), revenueCat: { stampPlacement: true } and reportsPurchaseEvents.

getAccountId
() => Promise<string | null>

Your user id — joins events, errors and entitlements to a person. Wins over Growth.identify.

getRevenueCatId
() => Promise<string | null>

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

getDeviceId
() => Promise<string>

Only for an app that already has a device id, so one device does not become two users.

defaults
Partial<SdkConfigPayload>

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

legal
{ termsUrl?, privacyUrl? }

Where a paywall's Terms and Privacy links go. The SDK ships no URLs of its own.

getLocale
() => string | null | Promise<string | null>

The language to serve copy in. A change in the returned value triggers a config refetch without a restart.

localImages
Record<string, number | string>

Pictures bundled in the app, by name. An editor image with a Bundled picture name draws this file and falls back to its URL. Needs expo-asset, and expo-file-system in release builds.

onCustomAction
(name, payload) => boolean | void | { ok?, values? }

Runs a paywall's Custom action tap, sync or async. Return false for its failure branch, or values to hand them back as state.<name>. Without this, custom actions fail.

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.

onIdentity
(masterUserId) => void

Called whenever the backend's user id is learned.

screenNames
Record<string, string>

Pretty names for routes, used by the expo-router tracker.

enablePressCapture
boolean · default true

The JSX onPress fallback for automatic element_tapped capture. autocapture.captureTouches: false turns all tap capture off.

autocapture
GrowthAutocaptureConfig

captureTouches, captureScreens, captureLifecycle, captureRageTaps, captureDeadTaps, customLabelProp, noCaptureProp, noTextProp, ignoreLabels, maxElementsCaptured, propsToCapture. Defaults are in AUTOCAPTURE_DEFAULTS. The dashboard can switch taps, screens and lifecycle off but never on.

enableErrorCapture
boolean · default true

Crash and unhandled-rejection capture. Chains to any handler installed before init.

captureConsoleErrors
boolean · default false

Also send each console.error line as an issue. Off, those lines become breadcrumbs on the next real error.

errorSampleRate / maxErrorsPerIssuePerMinute / beforeSendError
1 / 10 / function

Share of non-fatal errors sent, a per-issue rate limit on this device, and a hook to change or drop a report. Fatal crashes are never sampled or limited.

enableNativeCrashReporting
boolean · default true

Native crashes, ANRs and hangs from the OS's own records on the next launch. See Native crashes.

enableTracing / tracesSampleRate / tracePropagationTargets / enableFrameTracking
true / 1 / [] / true

Screen, app-start and HTTP traces, the share kept before the dashboard's rate loads, where traceparent may be sent, and slow and frozen frame counts.

enableBioLinkResolve
boolean · default true

Resolve the install against bio links on first open. Set false if the app calls resolveFirstOpen() itself.

sessionIdleMs / onSessionChange
1800000 / function

A session ends after this long with no events, or 24 hours after it started. The callback hears each new $session_id.

beforeSend / sanitizeProperties
function

Edit or drop an event before it queues, and clean its properties before the size caps. A hook that throws never costs events.

defaultOptIn
boolean · default true

Set false to capture nothing until Growth.optIn().

flushMs / maxBatch / maxQueueSize
number · 4000 / 25 / 1000

Event batching: flush interval, batch-size trigger, and how many events the device holds before the oldest are dropped.

Components

  • <GrowthProvider> — mounts screen tracking and tap capture (both gated on the event-tracking tool), the cancel-survey modal (gated on cancel-survey), PaywallWarmer (gated on paywalls), and always PlacementPresenter and PreviewPresenter. You do not mount those three yourself.
  • <GrowthPaywall placement onClose onPurchaseComplete onRestoreComplete fallback assets initialScreenKey params /> — 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.
  • <AttributionCodeScreen /> — the iOS first-run code screen for bio links.
  • WebviewPaywall, WebviewOnboarding, PaywallTemplate, OnboardingStepView, GrowthScreenTracker, GrowthTapTracker — the pieces the components above are built from, exported for hosts that mount them directly.
  • HouseAIPaywall, HouseAIV2, HouseAIOnboarding, the House AI MAX screens (FreeTry, TrialNotification, TrialReelTrial, TrialReelWeekly, ExclusiveOffer, FlashSaleWeekly, FlashSaleYearly) and the Template 2 screens (Intro, Features, Template2Notification, Pricing) — prebuilt designs, rendered directly. Their default words and palettes are exported too: HOUSE_AI_MAX_SCREENS, EXCLUSIVE_OFFER_COPY, FLASH_SALE_WEEKLY_COPY, FLASH_SALE_YEARLY_COPY, FREE_TRY_COPY, TRIAL_NOTIFICATION_COPY, TRIAL_REEL_TRIAL_COPY, TRIAL_REEL_WEEKLY_COPY, HOUSE_AI_V2_COPY, HOUSE_AI_V2_THEME, TEMPLATE2_SCREENS, TEMPLATE2_THEME, INTRO_COPY, FEATURES_COPY, TEMPLATE2_NOTIFICATION_COPY, PRICING_COPY.

Events

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

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

// Merged into every event, in memory only:
setUserContext({ plan: "trial" });

// Targeting attributes — max 100 keys, strings ≤1024 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. The queue survives restarts when @react-native-async-storage/async-storage is installed. Status is one of success, failure, info. Events disabled on the dashboard are dropped before they're sent.

Automatic events

EventWhen
first_openOnce per install.
app_openLaunch and every foreground.
app_updated / app_backgroundedA new version or build, and leaving the foreground.
screen_viewed / screen_closedRoute changes, with screen, from/to, and duration_ms.
element_tappedOne per tap, with the element chain in $elements and the best label in element: testID, accessibility label, text, icon name or component name.
rage_tap / dead_tapFour or more fast taps on one element, and a press whose handler never ran.
paywall_shown / paywall_screen_viewed / paywall_page_viewed / paywall_product_selected / paywall_interacted / paywall_cta_tapped / paywall_dismissed / paywall_load_failedThe paywall funnel. paywall_page_viewed is a screen change in an editor-built design.
paywall_survey_answered / paywall_survey_skippedA paywall's close or post-purchase survey.
paywall_webview_crashedThe page's web process died and the paywall was brought back.
placement_triggered / paywall_presentation_requestA placement ran, and whether it presented.
purchase_started / purchase_completed / purchase_cancelled / purchase_failedOne purchase attempt, tied together by attempt_id. From 0.22 purchase_completed is success only; failures are purchase_failed.
restore_started / restore_completed / restore_failedRestore purchases (restored: false when there was nothing to restore).
onboarding_started / _step_viewed / _question_answered / _completed / _skippedThe onboarding funnel.
web_checkout_opened / web_checkout_open_failedThe hand-off to the browser.

Every paywall and purchase event carries the placement block (placement, paywall_id, campaign_id, variant_id and more); the full list, and the names that changed in 0.22, are in the event dictionary.

Everything else

  • Web checkout — openWebCheckout(), isWebCheckoutAvailable(), getWebCheckoutUrl(), 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, not on Growth) prompts and registers an Expo push token, and resolves whether it did; the SDK never prompts on its own.
  • Attribution — onConversionData(fn), onDeepLink(fn), getConversionData(); late subscribers are replayed the last payload. claimAttribution(clickId) is the one call you place by hand — see How attribution works for when and why. Bio links: resolveFirstOpen(), resolveWithCode(), getResolvedInstall(), reportInstallEnvironment(), environmentSnapshot(), readInstallReferrer(), resetInstallReferrerRead().
  • Placements — usePlacement(callbacks?) returns { registerPlacement, state }. Also registerPlacement(), sanitizeParams(), substituteParams(), evaluateRule(), compareVersions(), and resolvePaywall(placement) / resolveOnboarding(placement) for the variant a placement resolves to.
  • Paywall warming and caching — prefetchPlacements(placements, { delayMs? }), prefetchServedPaywall(placement, { warm? }), getCachedPaywallHtml(paywallId); see Served designs.
  • Preview on a phone — openPaywallPreview(url), previewIdFrom(url) and <PreviewPresenter />, for apps that route links themselves; see The paywall editor.
  • Store — purchasesAdapter() (the adapter in force), revenueCatAdapter, revenueCatAvailable(), mockPurchasesAdapter, formatPrice().
  • Templates — registerPaywallTemplate(), registerOnboardingTemplate(), paywallTemplate(key), onboardingTemplate(key), registeredPaywallTemplates(), registeredOnboardingTemplates(), and setFicturaUI({ Image, LinearGradient }) to inject the host's UI primitives.
  • Config — getSdkConfig(), getSdkConfigStatus(), subscribeSdkConfig(fn), refreshSdkConfig(force?), hydrateSdkConfigCache(), isToolEnabled(key), getShadowEntitlement().
  • Outcome funnels — trackOutcome(name, props, fn) wraps a call and logs <name>_requested and <name>_finished with duration_ms and error_code. For work that finishes elsewhere: trackOutcome(name, props?), bindOutcome(), finishOutcome(), isOutcomeTracked(), mapErrorCode().
  • Users and events — screen(), getCurrentScreen(), setCurrentScreen(), screenName(), getLastPressAt(), getSessionId(), getMasterUserId(), flush(), setOnce(), unsetAttribute(), getAttributes(), clearAttributes(), registerSuperProperties(), unregisterSuperProperty(), getSuperProperties(), optIn(), optOut(), isOptedOut().
  • Surveys — checkPendingSurvey(), submitCancelSurvey(reason, freeText?).
  • Errors and tracing — captureError(), captureMessage(), flushErrors(), installErrorCapture(), setTag(), setTags(), ErrorBoundary, reactErrorHandler(), installPressCapture(), installTracing(), flushSpans(), activeTraceContext(), reportFullyDisplayed(); see React Native.
  • Preview — isPreviewMode(), getPreviewState(); in dashboard previews, events, surveys, errors and push are all suppressed.
  • Version — SDK_VERSION, sent as x-fictura-sdk on every call.

On this page