Expo / React Native
@fictura/sdk 0.23.0The public surface of @fictura/sdk — the Growth object, every init option, the components, and the helpers around them.
Growth
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.
The client-side gate — see Client-side gating. Fails closed before the first config.
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.
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.
The user logged in. options.set and options.set_once set attributes in the same call.
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.
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.
Properties on every later event, kept across launches.
Stop or resume capturing anything about this user. The choice is stored and survives restarts and reset(). See Privacy.
Runs a placement: { placement, params?, feature?, handler? }. Resolves once the placement has finished and never rejects. See Placements and campaigns.
What register would do right now, with no side effects.
Shows the placement's paywall unless the user already has requiredEntitlement. Answers PURCHASED, RESTORED, CANCELLED, NOT_PRESENTED or ERROR.
The paywall a placement would show, for your own UI. null for a holdout or no match.
Fetches paywall designs ahead of time. No list: every campaign paywall, prioritized first and the rest 5 seconds later.
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.
Explicit error report. Options are tags, extra, level and fingerprint; a plain object is kept as extra.
Reports a message with no exception. Levels are fatal, error, warning and info.
Tags on every later error report. null removes one.
Reports render crashes in a subtree, or through React 19's root options.
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
Your Fictura host.
The SDK app key (gk_…) from Dashboard → Setup. Sent as x-api-key.
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.
Your user id — joins events, errors and entitlements to a person. Wins over Growth.identify.
The RevenueCat app user id, for identity stitching with billing webhooks.
Only for an app that already has a device id, so one device does not become two users.
A bundled fallback config. Precedence: network > cache > defaults.
Where a paywall's Terms and Privacy links go. The SDK ships no URLs of its own.
The language to serve copy in. A change in the returned value triggers a config refetch without a restart.
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.
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.
Fires just before the user leaves for the browser — the place to arm a subscription re-check.
Observe every event as it queues.
Called whenever the backend's user id is learned.
Pretty names for routes, used by the expo-router tracker.
The JSX onPress fallback for automatic element_tapped capture. autocapture.captureTouches: false turns all tap capture off.
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.
Crash and unhandled-rejection capture. Chains to any handler installed before init.
Also send each console.error line as an issue. Off, those lines become breadcrumbs on the next real error.
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.
Native crashes, ANRs and hangs from the OS's own records on the next launch. See Native crashes.
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.
Resolve the install against bio links on first open. Set false if the app calls resolveFirstOpen() itself.
A session ends after this long with no events, or 24 hours after it started. The callback hears each new $session_id.
Edit or drop an event before it queues, and clean its properties before the size caps. A hook that throws never costs events.
Set false to capture nothing until Growth.optIn().
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 alwaysPlacementPresenterandPreviewPresenter. 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
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
| Event | When |
|---|---|
first_open | Once per install. |
app_open | Launch and every foreground. |
app_updated / app_backgrounded | A new version or build, and leaving the foreground. |
screen_viewed / screen_closed | Route changes, with screen, from/to, and duration_ms. |
element_tapped | One 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_tap | Four 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_failed | The paywall funnel. paywall_page_viewed is a screen change in an editor-built design. |
paywall_survey_answered / paywall_survey_skipped | A paywall's close or post-purchase survey. |
paywall_webview_crashed | The page's web process died and the paywall was brought back. |
placement_triggered / paywall_presentation_request | A placement ran, and whether it presented. |
purchase_started / purchase_completed / purchase_cancelled / purchase_failed | One purchase attempt, tied together by attempt_id. From 0.22 purchase_completed is success only; failures are purchase_failed. |
restore_started / restore_completed / restore_failed | Restore purchases (restored: false when there was nothing to restore). |
onboarding_started / _step_viewed / _question_answered / _completed / _skipped | The onboarding funnel. |
web_checkout_opened / web_checkout_open_failed | The 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 onGrowth) 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 }. AlsoregisterPlacement(),sanitizeParams(),substituteParams(),evaluateRule(),compareVersions(), andresolvePaywall(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(), andsetFicturaUI({ 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>_requestedand<name>_finishedwithduration_msanderror_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 asx-fictura-sdkon every call.