@affiliateo/react-native

Affiliateo SDK for React Native. mobile affiliate attribution and screen tracking.

Install

npm install @affiliateo/react-native

Setup

Wrap your app with AffiliateoProvider. To get a complete funnel without adding tracking calls to every screen, also pass a React Navigation navigationRef. the SDK subscribes to navigation state changes and auto-fires one screen_view per route.

import { NavigationContainer, useNavigationContainerRef } from '@react-navigation/native';
import { AffiliateoProvider } from '@affiliateo/react-native';

export default function App() {
  const navigationRef = useNavigationContainerRef();
  return (
    <NavigationContainer ref={navigationRef}>
      <AffiliateoProvider
        appId="YOUR_APP_ID"
        navigationRef={navigationRef}
      >
        <YourApp />
      </AffiliateoProvider>
    </NavigationContainer>
  );
}

Without navigationRef the SDK still fires an entry screen_view at launch and a final one on background, but per-screen tracking would require manual .page() calls.

Track Screens manually (optional)

If you don't use React Navigation, or want to fire a specific custom screen name, call .page() from the context:

import { useAffiliateRef } from '@affiliateo/react-native';

function PricingScreen() {
  const { page } = useAffiliateRef();
  useEffect(() => { page('Pricing'); }, []);
  return <View>...</View>;
}

Track custom goals

Screen views auto-track. For specific moments that matter to your funnel (signup_completed, trial_started, etc.), call track():

import { useEffect } from 'react';
import { useAffiliateRef } from '@affiliateo/react-native';

function SignupSuccessScreen() {
  const { track } = useAffiliateRef();
  useEffect(() => {
    track('signup_completed', { plan: 'free' });
  }, []);
  return <View>...</View>;
}

Goal names: lowercase letters, digits, underscores, hyphens, colons. Max 64 chars. Optional metadata bounded to 4KB JSON.

Identify signed-in users (cross-device stitching)

Without identify(), the same person on phone + tablet counts as two visitors and your funnel splits. Call once after sign-in:

import { useEffect } from 'react';
import { useAffiliateRef } from '@affiliateo/react-native';
import { useUser } from './your-auth';

export default function App() {
  const { identify } = useAffiliateRef();
  const user = useUser();
  useEffect(() => {
    if (user) identify(user.id);
  }, [user]);
  return <NavigationContainer>...</NavigationContainer>;
}

Idempotent. safe to fire on every app launch while a user is signed in. user_id only. The SDK does not accept, collect, or transmit email or any other PII.

Get Affiliate Ref

import { useAffiliateRef } from '@affiliateo/react-native';

function MyComponent() {
  const { refCode, isMatched, isLoading } = useAffiliateRef();
  // ...
}

Apple Native IAP (StoreKit 2)

If your iOS app uses StoreKit 2 directly (not RevenueCat), pass the SDK's appAccountToken to your purchase call. Apple stamps it onto every transaction in the chain so we can credit the affiliate on every renewal and refund.

import { useAffiliateRef } from '@affiliateo/react-native';
import { requestPurchase } from 'expo-iap'; // or react-native-iap v14+

function BuyButton() {
  const { appAccountToken } = useAffiliateRef();

  async function buy() {
    await requestPurchase({
      sku: 'pro_monthly',
      appAccountTokenIOS: appAccountToken ?? undefined,
    });
  }

  return <Button onPress={buy} title="Subscribe" />;
}

Swift StoreKit 2 (if you have a Swift purchase layer):

let token = UUID(uuidString: affiliateoAppAccountToken)
let result = try await product.purchase(
  options: token.map { [.appAccountToken($0)] } ?? []
)

Requires iOS 15+. On Android (or before identify completes, or for unmatched users), appAccountToken is null.

How It Works

1. On first app open, the SDK sends a device fingerprint to Affiliateo
2. Affiliateo matches it against recent affiliate link clicks using IP + device signals
3. The SDK auto-sets the affiliateo_visitor_id attribute on RevenueCat (if installed) so every purchase links back to this device's tracked visitor (per-buyer spend, funnels, ad ROAS). If matched, it additionally:
   • Auto-sets the affiliateo_ref attribute on RevenueCat
   • Mints + registers a StoreKit 2 appAccountToken so Apple native purchases get attributed automatically
4. Screen views are batched and sent every 30s for funnel analytics
5. Events are persisted offline and flushed when connectivity returns

Giving affiliates free access

App owners can switch complimentary access on for an individual affiliate from their Affiliateo dashboard, which grants a promotional entitlement in their own RevenueCat project.

Nothing to add to your code. As of 4.7.0 the SDK reads your RevenueCat App User ID itself, on launch and on every foreground. If react-native-purchases isn't installed, or RevenueCat hasn't configured yet, it does nothing and tries again next time.

Before 4.7.0 this needed a setRevenueCatUser() call you had to add yourself. That call still exists if you want to control the timing:

import Purchases from 'react-native-purchases';
import { useAffiliateRef } from '@affiliateo/react-native';

const { setRevenueCatUser } = useAffiliateRef();

// after Purchases.configure(...) — optional, the SDK already does this
setRevenueCatUser(await Purchases.getAppUserID());

Sending the same id repeatedly is a no-op. RevenueCat issues an anonymous placeholder until your app calls Purchases.logIn(); the SDK re-reads on foreground and the server accepts exactly one upgrade from that placeholder to the real id.

An affiliate still has to have opened your app through their own referral link at least once, since that link is what tells us which device is theirs. Until then the owner sees a disabled switch reading "hasn't opened your app yet".

Notes:

• It's separate from identify() on purpose. Sign-in and RevenueCat setup happen at different moments, and your app may do one without the other.
• The value is write-once per device. Sending a different ID for a device that's already bound is rejected, so a tampered client can't repoint a device at another customer.
• No email or other PII is sent, same as identify().