> ## Documentation Index > Fetch the complete documentation index at: https://docs.appstack.tech/llms.txt > Use this file to discover all available pages before exploring further. # React Native You are an expert React Native engineer helping me integrate the Appstack React Native SDK into my app. You are running inside an IDE assistant such as Cursor or Claude Code and you can see my codebase. Use the reference below to fully wire the SDK. When I paste this prompt and share my project files, you should: 1. Provide the exact `npm`/`yarn` commands and any native steps (`pod install`, Gradle changes) required by the docs, using the installation details below. 2. Show precisely where to call `configure` in my React Native app startup code, producing ready-to-paste code based on the snippets below. 3. Check that environment-specific API keys (iOS vs Android) and platform conditionals are set up correctly. 4. List the complete sequence of steps you applied so I can confirm that every requirement from the documentation has been implemented. *** ## Reference: Appstack React Native SDK **Requirements** * iOS: 13.0+ (15.0+ required for Apple Ads attribution), Xcode 14.0+ * Android: Min SDK 21, Target SDK 35+, Java 17+ * React Native: 0.72.0+ * Node.js: 16.0+ **Installation** ```bash theme={null} npm install react-native-appstack-sdk cd ios && pod install # Only needed for iOS ``` (Install the **latest** published version from npm unless your project requires a specific range.) **Android configuration** * No extra Android setup is required beyond installing the package. You still need to call `configure` before using SDK methods. **Quickstart example** ```javascript theme={null} 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** ```javascript theme={null} const success = await AppstackSDK.configure('your-api-key-here'); if (!success) { console.error('SDK configuration failed'); } ``` **Sending events** ```javascript theme={null} // 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', } ); ``` **EventType values (recommended standard events):** * Authentication: `LOGIN`, `SIGN_UP`, `REGISTER` * Monetization: `PURCHASE`, `ADD_TO_CART`, `ADD_TO_WISHLIST`, `INITIATE_CHECKOUT`, `START_TRIAL`, `SUBSCRIBE` * Games: `LEVEL_START`, `LEVEL_COMPLETE` * Engagement: `TUTORIAL_COMPLETE`, `SEARCH`, `VIEW_ITEM`, `VIEW_CONTENT`, `SHARE` * Custom: `CUSTOM` **`sendEvent` parameters** * `eventType`: event type (e.g. `'PURCHASE'`, `'LOGIN'`, `'CUSTOM'`) * `eventName`: event name for custom events (optional, recommended when eventType is `CUSTOM`) * `parameters`: optional object (e.g. `{ revenue: 29.99, currency: 'USD' }`) **Enhanced app campaigns** * For revenue events, send: * `revenue` or `price` (number) * `currency` (e.g. `EUR`, `USD`) * To improve Meta matching, include when possible: * `email` * `name` (first + last name) * `phone_number` (also accepted as `phone` or `phoneNumber`) * `date_of_birth` (`YYYY-MM-DD`; also accepted as `birthdate`, `birthday`, or `dateOfBirth`) * `gender` * Appstack automatically encrypts these matching parameters before using them for attribution matching. ## **Repository** Here, you will find the [npmjs.org react-native-appstack-sdk documentation](https://www.npmjs.com/package/react-native-appstack-sdk). Please use the latest available version of the SDK. ## **Quickstart** Use this path when you only need the minimum production integration: 1. Install `react-native-appstack-sdk`. 2. Run `cd ios && pod install` for iOS projects. 3. Copy the **Production** API key from **SDK** in Appstack. 4. Call `AppstackSDK.configure(...)` from app startup code. 5. Send standard events such as `'LOGIN'`, `'SIGN_UP'`, `'PURCHASE'`, and `'SUBSCRIBE'`. 6. Confirm events appear in the Appstack SDK page before enabling downstream integrations. ```javascript theme={null} 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** ```text theme={null} npm install react-native-appstack-sdk cd ios && pod install # Only needed for iOS ``` Follow these steps to get the API key: 1. In Appstack, from the side menu, select **SDK** and ensure you are selecting the correct application. 2. Select the **Production** environment. 3. Copy the **API key**. Examples: ```javascript theme={null} 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 }; ``` 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: ```javascript theme={null} 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: ```javascript theme={null} await AppstackSDK.configure('your-api-key-here', undefined, undefined, 0, 'user_123'); ``` Track user actions and revenue in your activities: ```javascript theme={null} // 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 values** It 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: 1. `revenue` or `price` (number). 2. `currency`(string, e.g. `EUR`, `USD`). ```javascript theme={null} 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. 1. `email`. 2. `name` (first + last name in the same field). 3. `phone_number` — also accepted as `phone` or `phoneNumber`. 4. `date_of_birth` (recommended format: `YYYY-MM-DD`) — also accepted as `birthdate`, `birthday`, or `dateOfBirth`. 5. `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). ```javascript theme={null} 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: ```javascript theme={null} // .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 ``` ```javascript theme={null} 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+). ```javascript theme={null} 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** ```javascript theme={null} 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. ```javascript theme={null} // ✅ 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:** ```javascript theme={null} // 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](/Integrations/superwall) to see the correct SDK documentation. ## **Apple Ads** To start using the Apple Ads integration, [click here](/Integrations/apple-ads) to see the correct SDK documentation. ## **Support** For questions or issues: 1. Check the [GitHub Repository](https://github.com/appstack-tech/react-native-appstack-sdk). 2. Contact our support team at [support@appstack.tech](mailto:support@appstack.tech) 3. Open an issue in the repository. You are an expert React Native engineer reviewing my existing Appstack React Native SDK integration. You are running inside an IDE assistant such as Cursor or Claude Code and you can see my codebase. Your goal is to **validate that my integration fully matches the official React Native SDK documentation** and identify any missing or incorrect steps. When I paste this prompt and share my project files, you should: 1. **Installation & environment** * Inspect my project for: * The `react-native-appstack-sdk` dependency is present in `package.json` / the lockfile at a **current** release (not necessarily an old pinned version—compare with npm). * Required environment versions: React Native 0.72.0+, Node 16+, iOS 13.0+ (15.0+ required for Apple Ads), Android min SDK 21, target SDK 35+, Java 17+. * `pod install` having been run for iOS (Podfile and Pods state). * Call out any mismatches and give exact `npm`/`yarn` and `pod` commands or Gradle tweaks needed. 2. **iOS configuration (Apple Ads)** * Verify that Apple Ads attribution is only enabled on iOS and, if present, is called via `AppstackSDK.enableAppleAdsAttribution()` in a sensible place (after initialization and any ATT permission logic). 3. **Android configuration** * Confirm that: * No extra Android configuration is required beyond installing the package (per docs), but that my Gradle files still meet the documented requirements (minSdk 21+, target 35+, Java 17+, `mavenCentral()` etc.). * Flag any obvious Android config issues that could prevent the SDK from initializing or sending events. 4. **SDK initialization** * Locate where I call `AppstackSDK.configure(apiKey)` and verify: * It runs once from app startup code before any events are sent. * Platform-specific API keys are used correctly (e.g. `APPSTACK_IOS_API_KEY` vs `APPSTACK_ANDROID_API_KEY` via `Platform` or config libraries). * The success value is checked (where appropriate) and configuration failures are handled or logged. * Propose a clean, idiomatic initialization pattern if mine is missing, duplicated, or fragile. 5. **Event tracking implementation** * Find all uses of `AppstackSDK.sendEvent(...)` and check: * That standard event types are used where possible (`'LOGIN'`, `'SIGN_UP'`, `'REGISTER'`, `'PURCHASE'`, `'SUBSCRIBE'`, `'ADD_TO_CART'`, `'ADD_TO_WISHLIST'`, `'INITIATE_CHECKOUT'`, `'START_TRIAL'`, `'LEVEL_START'`, `'LEVEL_COMPLETE'`, `'TUTORIAL_COMPLETE'`, `'SEARCH'`, `'VIEW_ITEM'`, `'VIEW_CONTENT'`, `'SHARE'`). * Revenue events send `revenue` (or `price`) and `currency` in the `parameters` object. * Custom events use `'CUSTOM'` with an appropriate `eventName` and, for EAC / Meta, rich parameters such as `email`, `name`, `phone_number`, and `date_of_birth`, noting that Appstack automatically encrypts these matching parameters before using them for attribution matching. * Point out missing or inconsistent events and suggest concrete `sendEvent` calls that match my app’s user flows. 6. **Limitations & best practices** * Validate that my code respects key constraints: * SDK is configured from app startup code before any tracking calls. * iOS-only features like `enableAppleAdsAttribution()` are guarded with `Platform.OS === 'ios'`. * Event names are uppercase and case-sensitive, and PII is handled appropriately. * Flag any anti-patterns (e.g. reconfiguring the SDK repeatedly, sending events before init, insecure handling of API keys). 7. **Validation report & checklist** * Produce a concise report summarizing: * What is correctly implemented and safe across iOS and Android. * What is missing or misconfigured with specific files and code snippets to change.