React Native

​

npmjs.org repository

​

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

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

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

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 Appple Ads Attribution
      if (Platform.OS === 'ios') {
        await AppstackSDK.enableAppleAdsAttribution();
      }
    };
    
    init();
  }, []);

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

  // ... your app
};

const success = await AppstackSDK.configure('your-api-key-here');
if (!success) {
  console.error('SDK configuration failed');
}

// 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" 
	}
);

AppStackAttributionSdk.sendEvent(
    EventType.PURCHASE,
    parameters = mapOf("revenue" to 4.99, "currency" to "EUR")
)

​

Advanced usage

​

Environment-based configuration

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

​

Platform-specific considerations

​

iOS

• 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

• 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
• The SDK must be initialized before any tracking calls
• Network connectivis ity 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

// Check if API key is valid
const success = await AppstackSDK.configure(apiKey);
if (!success) {
  console.error('Invalid API key or network issue');
}

• Check network connectivity
• Verify the API key is correct for the platform
• Events may take a few minutes to appear in the dashboard

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

​

Support

1. Check the GitHub Repository
2. Contact our support team at support@appstack.tech
3. Open an issue in the repository