> ## 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` and other SDK methods in my React Native app (e.g. root component, initialization hooks), 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+ (14.3+ recommended for Apple Ads), Xcode 14.0+ * Android: Min SDK 21, Target SDK 34+, 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 setup is required beyond installing the package; SDK works automatically after installation. **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_WISHLIST`, `INITIATE_CHECKOUT`, `START_TRIAL`, `SUBSCRIBE` * Games: `LEVEL_START`, `LEVEL_COMPLETE` * Engagement: `TUTORIAL_COMPLETE`, `SEARCH`, `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` * `date_of_birth` (`YYYY-MM-DD`) ## **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. ### **npmjs.org repository** Here, you will find the [npmjs.org](http://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. ## **Requirements** ### **iOS** * **iOS version:** 13.0+ (14.3+ recommended for Apple Ads). * **Xcode:** 14.0+ * **React Native:** 0.72.0+ ### **Android** * **Minimum SDK:** Android 5.0 (API level 21). * **Target SDK:** 34+ * **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. Must be called before any other SDK methods. Parameters: * `apiKey`  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'); } ``` 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_WISHLIST`/ `INITIATE_CHECKOUT`/ `START_TRIAL`/ `SUBSCRIBE`  Monetization. * `LEVEL_START`/ `LEVEL_COMPLETE` Game progression. * `TUTORIAL_COMPLETE`/`SEARCH`/ `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} AppstackAttributionSdk.sendEvent( EventType.PURCHASE, parameters = mapOf("revenue" to 4.99, "currency" to "EUR") ) ``` To improve matching quality on Meta, send events including the following parameters if you can fulfill them: 1. `email`. 2. `name` (first + last name in the same field). 3. `phone_number`. 4. `date_of_birth` (recommended format: `YYYY-MM-DD`). ## **Advanced usage** ### **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 14.3+ * 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'; if (Platform.OS === 'ios' && Platform.Version >= '14.3') { 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 considerations** ### **API key protection** * Never commit API keys to version control. * Use environment variables or secure configuration. * Use different keys for development and production. ```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 14.3+ * **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 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. * For now, iOS endpoint configuration cannot be customized (will be patched in future release). * Event name standardization is done for Android, but not for iOS yet. ## **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 14.3+ * Verify the app is installed from the App Store or TestFlight. * Allow 24-48 hours for attribution data to appear. ## **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+ (14.3+ recommended for Apple Ads), Android min SDK 21, target SDK 34+, 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 34+, 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 on app startup (e.g. in the root component via `useEffect`, or an App initialization layer) 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_WISHLIST'`, `'INITIATE_CHECKOUT'`, `'START_TRIAL'`, `'LEVEL_START'`, `'LEVEL_COMPLETE'`, `'TUTORIAL_COMPLETE'`, `'SEARCH'`, `'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`. * 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 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.