react-native-nitro-skan-referrer

A React Native Nitro Module providing a unified API for:

• 🟢 Google Play Install Referrer (Android)
• 🔵 Apple SKAdNetwork Conversion Value Updates (iOS)

This library gives you a clean, modern, fully type-safe bridge to attribution signals across both mobile ecosystems.

[!IMPORTANT]

• Tested only on React Native 0.81+ with Nitro Modules.
• Install Referrer requires Google Play Store (not available on emulators).
• SKAdNetwork APIs require iOS 14+ (basic) and iOS 16.1+ (postback conversions).

📦 Installation

npm install react-native-nitro-skan-referrer react-native-nitro-modules

[!NOTE] This package ships a hybrid iOS + Android implementation using Nitro Modules. iOS supports SKAdNetwork conversion values. Android supports the Install Referrer API.

Demo

🧠 Overview

| Platform | API Used | Purpose | | ----------- | ----------------------------------- | ----------------------------------------------------------- | | Android | Google Play Install Referrer API | Retrieve install referrer, timestamps, instant install flag | | iOS | SKAdNetwork (14.0–16.1+ variations) | Update SKAN conversion values & postback conversion values |

Configuration

iOS

If you’re using SKAdNetwork postback APIs (iOS 16.1+), ensure the appropriate Apple SKAN entries exist in your Info.plist or entitlement file as required by your ad network.

No custom entitlements are required for this library.

Steps to get SKAN working

• Build your Release version

• Upload it to the App Store (production or TestFlight with StoreKit config)

• Serve an actual SKAdNetwork ad from:

1. Meta Ads

2. Google Ads

3. TikTok Ads

4. Snap Ads

5. Unity Ads

• Tap the ad → it opens your App Store page

• User installs the app from that ad

• User triggers events → SKAN conversion values are updated

• Apple sends a postback after 24–72 hours

• Ad network receives your conversion value

• Only then SKAN updates succeed.

Error 10 = "Not Eligible / Not a Valid Ad Conversion"

• Happens when testing in dev mode or apple does not know if your ad was served from an adnetwork

• So do test in production setting.

Android

No extra setup required — but:

✔ The device must have Google Play Store installed ✔ The app must be downloaded via Play Store for true referrer values ✔ API does NOT work on AOSP emulator

⚙️ Usage

import { useEffect, useState } from 'react';
import {
  View,
  Text,
  Button,
  ScrollView,
  Platform,
  ActivityIndicator,
} from 'react-native';

import {
  getInstallReferrer,
  registerAppForAdNetworkAttribution,
  updateConversionValue,
  updatePostbackConversionValue,
} from 'react-native-nitro-skan-referrer';

export default function App() {
  const [result, setResult] = useState<any>(null);
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState<string | null>(null);

  const fetchReferrerOrSkan = async () => {
    setLoading(true);
    setError(null);

    try {
      if (Platform.OS === 'android') {
        const data = await getInstallReferrer();
        setResult(data);
      } else {
        await registerAppForAdNetworkAttribution();

        // Update SKAN fine value
        const res = await updateConversionValue(12);

        // Or update postback values (iOS 16.1+)
        // const res = await updatePostbackConversionValue(12, 'high', true);

        setResult(res);
      }
    } catch (err: any) {
      console.error(err);
      setError(err?.message ?? 'Unknown error occurred');
    } finally {
      setLoading(false);
    }
  };

  return (
    <View style={{ padding: 20, flex: 1 }}>
      <Text style={{ fontSize: 22, fontWeight: '700', marginBottom: 20 }}>
        {Platform.OS === 'android'
          ? 'Install Referrer Demo'
          : 'SKAdNetwork Demo'}
      </Text>

      <Button title="Run Test" onPress={fetchReferrerOrSkan} />

      <View style={{ marginTop: 20, flex: 1 }}>
        {loading ? (
          <ActivityIndicator size="large" />
        ) : error ? (
          <Text style={{ color: 'red' }}>{error}</Text>
        ) : (
          <ScrollView>
            <Text>{JSON.stringify(result, null, 2)}</Text>
          </ScrollView>
        )}
      </View>
    </View>
  );
}

🧩 API Reference

Android Install Referrer

getInstallReferrer(): Promise<{
  success: boolean;
  data?: {
    installReferrer: string;
    referrerClickTimestampSeconds: number;
    installBeginTimestampSeconds: number;
    referrerClickTimestampServerSeconds: number;
    installBeginTimestampServerSeconds: number;
    googlePlayInstantParam: boolean;
    installVersion?: string;
  };
  error: string;
  errorMessage?: string;
}>

iOS SKAdNetwork

Register App

registerAppForAdNetworkAttribution(): Promise<SKANConversionResult>;

Update Conversion Value (iOS 14+)

updateConversionValue(fineValue: number): Promise<SKANConversionResult>;

Update Postback Conversion Value (iOS 16.1+)

updatePostbackConversionValue(
  fineValue: number,
  coarseValue: 'high' | 'medium' | 'low',
  lockWindow: boolean
): Promise<SKANConversionResult>;

🧩 Supported Platforms

| Platform | Status | | ----------------- | ---------------------- | | Android | ✅ Supported | | iOS 14–16.1+ | ✅ Supported | | iOS Simulator | ⚠️ SKAN not supported | | AOSP Emulator | ❌ Install Referrer N/A |

🤝 Contributing

PRs welcome!

• Development Workflow
• Sending a PR
• Code of Conduct

🪪 License

MIT © Gautham Vijayan

Made with ❤️ and Nitro Modules