React Native

Automated

Prefer to automate this? The Appstack CLI detects your project, installs and configures the SDK, then verifies the result:

npx appstack-cli integrate

Already integrated? npx appstack-cli review audits it without changing any files.

AI-assisted

Use Cursor, Claude Code, or another AI to help you integrate the React Native SDK.

Open in Cursor

Repository

Here, you will find the npmjs.org react-native-appstack-sdk documentation. Please use the latest available version of the SDK. Current stable release: 3.5.1, published 22 September 2026. See the changelog for everything that changed.

Quickstart

Use this path when you only need the minimum production integration:

Install react-native-appstack-sdk.
Run cd ios && pod install for iOS projects.
Copy the Production API key from SDK in Appstack.
Call AppstackSDK.configure(...) from app startup code.
Send standard events such as 'LOGIN', 'SIGN_UP', 'PURCHASE', and 'SUBSCRIBE'.
Confirm events appear in the Appstack SDK page before enabling downstream integrations.

import { Platform } from 'react-native';
import AppstackSDK, { EventType } from 'react-native-appstack-sdk';

const apiKey = Platform.OS === 'ios'
  ? process.env.APPSTACK_IOS_API_KEY
  : process.env.APPSTACK_ANDROID_API_KEY;

await AppstackSDK.configure(apiKey);

await AppstackSDK.sendEvent(
  EventType.PURCHASE,
  { revenue: 29.99, currency: 'USD' }
);

Watch the video walkthrough

Claude

Codex

AI agent

Manual

Migrating from 2.x

The 3.0.0 release changed the two calls every integration makes. The public surface is otherwise the same, and the JavaScript API is unchanged by the TurboModule work underneath.

A 2.x-style call to either method now throws an error naming its replacement, rather than silently misbehaving. Both changes are mechanical, but neither is caught by a type check alone if you call from plain JavaScript.

configure takes an options object The positional signature, deprecated in 2.6.0, is gone. isDebug and endpointBaseUrl are removed outright: neither was ever forwarded to the native SDKs, so nothing is lost by dropping them.

// 2.x
await AppstackSDK.configure(apiKey, false, undefined, 0, 'user_123');

// 3.x
await AppstackSDK.configure(apiKey, { logLevel: 0, customerUserId: 'user_123' });

sendEvent takes two arguments The middle eventName argument is gone, and with it EventType.CUSTOM. Pass a standard EventType for a standard event, or your own name for a custom one:

// 2.x                                              // 3.x
sendEvent('PURCHASE', null, { revenue: 4.99 })  ->  sendEvent(EventType.PURCHASE, { revenue: 4.99 })
sendEvent('CUSTOM', 'user_attributes', params)  ->  sendEvent('user_attributes', params)
sendEvent('CUSTOM', 'APP_OPENED')               ->  sendEvent('APP_OPENED')

Other changes to check

sendEvent resolves void instead of true. The old true only ever meant “the call reached native” and was returned even when the event was then dropped. Stop branching on the result; await still works unchanged.
logLevel must be 0, 1, 2 or 3. A fractional value such as 1.5 previously passed validation and was silently truncated.
Parameter values of null or undefined are stripped before the call reaches native, so both platforms observe the same map. 0, false and '' are real values and are preserved.
parameters is typed as Record<string, JsonValue | undefined>. A Date, a class instance or a function is now a compile error rather than a value mangled in transit.
If you called new NativeEventEmitter(NativeModules.AppstackReactNative) on the legacy architecture, remove it. The iOS module no longer subclasses RCTEventEmitter; it never emitted any events.
A manual sendEvent('INSTALL') is dropped before reaching native, logging an error and resolving normally. The same applies to the SDK’s internal lifecycle events, which are not part of the public EventType API.

Older 2.x guidance remains available on the 2.x page, selectable from the version dropdown at the top of this page.

Requirements

iOS

iOS version: 15.0+
Xcode: 14.0+
React Native: 0.72.0+

Android

Minimum SDK: Android 5.0 (API level 21).
Target SDK: 35+
Java Version: 17+

General

Node.js: 16.0+
React Native architecture: both are supported. Since 3.0.0 the SDK is a real TurboModule generated by React Native’s codegen, with the legacy architecture still served by the same package and no configuration to choose between them.

On iOS, React Native 0.87 Swift Package Manager support is experimental as of 3.2.0. CocoaPods support is unchanged and remains the supported path.

Initial setup

Installation

npm install react-native-appstack-sdk
cd ios && pod install  # Only needed for iOS

Initialization

Follow these steps to get the API key:

In Appstack, from the side menu, select SDK and ensure you are selecting the correct application.
Select the Production environment.
Copy the API key.

Examples:

import { useEffect } from 'react';
import { Platform } from 'react-native';
import AppstackSDK, { EventType } from 'react-native-appstack-sdk';

const App = () => {
  useEffect(() => {
    const init = async () => {
      const apiKey = Platform.OS === 'ios'
        ? process.env.APPSTACK_IOS_API_KEY
        : process.env.APPSTACK_ANDROID_API_KEY;

      await AppstackSDK.configure(apiKey);

      // Request tracking permission and enable Apple Ads Attribution
      if (Platform.OS === 'ios') {
        await AppstackSDK.enableAppleAdsAttribution();
      }
    };

    init();
  }, []);

  const trackPurchase = () => {
    AppstackSDK.sendEvent(EventType.PURCHASE, { revenue: 29.99, currency: 'USD' });
  };

  // ... your app
};

Configuration parameters

Initializes the SDK with your API key. Call this from app startup code before any other SDK methods. The optional second argument carries logLevel and customerUserId; see the React Native API reference for the full signature and options.

const success = await AppstackSDK.configure('your-api-key-here');
if (!success) {
  console.error('SDK configuration failed');
}

logLevel accepts only 0 DEBUG, 1 INFO, 2 WARN, or 3 ERROR (default 1); a fractional value is rejected.

Customer user ID

The customer user ID is your own identifier for the signed-in user. Appstack attaches it to events so server-to-server events — which identify the user by this ID rather than by the install — can be joined back to the install that produced them.Set it as soon as it is known — at configure time via the customerUserId option, or later, most often once a login reveals it. It applies to every event sent from then on, including ones the native SDK has buffered but not yet flushed, and at least one event has to follow for it to take effect. See setCustomerUserId() in the API reference for the full semantics.

await AppstackSDK.setCustomerUserId('user_123');

Sending events

Track user actions and revenue in your app:

// Track events without parameters
await AppstackSDK.sendEvent(EventType.LOGIN);

// Track events with parameters (including revenue)
await AppstackSDK.sendEvent(
    EventType.PURCHASE, { revenue: 29.99, currency: 'USD' }
);

// Custom events: pass the name directly
await AppstackSDK.sendEvent('user_attributes', {
    email: "test@example.com",
    name: "John Doe",
    phone_number: "+33060000000",
    date_of_birth: "2026-02-01"
});

INSTALL is tracked automatically on SDK initialization. Do not send it manually. See the React Native API reference for the full signature, parameter details, and the complete list of EventType values.Enhanced app campaigns

When running enhanced app campaigns (EACs), it is highly recommended to send multiple parameters with the in-app event to improve matching quality.

For any event that represents revenue, send revenue or price (number) and currency (string, e.g. EUR, USD). To improve matching quality on Meta, also send these when you can:

email.
name (first + last name in the same field).
phone_number — also accepted as phone or phoneNumber.
date_of_birth (recommended format: YYYY-MM-DD) — also accepted as birthdate, birthday, or dateOfBirth.
gender.

Appstack encrypts these matching parameters on the device before they are sent (iOS 17+ and Android; on iOS 15–16 they are encrypted server-side instead), so no code change is required. Names that must stay readable — among them currency and revenue — are excluded, and revenue reporting is unaffected.

Appstack ID and attribution params

After configure, you can read the Appstack user ID and the attribution object for partner integrations (for example Superwall, RevenueCat).

const appstackId = await AppstackSDK.getAppstackId();
const attributionParams = (await AppstackSDK.getAttributionParams()) ?? {};

getAttributionParams() waits for the attribution match to finish, so you do not need a fixed delay after launch. For the full signatures and return values, see the React Native API reference. A matched install returns something like:

{
  "appstack_adnetwork": "meta",
  "appstack_campaign": "summer_sale",
  "appstack_adset": "lookalike_1pct",
  "appstack_ad": "video_15s",
  "appstack_id": "9f1c8b64-...",
  "appstack_match_status": "matched"
}

appstack_adnetwork is google, meta or tiktok. It is absent when the click carried no recognised network param — for a standard link, read media_source instead. On Google the campaign, ad set and ad values are numeric IDs rather than names. appstack_id comes back on every result, including organic ones, so read appstack_match_status rather than testing whether the result is empty. For the meaning of each appstack_match_status value and how to read it, see the React Native API reference.

Check for the key rather than assuming it is there — Android does not report it yet.

Development setup

Environment-based configuration

Set up different API keys for different environments:

// .env.development
APPSTACK_IOS_API_KEY=your_ios_dev_key
APPSTACK_ANDROID_API_KEY=your_android_dev_key

// .env.production
APPSTACK_IOS_API_KEY=your_ios_prod_key
APPSTACK_ANDROID_API_KEY=your_android_prod_key

import Config from 'react-native-config';

const apiKey = Platform.OS === 'ios'
  ? Config.APPSTACK_IOS_API_KEY
  : Config.APPSTACK_ANDROID_API_KEY;

await AppstackSDK.configure(apiKey);

Platform-specific considerations

iOS

Apple Ads attribution:

Only works on iOS 15.0+ (below that the call is a no-op)
Requires app installation from App Store or TestFlight.
Attribution is matched within seconds of the app opening.
User consent may be required for detailed attribution (iOS 14.5+).

import { Platform } from 'react-native';

const iosVersion = Number.parseFloat(String(Platform.Version));

if (Platform.OS === 'ios' && iosVersion >= 15.0) {
  await AppstackSDK.enableAppleAdsAttribution();
}

Android

Play Store attribution:

Install referrer data collected automatically.
Attribution available immediately for Play Store installs.
Works with Android 5.0+ (API level 21).

Cross-platform best practices

const initializeSDK = async () => {
  const apiKey = Platform.select({
    ios: process.env.APPSTACK_IOS_API_KEY,
    android: process.env.APPSTACK_ANDROID_API_KEY,
    default: process.env.APPSTACK_DEFAULT_API_KEY
  });

  if (!apiKey) {
    console.error('Appstack API key not configured');
    return;
  }

  const configured = await AppstackSDK.configure(apiKey);

  if (configured && Platform.OS === 'ios') {
    await AppstackSDK.enableAppleAdsAttribution();
  }
};

Security and privacy

API key protection

Never commit API keys to version control.
Use environment variables or secure configuration.
Use different keys for development and production.
Do not put personally identifiable information in event names.
Only send matching parameters such as email, name, phone_number, and date_of_birth when your app has the right consent and compliance basis. Appstack encrypts these fields on the device before they are sent.
Prefer standard event types for common flows so event mapping remains consistent across Appstack and ad integrations.

// ✅ Good - Use environment variables
const apiKey = Config.APPSTACK_API_KEY;

// ❌ Avoid - Hardcoded keys
const apiKey = "ak_live_1234567890abcdef"; // DON'T DO THIS

Data privacy

Event names and revenue data are transmitted securely over HTTPS.
No personally identifiable information (PII) should be included in event names.
The SDK does not collect device identifiers beyond what’s required for attribution.

Limitations

Attribution timing

iOS: Apple Ads attribution is matched within seconds of the app opening after install.
Android: Install referrer data available immediately for Play Store installs.
Attribution only available for apps installed from official stores.

Platform constraints

iOS: Requires iOS 15.0+
Android: Minimum API level 21 (Android 5.0).
React Native: 0.72.0+
Some Apple Ads features may not work in development/simulator environments.

Event tracking

Standard event names are resolved case-insensitively: 'purchase' and 'PURCHASE' both send the standard PURCHASE. Custom event names are recorded exactly as given, so their casing is preserved.
Parameters are passed as an object and can include any key-value pairs.
For revenue events, always pass a revenue (or price) and a currency parameter.
The SDK must be initialized from app startup code before any tracking calls.
Network connectivity required for event transmission (events are queued offline).

Technical limitations

enableAppleAdsAttribution() only works on iOS and will do nothing on Android.
sendEvent resolves void; nothing about delivery is observable from JavaScript. Do not branch on its result.
isDebug and endpointBaseUrl were removed in 3.0.0 along with the positional configure signature. A 2.x-style call now throws an error naming the replacement.

Troubleshooting

Common Issues

Configuration fails:

// Check if API key is valid
const success = await AppstackSDK.configure(apiKey);
if (!success) {
  console.error('Invalid API key or network issue');
}

Events not appearing in dashboard:

Check network connectivity.
Verify the API key is correct for the platform.
Events may take a few minutes to appear in the dashboard.

iOS Attribution not working:

Ensure iOS version is 15.0+
Verify the app is installed from the App Store or TestFlight.
Attribution is matched within seconds of the app opening.

Verification checklist

react-native-appstack-sdk is installed.
iOS dependencies are installed with cd ios && pod install.
App meets React Native 0.72.0+, Node 16.0+, iOS 15.0+, Android min SDK 21, target SDK 35+, and Java 17+ requirements.
Platform-specific API keys are configured for iOS and Android.
Production API keys are used in production builds.
Development API keys are used only in development builds.
configure(...) runs once from app startup code before any events.
The customer user ID is set — via configure(...) or setCustomerUserId(...) — as soon as it is known, and at least one event follows it.
iOS-only Apple Ads calls are guarded with Platform.OS === 'ios'.
INSTALL is not sent manually.
Login, signup, purchase, subscription, and other key app events use standard event names where possible.
Revenue events include revenue or price and currency.
Custom events pass the event name directly as the first argument to sendEvent.
Appstack ID and attribution params are available before wiring partner integrations.
Events are visible in the Appstack SDK page before launch.

Apple Ads

To start using the Apple Ads integration, click here to see the correct SDK documentation.

Support

For questions or issues:

Check the GitHub Repository.
Contact our support team at support@appstack.tech
Open an issue in the repository.

Use Cursor, Claude Code, or another AI to validate your existing Appstack React Native SDK integration.

Open in Cursor

Getting started

Mobile SDKs

Integrations

Products

Developer tools

Automated

AI-assisted

Repository

Quickstart

Migrating from 2.x

Requirements

iOS

Android

General

Initial setup

Appstack ID and attribution params

Development setup

Environment-based configuration

Platform-specific considerations

iOS

Android

Cross-platform best practices

Security and privacy

API key protection

Data privacy

Limitations

Attribution timing

Platform constraints

Event tracking

Technical limitations

Troubleshooting

Common Issues

Verification checklist

Apple Ads

Support

​Automated

​AI-assisted

​Repository

​Quickstart

​Migrating from 2.x

​Requirements

​iOS

​Android

​General

​Initial setup

​Appstack ID and attribution params

​Development setup

​Environment-based configuration

​Platform-specific considerations

​iOS

​Android

​Cross-platform best practices

​Security and privacy

​API key protection

​Data privacy

​Limitations

​Attribution timing

​Platform constraints

​Event tracking

​Technical limitations

​Troubleshooting

​Common Issues

​Verification checklist

​Apple Ads

​Support

Automated

AI-assisted

Repository

Quickstart

Migrating from 2.x

Requirements

iOS

Android

General

Initial setup

Appstack ID and attribution params

Development setup

Environment-based configuration

Platform-specific considerations

iOS

Android

Cross-platform best practices

Security and privacy

API key protection

Data privacy

Limitations

Attribution timing

Platform constraints

Event tracking

Technical limitations

Troubleshooting

Common Issues

Verification checklist

Apple Ads

Support