React Native SDK

Overview

The Appstack React Native SDK lets you:

• Track standardized and custom events
• Track revenue events with currency (for ROAS / optimization)
• Enable Apple Ads attribution on iOS
• Retrieve the Appstack installation ID and attribution parameters

Features (with examples)

SDK initialization

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

const apiKey = Platform.OS === 'ios' ? 'your-ios-api-key' : 'your-android-api-key';
await AppstackSDK.configure(apiKey);

Event tracking (standard + custom)

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

// Standard
await AppstackSDK.sendEvent(EventType.SIGN_UP);

// Custom
await AppstackSDK.sendEvent(EventType.CUSTOM, 'level_completed', { level: 12 });

Revenue tracking (recommended for all ad networks)

await AppstackSDK.sendEvent(EventType.PURCHASE, null, { revenue: 29.99, currency: 'EUR' });
// `price` is also accepted instead of `revenue`

Installation ID + attribution parameters

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

Apple Ads attribution (iOS)

import { Platform } from 'react-native';

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

Link to the npmjs.org repository

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

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+

Installation

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

Platform Configuration

iOS Configuration

Add to ios/YourApp/Info.plist:

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

Android Configuration

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 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();
      }
    };
    
    init();
  }, []);

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

  // ... your app
};

API Reference

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 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: Promise that resolves to true if event was sent successfully

Event Types:

• INSTALL - App installation (tracked automatically)
• 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

Examples:

// 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', 'level_completed', { level: 5, score: 1000 });

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

Enables Apple Ads attribution tracking. Call this after configure() and the ATT 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();
}

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):
// {
//   "appstack_id": "05696366-DC99-43FA-AB8F-7B83FACBD0A2",
//   "adsetname": "{{adset.name}}",
//   "adname": "{{ad.name}}",
//   "campaign_name": "{{campaign.name}}",
//   "site_source_name": "{{site_source_name}}",
//   "campaignid": "{{campaign.id}}",
//   "adid": "{{ad.id}}",
//   "adsetid": "{{adset.id}}",
//   "deeplink_id": "II17NXag",
//   "placement": "{{placement}}"
// }

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 Usage

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);

Error Handling

const trackUserAction = async (action: string, revenue?: number, currency?: string) => {
  try {
    const parameters: Record<string, any> = {};
    if (revenue != null) parameters.revenue = revenue;
    if (currency) parameters.currency = currency;
    const success = await AppstackSDK.sendEvent(action, null, Object.keys(parameters).length ? parameters : undefined);
    if (!success) {
      console.warn(`Failed to track event: ${action}`);
    }
  } catch (error) {
    console.error('SDK Error:', error);
  }
};

Common Event Patterns

// E-commerce events
const trackPurchase = (productId: string, price: number) => {
  AppstackSDK.sendEvent('PURCHASE', null, { 
    revenue: price, 
    product_id: productId,
    currency: 'USD'
  });
};

// User lifecycle events
const trackUserRegistration = (method: string) => {
  AppstackSDK.sendEvent('SIGN_UP', null, { method });
};

// Game progression
const trackLevelComplete = (level: number) => {
  AppstackSDK.sendEvent('CUSTOM', `level_${level}_completed`, { level });
};

Platform-Specific Considerations

iOS Features

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+)

import { Platform } from 'react-native';

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

Android Features

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 Considerations

API Key Protection

• Never commit API keys to version control
• Use environment variables or secure configuration
• Use different keys for development and production

// ✅ 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
• 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 iOS yet

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:

• Ensure event names match exactly with dashboard configuration
• Check network connectivity
• Verify API key is correct for the platform
• Events may take a few minutes to appear in dashboard

iOS Attribution not working:

• Ensure iOS version is 14.3+
• Verify app is installed from App Store or TestFlight
• Check that NSAdvertisingAttributionReportEndpoint is configured in Info.plist
• Allow 24-48 hours for attribution data to appear

EAC recommendations

Revenue events (all ad networks)

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

Meta matching (send once per installation, as early as possible)

To improve matching quality on Meta, send events including the following parameters if you can fullfill them:

• email
• name (first + last name in the same field)
• phone_number
• date_of_birth (recommended format: YYYY-MM-DD)

## Support

For questions or issues:
- Check the [GitHub Repository](https://github.com/appstack-tech/react-native-appstack-sdk)
- Review the [Complete Usage Guide](https://github.com/appstack-tech/react-native-appstack-sdk/blob/main/USAGE.md)
- Contact our support team
- Open an issue in the repository