React Native

The SignalSeal React Native SDK is a thin bridge over the native iOS and Android SDKs. Same API on both platforms - pick the right SDK key for the platform the app is running on.

Requirements

• React Native 0.74 or higher
• iOS 15.0+ (iOS target)
• Android 5.0 / API 21+ (Android target)

Both legacy and new (TurboModule / JSI) React Native architectures are supported - the package's codegen handles it.

Install

npm install @signalseal/react-native
# or
yarn add @signalseal/react-native

iOS

cd ios && pod install

The bridge vendors the iOS SignalSeal framework - you do not need to add it as a separate Swift Package Manager or CocoaPods dependency.

Android

Autolinking handles it. The bridge transitively pulls the SignalSeal Android SDK from Maven Central. No manual changes to your Gradle files are required.

Initialize

Call configure(...) once on app startup - typically in your root component or a top-level index.ts.

import { SignalSealSDK } from '@signalseal/react-native'
import { Platform } from 'react-native'

SignalSealSDK.configure({
  apiKey: Platform.OS === 'ios' ? 'ak_ios_...' : 'ak_android_...',
})

Configuration parameters

SignalSealSDK.configure({
  apiKey: string
  isDebug?: boolean
  endpointBaseUrl?: string
  logLevel?: 'off' | 'error' | 'warn' | 'info' | 'debug'
  customerUserId?: string
  environment?: 'production' | 'sandbox'
  respectLimitAdTracking?: boolean
})

configure(...) is idempotent - calling it twice is safe. Argument shapes are validated on the JS side, so mistakes throw a readable SignalSealError synchronously instead of silently failing in the bridge.

Send events

import { SignalSealSDK, EventType } from '@signalseal/react-native'

SignalSealSDK.sendEvent(EventType.Purchase, {
  value: 9.99,
  proceeds: 6.99,
  currency: 'USD',
})

value is the gross amount in the buyer's currency. proceeds is optional - the net you keep after store commission and tax, in the same currency; pass it if you know it (e.g. from your receipt-validation backend). currency is the ISO-4217 code; omit it and value is treated as USD.

For events that don't fit any of the standard types, use EventType.Custom with a name:

SignalSealSDK.sendEvent(
  EventType.Custom,
  { steps: 5 },
  'onboarding_completed'
)

You can also pass a string event type (useful for dynamic instrumentation):

SignalSealSDK.sendEvent('PURCHASE', { value: 9.99, currency: 'USD' })

sendEvent(...) is fire-and-forget. Events queue in memory and flush in the background.

Event types

enum EventType {
  Install = 'INSTALL',
  Login = 'LOGIN',
  SignUp = 'SIGN_UP',
  Register = 'REGISTER',
  Purchase = 'PURCHASE',
  AddToCart = 'ADD_TO_CART',
  AddToWishlist = 'ADD_TO_WISHLIST',
  InitiateCheckout = 'INITIATE_CHECKOUT',
  StartTrial = 'START_TRIAL',
  Subscribe = 'SUBSCRIBE',
  LevelStart = 'LEVEL_START',
  LevelComplete = 'LEVEL_COMPLETE',
  TutorialComplete = 'TUTORIAL_COMPLETE',
  Search = 'SEARCH',
  ViewItem = 'VIEW_ITEM',
  ViewContent = 'VIEW_CONTENT',
  Share = 'SHARE',
  Custom = 'CUSTOM',
}

Set user attributes

SignalSealSDK.setUserAttributes({
  email: 'alice@example.com',
  firstName: 'Alice',
  country: 'US',
  externalId: 'user_42',
})

Available fields: email, phone, firstName, lastName, dob (ISO-8601 YYYY-MM-DD), gender, city, state, zip, country (ISO-3166-1 alpha-2), externalId.

iOS-only extras

Two iOS-specific helpers are exposed on the bridge. They're no-ops on Android, so it's safe to call them unconditionally.

Apple Search Ads

SignalSealSDK.enableAppleAdsAttribution()

Enable Apple Search Ads attribution for installs that came from Apple's ad inventory.

Automatic StoreKit 2 purchase tracking

SignalSealSDK.enablePurchaseTracking()

Listens to StoreKit 2 transaction updates and emits PURCHASE events automatically. Skip this if you already log purchases yourself or handle them through RevenueCat or SuperWall.

Helpers

Get the SignalSeal ID

A stable per-install ID, useful for bridging to RevenueCat, SuperWall, or your own backend.

const id = await SignalSealSDK.getSignalSealId()

Returns null until configure(...) has finished setting up.

Get attribution parameters

Returns the install's attribution data - the campaign that drove it, plus raw click IDs for any further server-side correlation.

const params = await SignalSealSDK.getAttributionParams()
// {
//   signalseal_id: '...',
//   signalseal_adnetwork: 'meta',
//   signalseal_campaign_id: '...',
//   fbclid: '...',
//   ...
// }

Organic installs return { signalseal_id: '...' } only. Attributed installs add signalseal_* keys plus any raw click IDs the original ad carried (gclid, fbclid, ttclid, wbraid, etc.).

Flush

Force-flush the in-memory event queue. Useful in tests.

await SignalSealSDK.flush()

Reset

Wipe all locally-stored SDK state - installation ID, queued events, cached user data. Use this for "log out" or "forget me" flows. The SDK re-mints an installation ID and re-fires the INSTALL event on the next call.

SignalSealSDK.resetData()

Disabled-state check

const disabled = await SignalSealSDK.isSdkDisabled()

Returns true if SignalSeal disabled the SDK on this device - usually because the API key was rejected. Reconfigure with a fresh key to recover.

Debug mode

Pass isDebug: true when configuring during development:

SignalSealSDK.configure({
  apiKey,
  isDebug: __DEV__,
})

In debug mode every event is tagged is_debug - events still appear in the SignalSeal dashboard so you can verify they look right, but they won't be forwarded to your ad networks.

What's next