React Native Appstack SDK

Track events and revenue with this SDK. You will also be able to activate Apple Search Ads attribution for your iOS applications and retrieve detailed attribution parameters from both iOS and Android.

Installation

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

Platform Configuration

iOS Configuration:

• iOS version 14.3+ recommended to use Apple Search Ads

Add to ios/YourApp/Info.plist:

<key>NSAdvertisingAttributionReportEndpoint</key>
<string>https://ios-appstack.com/</string>

Please define in your ios/Podfile.properties.json the following mendatory elements :

{
  "expo.jsEngine": "hermes",
  "EX_DEV_CLIENT_NETWORK_INSPECTOR": "true",
  "newArchEnabled": "true"
}

Android configuration:

• Minimum SDK: Android 5.0 (API level 21)
• Target SDK: 34+
• Java Version: 17+

No additional configuration needed for Android - the SDK will work automatically after installation.

Quick start

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);
      
      if (Platform.OS === 'ios') {
        await AppstackSDK.enableAppleAdsAttribution();
      }
      
      // Get attribution parameters
      const attributionParams = await AppstackSDK.getAttributionParams();
      console.log('Attribution data:', attributionParams);
    };
    
    init();
  }, []);

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

  // ... your app
};

API

configure(apiKey: string): Promise<boolean>

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: 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');
}

sendEvent(eventType?: EventType | string, eventName?: string, parameters?: Record<string, any>): Promise<boolean>

Tracks custom events with optional parameters. Use this for all user actions you want to measure.

Parameters:

• eventType - Event type from the EventType enum (preferred method for standard events)
• eventName - Event name (for backward compatibility or custom event names)
• parameters - Optional parameters object (e.g., { revenue: 29.99, currency: 'USD', productId: '123' })

Returns: Promise that resolves to true if event was sent successfully

Examples:

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

// Using EventType enum (recommended)
await AppstackSDK.sendEvent(EventType.PURCHASE, null, { revenue: 29.99, currency: 'USD' });
await AppstackSDK.sendEvent(EventType.SIGN_UP);
await AppstackSDK.sendEvent(EventType.ADD_TO_CART);

// Using string event types
await AppstackSDK.sendEvent('PURCHASE', null, { revenue: 29.99, currency: 'USD' });
await AppstackSDK.sendEvent('SIGN_UP');

// Backward compatibility - using eventName only
await AppstackSDK.sendEvent(null, 'user_registration');
await AppstackSDK.sendEvent(null, 'purchase', { revenue: 29.99 });

// Custom events with custom names and parameters
await AppstackSDK.sendEvent(EventType.CUSTOM, 'my_custom_event', { 
  revenue: 15.50, 
  productId: 'prod_123',
  category: 'electronics'
});

Available EventType values:

• INSTALL, LOGIN, SIGN_UP, REGISTER
• PURCHASE, ADD_TO_CART, ADD_TO_WISHLIST, INITIATE_CHECKOUT, START_TRIAL, SUBSCRIBE
• LEVEL_START, LEVEL_COMPLETE
• TUTORIAL_COMPLETE, SEARCH, VIEW_ITEM, VIEW_CONTENT, SHARE
• CUSTOM (for application-specific events)

enableAppleAdsAttribution(): Promise<boolean> (iOS only)

Enables Apple Search Ads attribution tracking. Call this after configure() on iOS to track App Store install sources.

Returns: Promise that resolves to true if attribution was enabled successfully

Requirements:

• iOS 14.3+
• App installed from App Store or TestFlight
• Attribution data appears within 24-48 hours

Example:

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

getAppstackId(): Promise<string>

Get the Appstack ID (equivalent to an install ID).

Returns: Promise that will returns a string containing the Appstack ID

Example:

const appstackId = AppstackSDK.getAppstackId();

isSdkDisabled(): Promise<boolean>

Check if the SDK is disabled.

Returns: Promise that resolves to true if the SDK is disabled, false otherwise

Example:

const isDisabled = await AppstackSDK.isSdkDisabled();
if (isDisabled) {
  console.log('SDK is disabled');
}

getAttributionParams(): Promise<Record<string, any>>

Retrieve attribution parameters from the SDK. This returns all available attribution data that the SDK has collected.

Returns: Promise that resolves to an object containing attribution parameters (key-value pairs)

Returns data on success: Object with various attribution-related data depending on the platform and SDK configuration

Returns empty object: {} if no attribution parameters are available

Example:

const attributionParams = await AppstackSDK.getAttributionParams();
console.log('Attribution parameters:', attributionParams);

// Example output (varies by platform):
// {
//   "attribution_source": "google_play",
//   "install_timestamp": "1733629800",
//   "attributed": "true",
//   ...
// }

Use Cases:

• Retrieve attribution data for analytics
• Check if the app was attributed to a specific campaign
• Log attribution parameters for debugging
• Send attribution data to your backend server
• Analyze user acquisition sources

Advanced

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

Network Security:

• All API communications use TLS 1.2+ encryption
• Certificate pinning is implemented for additional security
• Requests are authenticated using your API key

Attribution Timing:

• Apple Search Ads attribution data appears within 24-48 hours after install
• Attribution is only available for apps installed from App Store or TestFlight
• Attribution requires user consent on iOS 14.5+ (handled automatically)

Platform Constraints:

• iOS: Requires iOS 13.0+, Apple Search Ads attribution needs iOS 14.3+
• Android: Minimum API level 21 (Android 5.0)
• React Native: 0.72.0+
• Xcode: 14.0+
• Java: 17.0+
• Node.js 16.0+
• Some Apple Search Ads features may not work in some development/simulator environments

Event Tracking:

• Event names are case-sensitive and must match be standardized (already done for Android but not for iOS)
• Revenue values needs to be converted to USD
• For now, we can't configure the endpoint to send the events for iOS, this will be patched in a future release.

Technical Limitations:

• SDK must be initialized before any tracking calls
• enableAppleAdsAttribution only works on iOS and will do nothing on Android.
• Network connectivity required for event transmission (events are queued offline)
• Some attribution features require app to be distributed through official stores

Documentation

• Complete Usage Guide
• GitHub Repository