SDK Quickstart
SDK 0.24.0Install 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.
npm install @fictura/sdk
npx expo install expo-secure-store expo-application expo-device expo-network @react-native-async-storage/async-storage{
"expo": {
"plugins": ["@fictura/sdk/plugin"]
}
}| Package | What you lose without it |
|---|---|
expo-secure-store, expo-application | A device id that stays stable across launches. |
@react-native-async-storage/async-storage | The 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.
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 get | Where it goes | |
|---|---|---|
| Events | first_open, app_open, screen_viewed, element_tapped and friends, captured automatically | Event dictionary |
| Errors | JavaScript and native crashes and unhandled rejections, with your console.error lines kept as breadcrumbs | Error tracking |
| Entitlements | Growth.isSubscribed() — one answer, whether they paid through a store or the web | Client-side gating |
| Experiments | Variant assignment, decided server-side and delivered with your config | A/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:
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.
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.