Como Implementar Rastreamento de Afiliados em um App React Native com IAPs

O Que Você Vai Construir

Ao final deste tutorial, seu app React Native atribuirá as compras dentro do aplicativo aos afiliados que as geraram. Quando um usuário clica em um link de afiliado, abre seu app e faz uma compra, a transação aparecerá no seu painel da Insert Affiliate com o afiliado correto creditado e a comissão calculada.

A integração usa o pacote insert-affiliate-react-native-sdk e leva cerca de 30 minutos para ser concluída.

Pré-requisitos

• React Native 0.60 ou posterior
• iOS 13.0+ / Android API 21+
• Um Company Code do seu painel da Insert Affiliate (página de Configurações)
• Uma plataforma de verificação de compras configurada (este tutorial usa RevenueCat, mas o SDK também suporta Adapty, Apphud, Iaptic, App Store direto e Google Play direto)

Passo 1: Instale o SDK

Instale o SDK da Insert Affiliate e suas dependências de pares necessárias:

npm install insert-affiliate-react-native-sdk
npm install @react-native-async-storage/async-storage @react-native-clipboard/clipboard @react-native-community/netinfo react-native-device-info axios

Para projetos React Native puros (bare), instale os pods do iOS:

cd ios && pod install && cd ..

Para o fluxo gerenciado do Expo, pule a instalação dos pods. Os pods são instalados automaticamente quando você executa npx expo prebuild ou npx expo run:ios.

Passo 2: Envolva Seu App com o Provider

O SDK usa o React Context para gerenciar o estado. Envolva seu app com o DeepLinkIapProvider no seu arquivo de entrada (index.js):

import React from 'react';
import { AppRegistry } from 'react-native';
import App from './App';
import { name as appName } from './app.json';
import { DeepLinkIapProvider } from 'insert-affiliate-react-native-sdk';

const RootComponent = () => {
  return (
    
      
    
  );
};

AppRegistry.registerComponent(appName, () => RootComponent);

Passo 3: Inicialize o SDK

No seu App.tsx, chame initialize() com o seu Company Code:

import React, { useEffect } from 'react';
import { useDeepLinkIapProvider } from 'insert-affiliate-react-native-sdk';

const App = () => {
  const { initialize, isInitialized } = useDeepLinkIapProvider();

  useEffect(() => {
    if (!isInitialized) {
      initialize(
        "YOUR_COMPANY_CODE",
        true,   // verbose logging (disable in production)
        true,   // enable Insert Links
        false   // clipboard attribution
      );
    }
  }, [initialize, isInitialized]);

  return ;
};

Quando a inicialização for bem-sucedida, você verá isto no seu console:

[Insert Affiliate] SDK initialized with company code: YOUR_COMPANY_CODE

Passo 4: Conecte-se ao RevenueCat

Este é o passo crítico que faz a ponte entre a atribuição de afiliados e o rastreamento de compras. Quando o SDK detecta um identificador de afiliado (de um deep link ou short code), você o passa ao RevenueCat como um atributo de assinante:

import React, { useEffect } from 'react';
import { AppState } from 'react-native';
import Purchases from 'react-native-purchases';
import { useDeepLinkIapProvider } from 'insert-affiliate-react-native-sdk';

const App = () => {
  const {
    initialize,
    isInitialized,
    setInsertAffiliateIdentifierChangeCallback,
    isAffiliateAttributionValid,
    getAffiliateExpiryTimestamp
  } = useDeepLinkIapProvider();

  useEffect(() => {
    if (!isInitialized) {
      initialize("YOUR_COMPANY_CODE", true, true, false);
    }
  }, [initialize, isInitialized]);

  useEffect(() => {
    setInsertAffiliateIdentifierChangeCallback(async (identifier, offerCode) => {
      if (identifier) {
        await Purchases.setAttributes({
          "insert_affiliate": identifier,
          "affiliateOfferCode": offerCode || "",
          "insert_timedout": ""
        });
        await Purchases.syncAttributesAndOfferingsIfNeeded();
      }
    });

    return () => setInsertAffiliateIdentifierChangeCallback(null);
  }, [setInsertAffiliateIdentifierChangeCallback]);

  useEffect(() => {
    if (!isInitialized) return;

    const clearExpiredAffiliation = async () => {
      const isValid = await isAffiliateAttributionValid();
      if (!isValid) {
        const expiryTimestamp = await getAffiliateExpiryTimestamp();
        if (!expiryTimestamp) return;

        await Purchases.setAttributes({
          "affiliateOfferCode": "",
          "insert_timedout": expiryTimestamp.toString()
        });
        await Purchases.syncAttributesAndOfferingsIfNeeded();
      }
    };

    clearExpiredAffiliation();

    const subscription = AppState.addEventListener('change', (state) => {
      if (state === 'active') {
        clearExpiredAffiliation();
      }
    });

    return () => subscription?.remove();
  }, [isInitialized, isAffiliateAttributionValid, getAffiliateExpiryTimestamp]);

  return ;
};

O callback é disparado toda vez que o identificador de afiliado muda. O atributo insert_timedout armazena o timestamp de expiração para que o webhook possa comparar as datas das compras com a janela de atribuição.

Passo 5: Configure o Webhook do RevenueCat

1. No RevenueCat, crie um novo webhook.
2. Defina a URL do Webhook como https://api.insertaffiliate.com/v1/api/revenuecat-webhook.
3. Defina o Tipo de Evento como "All events".
4. No seu painel da Insert Affiliate, em Configurações, defina o método de Verificação de Compra no Aplicativo como RevenueCat.
5. Copie o valor do RevenueCat Webhook Authentication Header do painel da Insert Affiliate.
6. Cole-o no campo do cabeçalho Authorization na configuração do webhook do RevenueCat.

Passo 6: Configure o Deep Linking (iOS)

Atualize seu ios/YourApp/AppDelegate.mm para lidar com URLs recebidas:

#import 

- (BOOL)application:(UIApplication *)application
            openURL:(NSURL *)url
            options:(NSDictionary *)options
{
  return [RCTLinkingManager application:application openURL:url options:options];
}

- (BOOL)application:(UIApplication *)application continueUserActivity:(NSUserActivity *)userActivity
 restorationHandler:(void(^)(NSArray * __nullable restorableObjects))restorationHandler
{
  return [RCTLinkingManager application:application
                   continueUserActivity:userActivity
                     restorationHandler:restorationHandler];
}

Adicione seu esquema de URL do iOS ao Info.plist e, para Universal Links, adicione applinks:insertaffiliate.link aos Associated Domains no Xcode.

Passo 7: Configure o Deep Linking (Android)

Adicione um intent filter à sua activity principal em android/app/src/main/AndroidManifest.xml:

Para Android App Links, adicione um segundo intent filter com android:autoVerify="true" e android:host="insertaffiliate.link". Defina android:launchMode="singleTop" na sua activity.

Passo 8: Lide com o Expo Router (Se Aplicável)

Se você usar o Expo Router, crie app/+native-intent.tsx para evitar conflitos de rotas:

export function redirectSystemPath({ path }: { path: string }): string | null {
  if (path.includes('insert-affiliate') || path.includes('insertAffiliate')) {
    return null;
  }
  return path;
}

Passo 9: Teste a Integração

Crie um afiliado de teste no seu painel da Insert Affiliate usando um alias de e-mail (por exemplo, [email protected]). Em seguida, teste o deep link:

# iOS Simulator
xcrun simctl openurl booted "https://insertaffiliate.link/YOUR_COMPANY_CODE/TEST_SHORT_CODE"

# Android Emulator
adb shell am start -a android.intent.action.VIEW -d "https://insertaffiliate.link/YOUR_COMPANY_CODE/TEST_SHORT_CODE"

Verifique se o identificador de afiliado está armazenado conferindo os logs do console, depois faça uma compra em sandbox e confirme que a transação aparece no seu painel.

Usando Outras Plataformas de Verificação de Compra

Se você usar o Adapty em vez do RevenueCat, o callback do identificador define um atributo personalizado via adapty.updateProfile(). Para o Iaptic, chame validatePurchaseWithIapticAPI() do SDK. Para a integração direta com a App Store, chame returnUserAccountTokenAndStoreExpectedTransaction() antes de cada compra. Para o Google Play direto, chame storeExpectedStoreTransaction() com o token de compra após cada compra.

As etapas de deep linking e de inicialização do SDK permanecem as mesmas, independentemente da plataforma de verificação de compra que você escolher.

Recursos Avançados

Uma vez que a integração básica esteja funcionando, considere adicionar:

• Short codes: Permita que afiliados compartilhem códigos como "SAVE20" que os usuários digitam no seu app. Chame setShortCode(code) para validar e armazenar.
• Offer codes dinâmicos: Configure modificadores de offer code no painel e use OfferCode do SDK para construir IDs de produto dinâmicos.
• Rastreamento de eventos: Rastreie eventos personalizados como cadastros com trackEvent('user_signup') para estruturas de comissão além das compras.
• Tempo limite de atribuição: Defina um limite de tempo para quanto tempo a atribuição de afiliado permanece ativa, como 7 dias (604.800 segundos).
• Impedir transferência de afiliado: Trave a primeira atribuição de afiliado para que cliques em links subsequentes não possam sobrescrevê-la.