Fictura
Welcome

SDK Quickstart

SDK 0.24.0

Install one package and call Growth.init. Events, error tracking, entitlements and experiment assignment all start on that one call — paywalls are one of the things you can do next.

Install.

One npm package, plus the Expo modules it reports through: a stable device id, unsent events that survive a restart, and the device and connection on every event. Then add the config plugin, which writes the iOS privacy manifest they need.

Initialize.

Call Growth.init() once, early — before your first screen renders. apiBase is your Fictura host and apiKey is the SDK app key from Dashboard → Setup.

Wrap your app.

GrowthProvider mounts screen tracking, tap capture, the cancel-survey modal, and what presents a paywall. Screen and tap tracking run when the event-tracking tool is on; the survey modal when the cancel-survey tool is on.

Install
npm install @fictura/sdk
npx expo install expo-secure-store expo-application expo-device expo-network @react-native-async-storage/async-storage
app.json
{
  "expo": {
    "plugins": ["@fictura/sdk/plugin"]
  }
}
PackageWhat you lose without it
expo-secure-store, expo-applicationA device id that stays stable across launches.
@react-native-async-storage/async-storageThe event queue, super properties and cached config live in memory only, so unsent events are lost when the app restarts.
expo-device$device_model and $is_emulator.
expo-network$network_type.

All of them are optional: the SDK runs without any of them, and leaves out what it can't read.

The SDK also has a small native module, used for native crash reports and frame counts. It autolinks into a development or store build. In Expo Go those features stay off.

App.tsx
import { Growth, GrowthProvider } from "@fictura/sdk";

Growth.init({
  apiBase: process.env.EXPO_PUBLIC_GROWTH_API_BASE!,
  apiKey: process.env.EXPO_PUBLIC_GROWTH_API_KEY!,   // gk_… from Dashboard → Setup
  getAccountId: async () => auth.currentUserId ?? null,
});

export default function App() {
  return <GrowthProvider>{/* your app */}</GrowthProvider>;
}

That's the integration

Four things are now running. None of them needs another line of setup, and none of them needs an app release to change afterwards.

What you getWhere it goes
Eventsfirst_open, app_open, screen_viewed, element_tapped and friends, captured automaticallyEvent dictionary
ErrorsJavaScript and native crashes and unhandled rejections, with your console.error lines kept as breadcrumbsError tracking
EntitlementsGrowth.isSubscribed() — one answer, whether they paid through a store or the webClient-side gating
ExperimentsVariant assignment, decided server-side and delivered with your configA/B experiments

Everything else is one line, placed by hand

What's automatic above is purely structural — screens, taps. The SDK has no way to know that a tap means "user finished onboarding" or "generation succeeded"; that's your business logic, and only you know where it happens in your code. So every milestone that actually matters to your funnel is a manual call, placed once, at the moment it happens:

Anywhere in your app
import { Growth, logEvent } from "@fictura/sdk";

// name, status ("success" | "failure" | "info"), and any properties you want on it.
logEvent("generation_success", "success", { model: "large" });

// Something that went wrong on a path you care about.
try { await generate(); } catch (e) { Growth.captureError(e); }

This isn't "add logEvent everywhere" — it's one call per milestone in your funnel, not one per button. A typical app has 5–15 of these total: signup, onboarding done, your value moment, purchase. Place each one the first time you build that flow, and the event name you choose here is also what you'll type as an experiment's primary metric later — same string, same event.

Everything is server-driven

The SDK fetches config at launch, on every foreground and every 45 seconds while the app is in front, cached on device. Which paywall shows, which events are captured, which experiment a user is in, and whether error capture is on at all — each is decided in the dashboard and reaches installed apps on their next refresh. See SDK keys & config refresh.

Rendering a paywall

When you're ready to sell, GrowthPaywall renders whatever is live for its placement — a native template, a block design, or a served HTML design — and falls back to your fallback node when nothing is configured. To show one at a moment instead of on a screen, see Placements and campaigns.

Paywall.tsx
import { GrowthPaywall } from "@fictura/sdk";

<GrowthPaywall
  placement="default"
  onClose={() => router.back()}
  onPurchaseComplete={(packageId) => unlock(packageId)}
/>;

To sell anything, the SDK needs your store. If the app has react-native-purchases, it detects it and there is nothing to wire. Otherwise hand it a purchases adapter. With neither, paywalls render with no packages and nothing can be purchased.

Designs made in the editor or as HTML also need react-native-webview — npx expo install react-native-webview. Without it they show "Update the app to see this offer." Set legal: { termsUrl, privacyUrl } in Growth.init too, for the paywall's Terms and Privacy links.

Check unsent events survive a restart

The dashboard can't tell whether AsyncStorage is installed, so test it once. Your coding agent can walk you through this:

Note the count.

Read how many app_open events the app has so far, on Events or with the MCP get_tracking_plan tool.

Send one launch nowhere.

Set EXPO_PUBLIC_GROWTH_API_BASE to http://127.0.0.1:9, a port nothing listens on, and restart with npx expo start --clear. Open the app, wait five seconds, then close it fully.

Put it back and open it again.

Restore EXPO_PUBLIC_GROWTH_API_BASE, restart with npx expo start --clear, and open the app.

Read the count again.

It should go up by 2: the launch that had nowhere to go, and this one. If it goes up by 1, the first launch's events were lost, so check AsyncStorage is installed.

On this page