RevenueCat Web Billing

Rastreie comissões em assinaturas web usando o RevenueCat Web SDK com Web Billing - gerenciando assinaturas diretamente pela plataforma web do RevenueCat.

Ao ativar o rastreamento do RevenueCat Web Billing, você pode atribuir assinaturas web a afiliados passando parâmetros UTM como metadados de compra.

O que você pode rastrear

Uma vez configurado, o Insert Affiliate rastreia automaticamente:

  • Assinaturas web do RevenueCat feitas através do Web SDK
  • Compras iniciais de assinatura
  • Renovações de assinatura
  • Todas as transações gerenciadas pelo sistema de web billing do RevenueCat

Pré-requisitos

Antes de configurar o rastreamento do Insert Affiliate, você precisa ter:

  • RevenueCat Web SDK instalado e configurado
  • RevenueCat Web Billing configurado com o Stripe
  • Insert Affiliate SDK inicializado na sua página
  • Stripe Connect configurado no seu painel do Insert Affiliate

Configuração do webhook do RevenueCat

Importante: Ao configurar o seu webhook do RevenueCat para enviar eventos ao Insert Affiliate, você deve enviar apenas eventos da App Store e da Google Play Store - não eventos do Stripe ou do Web Billing.

Como o Insert Affiliate recebe eventos do Stripe diretamente através do Stripe Connect (configurado na Etapa 1 abaixo), enviar eventos de webhook do RevenueCat para transações do Stripe/Web Billing resultaria em rastreamento duplicado de transações.

Para configurar o seu webhook do RevenueCat:

  1. Acesse o seu painel do RevenueCat → Project Settings → Integrations → Webhooks
  2. Ao configurar o webhook do Insert Affiliate, configure-o para enviar eventos apenas para:
    • App Store (iOS)
    • Google Play Store (Android)
  3. Não inclua eventos do Stripe ou do Web Billing neste webhook

Isso garante uma atribuição limpa: transações móveis são rastreadas via webhooks do RevenueCat, enquanto transações web são rastreadas via Stripe Connect.

Guia de configuração

Etapa 1: Conecte sua conta do Stripe via Stripe Connect

Como o RevenueCat Web Billing usa o Stripe nos bastidores, você precisa conectar sua conta do Stripe ao Insert Affiliate:

  1. Acesse Settings → Stripe Connect
  2. Clique em "Connect with Stripe"
  3. Conclua o processo de onboarding do Stripe:
    • Faça login na sua conta existente do Stripe (a mesma conectada ao RevenueCat)
    • Forneça as informações comerciais necessárias
    • Envie os documentos de verificação (se solicitado)
  4. Você será redirecionado de volta ao Insert Affiliate quando concluir

Indicadores de status:

  • Active: Sua conta do Stripe está totalmente conectada e pronta
  • Restricted: Informações adicionais necessárias - clique em "Continue Onboarding"
  • Pending: Documentos em análise (geralmente 1-2 dias úteis)

✅ Assim que sua conta do Stripe estiver conectada, o Insert Affiliate receberá automaticamente os eventos do Stripe das transações do RevenueCat.

Implementação: Integração do SDK

Etapa 1: Instale o SDK do Insert Affiliate

Adicione o SDK do Insert Affiliate à sua aplicação web:

npm install insert-affiliate-js-sdk

Etapa 2: Inicialize ambos os SDKs

Inicialize tanto o SDK do Insert Affiliate quanto o RevenueCat Web SDK:

import { InsertAffiliate } from 'insert-affiliate-js-sdk';
import { Purchases } from '@revenuecat/purchases-js';

// Initialize Insert Affiliate SDK
await InsertAffiliate.initialize('your_company_code');

// Initialize RevenueCat Web SDK
const purchases = Purchases.configure('your_revenuecat_web_api_key');

Etapa 3: Passe os dados do afiliado durante a compra

Antes de fazer uma compra, recupere o identificador do afiliado e o ID da empresa, depois passe-os como parâmetros UTM nos metadados da compra:

// Get the current affiliate identifier and company ID
// Use ignoreTimeout: true to get the identifier even if attribution window expired
const affiliateId = await InsertAffiliate.returnInsertAffiliateIdentifier(true);
const companyId = await InsertAffiliate.returnCompanyId();

console.log('Affiliate ID:', affiliateId || 'none');
console.log('Company ID:', companyId || 'none');

// Prepare metadata with UTM parameters for RevenueCat Web Billing
const metadata: Record<string, string> = {};

if (affiliateId && affiliateId !== 'none') {
  metadata.utm_source = 'insertAffiliate';
  metadata.utm_medium = companyId || 'none';
  metadata.utm_campaign = affiliateId;
}

console.log('Purchase metadata:', JSON.stringify(metadata, null, 2));

// Get offerings and select a package
const offerings = await purchases.getOfferings();
const selectedPackage = offerings.current?.availablePackages[0];

if (!selectedPackage) {
  console.error('No packages available');
  return;
}

// Make the purchase with metadata
const { customerInfo } = await purchases.purchase({
  rcPackage: selectedPackage,
  metadata: metadata,
});

console.log('Purchase successful!');
console.log('Active entitlements:', Object.keys(customerInfo.entitlements.active));

Parâmetros UTM obrigatórios

Os seguintes parâmetros UTM são obrigatórios para a atribuição correta do afiliado:

  • utm_source: Sempre definido como 'insertAffiliate' para identificar conversões do Insert Affiliate
  • utm_medium: O ID da sua empresa no Insert Affiliate
  • utm_campaign: O identificador do afiliado (código curto)

Observações importantes:

  • Sempre chame returnInsertAffiliateIdentifier() e returnCompanyId() antes de iniciar a compra
  • Inclua os parâmetros UTM nos metadados apenas se existir um identificador de afiliado
  • Os metadados serão enviados com a compra e estarão disponíveis nos eventos de webhook do RevenueCat

Se você está usando RevenueCat Web Purchase Links para campanhas online (como e-mail marketing, redes sociais ou promoções de afiliados), você deve anexar os parâmetros UTM para garantir o rastreamento correto do afiliado.

Importante: Isso também se aplica se você está usando RevenueCat Paywalls no seu app móvel com um fluxo app-para-web. O recurso nativo de Paywalls do RevenueCat não suporta a passagem de metadados personalizados em plataformas móveis, então você deve usar uma destas abordagens:

  1. Redirecionar para Web Purchase Links - Em vez de usar a interface de Paywall do RevenueCat, direcione os usuários para um Web Purchase Link com os parâmetros UTM anexados (abordagem recomendada)
  2. Construir um Paywall personalizado - Crie sua própria interface de paywall que busca offerings e chama o método de compra com os metadados diretamente

Como funciona

Os RevenueCat Web Purchase Links são páginas de pagamento hospedadas que permitem vender assinaturas sem construir seu próprio fluxo de checkout. Para rastrear a atribuição do afiliado, anexe os parâmetros UTM a esses links.

Parâmetros UTM obrigatórios

  • utm_source: Sempre definido como insertAffiliate
  • utm_medium: O ID da sua empresa no Insert Affiliate
  • utm_campaign: O código curto do afiliado

Exemplo

Se o seu RevenueCat Web Purchase Link for:

https://pay.rev.cat/sandbox/viqxbcoudyfaeaae/

Você deve anexar os parâmetros UTM:

?utm_source=insertAffiliate&utm_medium={insertAffiliateCompanyId}&utm_campaign={affiliateShortCode}

Exemplo completo com parâmetros

https://pay.rev.cat/sandbox/viqxbcoudyfaeaxa/?utm_source=insertAffiliate&utm_medium=12345&utm_campaign=AFF123

Onde:

  • utm_source=insertAffiliate - Identifica isso como uma conversão do Insert Affiliate
  • utm_medium=12345 - O ID exclusivo da sua empresa no Insert Affiliate
  • utm_campaign=AFF123 - O código curto do afiliado

Como obter o ID da sua empresa

Você pode encontrar o ID da sua empresa no Insert Affiliate nas configurações do seu painel.

Como obter o identificador do afiliado

O identificador do afiliado (código curto) pode vir de várias fontes:

  • Deep linking: Quando um usuário clica em um link de afiliado, capture o identificador através da sua plataforma de deep linking
  • Código curto: Os usuários podem inserir ou aplicar manualmente um código curto de afiliado
  • Parâmetros de URL: Detectados automaticamente pelo SDK

Ver a documentação do JS SDK →

Plataformas de deep linking

Embora seja possível usar os RevenueCat Web Purchase Links como o deep link que você fornece aos seus afiliados, não recomendamos isso, pois fazê-lo fará com que APENAS transações baseadas na web sejam rastreadas—não as compras dentro do app.

Essa limitação existe devido à forma como os links de pagamento do RevenueCat lidam com a passagem dos parâmetros utm_source, utm_medium e utm_campaign para o app ao serem resgatados via links de resgate do RevenueCat.

Abordagem recomendada:

Se você quiser usar os RevenueCat Web Purchase Links para os seus afiliados, você deve:

  1. Selecionar "RevenueCat Web Purchase Links" nas configurações do seu Insert Affiliate para rastrear vendas baseadas na web
  2. Implementar códigos curtos como mecanismo de fallback dentro do seu app móvel
  3. Solicitar aos usuários dentro do seu app que identifiquem qual afiliado os recomendou
  4. Aplicar a atribuição do afiliado para futuras compras dentro do app com base na resposta deles

Essa abordagem híbrida garante um rastreamento abrangente tanto para compras web (via parâmetros UTM no Web Purchase Link) quanto para compras dentro do app (via códigos curtos).

Quando usar essa abordagem:

Use os RevenueCat Web Purchase Links como sua plataforma de deep linking apenas se você estiver confortável com a limitação de que os links de resgate não atribuirão automaticamente as compras dentro do app aos afiliados. O fallback de código curto é essencial para manter a atribuição correta nas transações móveis.

Testando sua configuração

Testando a integração do SDK

  1. Conecte sua conta do Stripe via Stripe Connect
  2. Inicialize o SDK do Insert Affiliate na sua página
  3. Inicialize o RevenueCat Web SDK
  4. Faça uma compra de teste com os parâmetros UTM nos metadados
  5. Verifique seu painel de transações para confirmar que a transação aparece
  1. Crie um RevenueCat Web Purchase Link
  2. Anexe os parâmetros UTM necessários (utm_source, utm_medium, utm_campaign)
  3. Clique no link e conclua uma compra de teste
  4. Verifique seu painel de transações para verificar se a transação é atribuída

Solução de problemas

Transações não aparecem

Verifique estes problemas comuns:

  • Status do Stripe Connect: Verifique se sua conta do Stripe aparece como "Active" nas configurações
  • Parâmetros UTM: Confirme que você está passando todos os três parâmetros UTM obrigatórios (utm_source, utm_medium, utm_campaign)
  • Inicialização do SDK: Certifique-se de que o SDK do Insert Affiliate está inicializado corretamente e retornando valores válidos
  • Conexão Stripe do RevenueCat: Verifique se o RevenueCat Web Billing está conectado corretamente à mesma conta do Stripe que você conectou via Stripe Connect
  • Formato dos metadados: Verifique se os parâmetros UTM estão sendo passados corretamente nos metadados da compra

SDK não detecta o afiliado

  • Configuração de deep link: Verifique se sua plataforma de deep linking está configurada corretamente
  • Parâmetros de URL: Verifique se os links de afiliado incluem o parâmetro insertAffiliate correto
  • Momento da inicialização do SDK: Certifique-se de que o SDK é inicializado antes de os usuários iniciarem as compras
  • Janela de atribuição: Verifique se o identificador do afiliado não expirou (use ignoreTimeout: true se necessário)
  • Formato dos parâmetros UTM: Certifique-se de que os parâmetros UTM estão corretamente codificados em URL
  • Ortografia dos parâmetros: Verifique novamente se os nomes dos parâmetros estão escritos corretamente (utm_source, utm_medium, utm_campaign)
  • ID da empresa: Verifique se você está usando o ID correto da empresa no Insert Affiliate
  • Código curto do afiliado: Confirme se o código curto do afiliado é válido e está ativo

O que acontece em seguida

Uma vez configurado:

  1. Compras com metadados UTM criam automaticamente registros de comissão
  2. Visualize todas as transações no seu painel
  3. Configure as taxas de comissão por afiliado
  4. Configure os métodos de pagamento para pagar seus afiliados
  5. O RevenueCat gerencia as assinaturas enquanto o Insert Affiliate rastreia a atribuição