SDK / API reference

This page lists the SDK APIs you are most likely to use when integrating SignalFox. The React Native SDK uses an imperative API: you call SignalFox.init() once (after you can build your integrations array, for example in useEffect), then use named exports such as trackFunnelStep anywhere in your app.

SignalFox.init and SignalFox

Initialize the SDK once per process. init is async and safe to call from useEffect.

import { useEffect, useMemo } from 'react';
import {
  SignalFox,
  reactNavigationIntegration,
} from '@asgami-digital/signalfox-react-native';

useEffect(() => {
  void SignalFox.init({
    apiKey: signalFoxApiKey,
    logOnly: false,
    integrations: [reactNavigationIntegration({ navigationRef })],
  });
}, [navigationRef]);

Options (SignalFoxInitOptions):

• apiKey (required): your SignalFox client API key
• integrations (optional): navigation, purchases, and other integrations
• logOnly (optional): when true, events are not sent to the network

The SignalFox object mirrors the same functions: SignalFox.init, SignalFox.destroy, SignalFox.trackFunnelStep, SignalFox.trackSubview, SignalFox.trackModalShown.

Call destroy() only in tests or when you must reset the SDK in the same JS process.

Named tracking helpers

Import and call these after init has completed (or queue them: the SDK buffers calls until the core is ready).

• trackFunnelStep(params) — in-screen funnel steps (same screen / modal)
• trackSubview(params) — important sections, tabs, or panels inside a screen
• trackModalShown(params) — modal-like UI that does not use React Native’s native Modal

Startup patches

Call these before your app renders (for example in index.js next to AppRegistry.registerComponent):

import {
  applyModalPatch,
  applyTouchablePatch,
} from '@asgami-digital/signalfox-react-native';

applyModalPatch();
applyTouchablePatch();

Use them so SignalFox can observe React Native modals and touchable/pressable interactions.

Navigation integrations

Configure exactly one navigation integration and pass it inside init:

reactNavigationIntegration({ navigationRef });
expoRouterIntegration({ navigationRef });

Use reactNavigationIntegration for React Navigation apps. Use expoRouterIntegration for Expo Router (see the library’s examples/expo-rniap for useNavigationContainerRef + useEffect).

Funnel steps (trackFunnelStep)

Use trackFunnelStep for multi-step experiences inside the same screen (or the same modal), not for screen-to-screen journeys (navigation already covers those).

import { trackFunnelStep } from '@asgami-digital/signalfox-react-native';

trackFunnelStep({
  funnelName: 'checkout',
  signalFoxNodeId: 'choose-plan',
  signalFoxNodeDisplayName: 'Choose plan',
  stepIndex: 2,
});

Public fields (camelCase):

• funnelName (required)
• signalFoxNodeId (required)
• signalFoxNodeDisplayName (optional)
• stepIndex (optional)

The backend still receives the canonical event shape (for example flow_step_view with flow_name, step_name, etc.); you only use the camelCase names above in app code.

Subviews (trackSubview)

import { trackSubview } from '@asgami-digital/signalfox-react-native';

trackSubview({
  signalFoxNodeId: 'billing-history',
  signalFoxNodeDisplayName: 'Billing history',
});

Manual modal-like surfaces (trackModalShown)

Use this when the surface behaves like a modal but is implemented with a sheet, overlay, portal, drawer, etc.

import { trackModalShown } from '@asgami-digital/signalfox-react-native';

trackModalShown({
  signalFoxNodeId: 'export-sheet',
  signalFoxNodeDisplayName: 'Export Sheet',
  visible: true,
});

Typical pattern with React state:

import { useEffect } from 'react';
import { trackModalShown } from '@asgami-digital/signalfox-react-native';

useEffect(() => {
  trackModalShown({
    signalFoxNodeId: 'export-sheet',
    signalFoxNodeDisplayName: 'Export Sheet',
    visible: isExportSheetVisible,
  });
}, [isExportSheetVisible]);

Fields:

• signalFoxNodeId: stable id for the surface
• signalFoxNodeDisplayName: optional readable label
• visible: true emits modal_open; false emits modal_close

Behavior notes:

• same path as the native Modal patch
• if you call visible: false for a surface that was never opened in the SDK’s modal stack, SignalFox does nothing

Purchase integrations

Pass purchase integrations in SignalFox.init:

revenueCatIntegration({ purchases, revenueCatUI });
reactNativeIapIntegration({ reactNativeIap });

revenueCatUI is optional. Pass it only if your app uses react-native-purchases-ui.

For react-native-iap, Nitro support was introduced in react-native-iap@14.4.0. Versions before 14.4.0 do not emit purchase_started automatically through the integration and need notifyPurchaseStarted() immediately before the purchase request.

Manual purchase functions

Use these only for custom purchase flows or unsupported libraries:

• notifyPurchaseStarted
• notifyPurchaseCancelled
• notifyPurchaseCompleted
• notifyPurchaseFailed
• notifyRestoreCompleted

react-native-iap legacy / pre-Nitro fallback

If your app uses react-native-iap before 14.4.0, call notifyPurchaseStarted() right before starting the purchase.

import { notifyPurchaseStarted } from '@asgami-digital/signalfox-react-native';

notifyPurchaseStarted();
await ReactNativeIap.requestPurchase({ sku: 'pro_monthly' });

Example for the other manual purchase helpers:

notifyPurchaseCompleted({
  productId: 'pro_monthly',
  productType: 'subscription',
  price: 7.99,
  currency: 'USD',
  environment: 'production',
});

Event names

You may see these event names in the dashboard:

• lifecycle: app_open, app_background, app_foreground, session_start, session_end
• navigation and surfaces: screen_view, subview_view, modal_open, modal_close
• interaction: component_press
• funnels (internal type): flow_step_view
• custom events: custom
• purchases: purchase_started, purchase_cancelled, purchase_completed, purchase_failed, subscription_started, trial_started, restore_completed