@attributehq/react-native-sdk

AttributeHQ React Native SDK — mobile attribution tracking with native iOS/Android bridge.

Wraps the native iOS SDK and Android SDK via React Native native modules for deterministic, high-accuracy attribution.

Requirements

• React Native >= 0.60
• iOS >= 14.0
• Android minSdk 21 (Android 5.0+)

Expo: Supported via EAS Build with the included config plugin. Not compatible with Expo Go (requires native compilation).

Installation

npm install @attributehq/react-native-sdk
# or
yarn add @attributehq/react-native-sdk

iOS Setup

The iOS pod depends on the AttributeHQ iOS SDK. Since the pod is not yet on CocoaPods trunk, add the source to your Podfile:

# ios/Podfile
pod 'AttributeHQ', :git => 'https://github.com/AttributeHQ/ios-sdk.git', :tag => '1.0.0'

Then install pods:

cd ios && pod install

Android Setup

Add JitPack to your project-level build.gradle (if not already present):

// android/build.gradle
allprojects {
    repositories {
        // ...existing repos...
        maven { url "https://jitpack.io" }
    }
}

No other Android setup is needed — the SDK dependency is resolved automatically.

Expo Setup

Add the config plugin to your app.json or app.config.js:

{
  "expo": {
    "plugins": [
      [
        "@attributehq/react-native-sdk",
        {
          "attPromptMessage": "We use this to deliver personalized ads and measure campaign performance."
        }
      ]
    ]
  }
}

The plugin automatically adds:

• iOS: NSUserTrackingUsageDescription to Info.plist (for ATT prompt)
• Android: INTERNET, ACCESS_NETWORK_STATE, and com.google.android.gms.permission.AD_ID permissions

Build with EAS:

eas build --platform all

Quick Start

import { AttributeHQ } from '@attributehq/react-native-sdk';

// Initialize at app startup (e.g., in a useEffect or before your root component)
await AttributeHQ.initialize({
  apiKey: 'ak_your_api_key',
  appId: 'your-app-uuid',
});

// Track events (fire-and-forget, synchronous)
AttributeHQ.track('signup', { method: 'email' });

// Track revenue
AttributeHQ.trackRevenue(1500, 'NGN', { product: 'premium_plan' });

// Identify user after login
AttributeHQ.identify('user_123', { email: '[email protected]' });

// Get attribution result
const attribution = await AttributeHQ.getAttribution();
if (attribution && !attribution.isOrganic) {
  console.log(`Attributed to: ${attribution.mediaSource}`);
}

API Reference

AttributeHQ.initialize(config)

Initialize the SDK. Must be called before any other method. This is the only async method.

await AttributeHQ.initialize({
  apiKey: 'ak_xxx',           // Required. Your API key.
  appId: 'your-app-uuid',     // Required. Your app UUID.
  enableDebugLogging: false,  // Optional. Enable debug logs. Default: false
  batchSize: 10,              // Optional. Events per batch before auto-flush. Default: 10
  flushInterval: 5,           // Optional. Auto-flush interval in seconds. Default: 5
  maxQueueSize: 100,          // Optional. Max events in offline queue. Default: 100
  requestATTOnInit: true,     // Optional. iOS only. Auto-request ATT on init. Default: true
  attDelaySeconds: 0,         // Optional. iOS only. Delay before ATT prompt. Default: 0
});

AttributeHQ.track(eventName, properties?)

Track a custom event. Fire-and-forget (synchronous, queued internally).

AttributeHQ.track('purchase', { item: 'gold_pack', amount: 500 });

AttributeHQ.trackRevenue(amount, currency?, properties?)

Track a revenue event.

AttributeHQ.trackRevenue(1500, 'NGN', { product: 'premium' });

AttributeHQ.identify(userId, properties?)

Identify a user (e.g., after login).

AttributeHQ.identify('user_123', { plan: 'pro' });

AttributeHQ.flush()

Manually flush all queued events to the server.

AttributeHQ.flush();

AttributeHQ.getAttribution()

Get the cached attribution result from the initial install tracking.

const result = await AttributeHQ.getAttribution();
// result: AttributionResult | null
// {
//   matchType: 'device_id' | 'fingerprint' | 'install_referrer' | 'organic',
//   confidence: number,
//   mediaSource: string | null,
//   campaignId: string | null,
//   isOrganic: boolean,
//   attributedTouchTime: number | null,
// }

AttributeHQ.requestTrackingPermission()

Request App Tracking Transparency permission (iOS 14+). On Android, always resolves with "authorized".

const status = await AttributeHQ.requestTrackingPermission();
// status: 'authorized' | 'denied' | 'restricted' | 'notDetermined'

AttributeHQ.isInitialized()

Check whether the SDK has been initialized.

if (AttributeHQ.isInitialized()) {
  AttributeHQ.track('app_open');
}

Screen Tracking (React Navigation)

The SDK includes a NavigationTracker for automatic screen view tracking with React Navigation v5+.

import { NavigationTracker } from '@attributehq/react-native-sdk';
import { NavigationContainer, useNavigationContainerRef } from '@react-navigation/native';

function App() {
  const navigationRef = useNavigationContainerRef();

  return (
    <NavigationContainer
      ref={navigationRef}
      onReady={() => NavigationTracker.enable(navigationRef)}
    >
      {/* your screens */}
    </NavigationContainer>
  );
}

This automatically tracks screen_view events with { screen_name: 'ScreenName' } on every navigation state change.

To disable:

NavigationTracker.disable();

Types

All TypeScript types are exported:

import type {
  AttributeHQConfig,
  AttributionResult,
  TrackingPermissionStatus,
} from '@attributehq/react-native-sdk';

How It Works

This SDK is a thin React Native bridge around the native SDKs:

• iOS: Calls the AttributeHQ iOS SDK via Swift native module. Supports IDFA collection (with ATT), device fingerprinting, and SKAdNetwork.
• Android: Calls the AttributeHQ Android SDK via Kotlin native module. Supports Google Play Install Referrer, GAID collection, and device fingerprinting.

Both native SDKs handle offline queueing, automatic install tracking on first launch, and background event flushing.

License

MIT