Skip to main content

React Native SDK

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.0.1
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();
}

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) => {
  try {
    const success = await AppstackSDK.sendEvent(action, revenue);
    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
  • Revenue values should be in USD
  • 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

Support​

For questions or issues: