O Insert Affiliate se integra ao RevenueCat para rastrear compras de assinaturas geradas por afiliados e calcular comissões automaticamente. A integração funciona armazenando um identificador de afiliado como atributo personalizado de assinante no RevenueCat e, em seguida, recebendo eventos do ciclo de vida da assinatura por meio de webhooks. Este guia cobre cada etapa da configuração.
Como a Integração Funciona
A integração entre o Insert Affiliate e o RevenueCat possui três componentes. Primeiro, o SDK do Insert Affiliate captura um identificador de afiliado quando um usuário clica em um link de afiliado ou insere um short code. Segundo, seu app grava esse identificador no RevenueCat como um atributo personalizado de assinante. Terceiro, o RevenueCat envia eventos de webhook ao Insert Affiliate sempre que ocorre um evento de assinatura, e o Insert Affiliate lê o atributo do afiliado no payload do webhook para creditar o afiliado correto.
Etapa 1: Configurar o RevenueCat
Se você ainda não tem uma conta no RevenueCat, crie uma em app.revenuecat.com/signup. Siga o guia de configuração de projeto do RevenueCat para configurar seu app, conectar suas credenciais da App Store e do Google Play e criar seus produtos e ofertas de assinatura.
O Insert Affiliate recomenda o RevenueCat como a integração mais fácil para a maioria dos desenvolvedores. Ele lida com assinaturas tanto no iOS quanto no Android, fornece notificações automáticas por webhook e oferece um plano gratuito disponível.
Etapa 2: Configurar o Painel do Insert Affiliate
No seu painel do Insert Affiliate em app.insertaffiliate.com/settings, defina a Verificação de Compra no Aplicativo como RevenueCat. Isso informa ao Insert Affiliate que ele deve esperar eventos de webhook do RevenueCat para a verificação de compras.
Etapa 3: Instalar o SDK do Insert Affiliate
O Insert Affiliate fornece SDKs para iOS (Swift), Android, React Native, Flutter, JavaScript/Capacitor e Unity. Cada SDK está disponível em seu respectivo repositório GitHub sob a organização Insert-Affiliate.
Instale o SDK para sua plataforma e inicialize-o com o seu company code. Por exemplo, em um app React Native, envolva seu app no componente DeepLinkIapProvider e chame a função initialize com o seu company code.
Etapa 4: Definir o Atributo Personalizado de Assinante
Esta é a etapa crítica que vincula a atribuição de afiliado aos assinantes do RevenueCat. Depois que o SDK do Insert Affiliate captura um identificador de afiliado, você deve gravá-lo no RevenueCat como um atributo personalizado de assinante com a chave insert_affiliate.
No React Native, o código fica assim:
const affiliateIdentifier = await returnInsertAffiliateIdentifier(); if (affiliateIdentifier) { await Purchases.setAttributes({"insert_affiliate": affiliateIdentifier}); }
O valor segue o formato SHORT_CODE-UUID, por exemplo SAVE20-a1b2c3d4-e5f6-7890-abcd-ef1234567890. O short code identifica o afiliado, e o UUID garante que cada atribuição seja única.
Você deve chamar esse código em dois lugares. Primeiro, imediatamente após um deep link ou short code definir o identificador de afiliado. Segundo, na inicialização do app, para garantir que o atributo seja sincronizado caso tenha sido definido em uma sessão anterior. O RevenueCat sincroniza atributos na inicialização do app, quando o app vai para segundo plano e nas compras, mas você também pode chamar Purchases.syncAttributesAndOfferingsIfNeeded() para forçar uma sincronização imediata.
O RevenueCat suporta até 50 atributos personalizados por assinante, com nomes de chave de até 40 caracteres e valores de até 500 caracteres.
Etapa 5: Configurar os Webhooks do RevenueCat
No seu painel do RevenueCat, navegue até as configurações do projeto, depois até Integrations e então até Webhooks. Adicione um novo webhook com a URL fornecida nas configurações do seu painel do Insert Affiliate.
Configure o webhook para enviar eventos apenas para a App Store (iOS) e a Google Play Store (Android). Se você também estiver usando o RevenueCat Web Billing ou o Stripe, não inclua essas fontes de eventos neste webhook. As transações Web e do Stripe são rastreadas separadamente por meio do Stripe Connect para evitar registros de comissão duplicados.
Os principais tipos de eventos de webhook do RevenueCat que o Insert Affiliate processa incluem INITIAL_PURCHASE, que é disparado quando uma nova assinatura ou período de teste começa, RENEWAL, que é disparado quando uma assinatura é renovada ou um período de teste converte para pago, CANCELLATION, que é disparado quando um usuário cancela, e EXPIRATION, que é disparado quando o acesso deve ser revogado.
Etapa 6: Definir as Taxas de Comissão
No seu painel do Insert Affiliate, configure sua estrutura de comissões. Você tem várias opções.
Defina uma taxa de comissão padrão global em Settings. Esta é a porcentagem base que todos os afiliados recebem. Você pode então substituí-la por taxas individuais de afiliado, selecionando um afiliado e definindo uma porcentagem de comissão personalizada.
Você também pode escolher a frequência de pagamento por afiliado. Defina-a como Initial Purchase mais Renewals se quiser que o afiliado ganhe comissão em cada renovação dos assinantes que ele indicou. Defina-a como Initial Purchase Only se quiser um pagamento único por assinante.
Para a dedução da taxa da plataforma, ative Deduct Platform Fees Before Commission nas suas configurações se quiser que as comissões sejam calculadas sobre o valor líquido após a Apple ou o Google ficarem com sua parte. Configure as taxas da plataforma para corresponder aos seus acordos reais, sejam os 30 por cento padrão, a taxa de 15 por cento do Small Business Program ou as taxas reduzidas do Google Play.
Como as Comissões São Calculadas em Eventos de Assinatura
Quando o RevenueCat envia um webhook ao Insert Affiliate, o sistema o processa da seguinte forma. Ele lê o tipo de evento para determinar se é uma compra inicial, uma renovação ou outro evento. Ele extrai o atributo personalizado insert_affiliate dos dados do assinante. Ele localiza o afiliado associado a esse identificador. Ele calcula a comissão com base no valor da transação e na taxa configurada do afiliado, aplicando as deduções de taxa da plataforma, se estiverem ativadas.
Por exemplo, com uma assinatura mensal de 9,99 USD, uma taxa de afiliado de 10 por cento e a dedução de taxa da plataforma ativada em 30 por cento, o cálculo seria: 9,99 USD menos 3,00 USD de taxa da loja é igual a 6,99 USD líquidos, e 10 por cento de 6,99 USD é igual a 0,70 USD de comissão do afiliado.
Se a frequência de pagamento estiver configurada para incluir renovações, essa comissão é gerada em cada evento RENEWAL para aquele assinante, proporcionando ao afiliado uma receita contínua enquanto o usuário permanecer assinante.
Testando a Integração
Antes de ir para produção, teste o fluxo completo usando transações em sandbox. Crie um afiliado de teste no seu painel do Insert Affiliate usando um alias de e-mail como [email protected]. Na sua build de desenvolvimento, use um short code para definir o identificador de afiliado e, em seguida, faça uma compra em sandbox.
O RevenueCat rotula claramente as transações em sandbox no painel do Insert Affiliate, para que você possa distinguir as compras de teste dos dados de produção. Verifique se a transação aparece com a atribuição de afiliado e o valor da comissão corretos.
Solucionando Problemas Comuns
Se as transações não estiverem aparecendo no seu painel, verifique o seguinte. Verifique se a URL do webhook no RevenueCat corresponde exatamente à URL fornecida pelo Insert Affiliate. Confirme se o atributo insert_affiliate está sendo definido antes de a compra ocorrer, verificando a página de atributos de cliente do RevenueCat para o assinante de teste. Garanta que o seu painel do Insert Affiliate esteja com a Verificação de Compra no Aplicativo definida como RevenueCat.
Se o identificador de afiliado não estiver sendo capturado, verifique se a sua plataforma de deep linking está configurada corretamente e se o SDK do Insert Affiliate é inicializado antes de os usuários interagirem com links de afiliado ou short codes.
Principais Conclusões
A integração entre o Insert Affiliate e o RevenueCat exige definir um atributo personalizado de assinante chamado insert_affiliate nos assinantes do RevenueCat, configurar um webhook do RevenueCat para o Insert Affiliate e definir suas regras de comissão no painel do Insert Affiliate. Uma vez configurado, o sistema rastreia automaticamente compras iniciais, conversões de período de teste e renovações de assinatura, calculando e registrando comissões para cada evento sem nenhum trabalho manual contínuo.