React Native

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

Repository

Here, you will find the npmjs.org react-native-appstack-sdk documentation. Please use the latest available version of the SDK.

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 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(
  'PURCHASE',
  null,
  { revenue: 29.99, currency: 'USD' }
);

Requirements

iOS

iOS version: 13.0+ (15.0+ required for Apple Ads attribution).
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+

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 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('PURCHASE', null, { 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.

Parameters:

apiKey (string, required): Your platform-specific API key from the Appstack dashboard.

Returns: A promise that resolves to true if configuration was successful.Example:

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

configure also accepts two trailing positional parameters: logLevel (0=DEBUG, 1=INFO, 2=WARN, 3=ERROR, default 1) and customerUserId. They sit behind two deprecated slots that the wrapper ignores, so pass undefined for both:

await AppstackSDK.configure('your-api-key-here', undefined, undefined, 0, 'user_123');

Sending events

Track user actions and revenue in your activities:

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

// Track events with parameters (including revenue)
await AppstackSDK.sendEvent(
    'PURCHASE', null, { revenue: 29.99, currency: 'USD' }
);
await AppstackSDK.sendEvent(
    'SUBSCRIBE', null, { revenue: 9.99, plan: 'monthly' }
);

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

Available EventType valuesIt is recommended to use standard events for a smoother experience.

INSTALL is tracked automatically on SDK initialization. Do not send it manually.

LOGIN/ SIGN_UP / REGISTER Authentication.
PURCHASE/ ADD_TO_CART/ ADD_TO_WISHLIST/ INITIATE_CHECKOUT/ START_TRIAL/ SUBSCRIBE Monetization.
LEVEL_START/ LEVEL_COMPLETE Game progression.
TUTORIAL_COMPLETE/SEARCH/ VIEW_ITEM/ VIEW_CONTENT/ SHARE Engagement.
CUSTOM For application-specific events.

Tracks custom events with optional parameters:

eventType Event type from EventType enum or string (e.g., ‘PURCHASE’, ‘LOGIN’).
eventName Event name for custom events (optional).
parameters Optional parameters object (e.g., { revenue: 29.99, currency: 'USD' }).

Returns: A promise that resolves to true if event was sent successfully.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, we recommend sending:

revenue or price (number).
currency(string, e.g. EUR, USD).

await AppstackSDK.sendEvent(
  'PURCHASE',
  null,
  { revenue: 4.99, currency: 'EUR' }
);

To improve matching quality on Meta, send events including the following parameters if you can fulfill them. Appstack automatically encrypts these matching parameters before using them for attribution matching.

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 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()) ?? {};

getAppstackId() — Appstack user identifier when a partner expects $appstackId or similar.
getAttributionParams() — Attribution payload (campaign, media source, click IDs, device identifiers where available) to forward to partners.

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 data appears within 24-48 hours.
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 automatically encrypts these fields before using them for attribution matching.
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 data appears within 24-48 hours 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 13.0+, Apple Ads attribution needs 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

Event types are case-sensitive (use uppercase like ‘PURCHASE’, ‘LOGIN’).
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.
The isDebug and endpointBaseUrl arguments still accepted by configure(...) are deprecated no-ops: they are not forwarded to the native SDKs and have no effect. Call configure(apiKey) and leave them out.

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.
Allow 24-48 hours for attribution data to appear.

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 13.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.
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 use 'CUSTOM' with a descriptive event name.
Appstack ID and attribution params are available before wiring partner integrations.
Events are visible in the Appstack SDK page before launch.

Superwall

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

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

API reference

Repository

Quickstart

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

Superwall

Apple Ads

Support

​Repository

​Quickstart

​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

​Superwall

​Apple Ads

​Support

Repository

Quickstart

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

Superwall

Apple Ads

Support