RevenueCat Web Billing

Rastreie comissões em compras web usando o RevenueCat Web Billing, gerenciando a cobrança diretamente pela plataforma web do RevenueCat.

Ao ativar o rastreamento do RevenueCat Web Billing, você pode atribuir compras web a afiliados passando parâmetros UTM, seja como metadados de compra através do Web SDK, seja como parâmetros de consulta em um Web Purchase Link hospedado.

O que você pode rastrear

Uma vez configurado, o Insert Affiliate rastreia automaticamente:

  • Compras iniciais de assinatura
  • Renovações de assinatura
  • Compras únicas, incluindo produtos vitalícios e outros produtos não renováveis (um NON_RENEWING_PURCHASE no RevenueCat, um pagamento avulso no Stripe)
  • Reembolsos, que revertem automaticamente a comissão do afiliado
  • Compras feitas através do Web SDK e através dos Web Purchase Links hospedados

Compras únicas e vitalícias

Compras únicas são rastreadas, exibidas e pagas exatamente como as compras de assinatura.

A atribuição do Web Billing chega ao Insert Affiliate através do Stripe Connect, e não pelo webhook do RevenueCat, então o que lemos é o pagamento subjacente no Stripe. Um pagamento avulso é registrado como uma compra inicial, e suas configurações de comissão, os totais do seu painel e seus pagamentos tratam essa compra da mesma forma que tratam uma assinatura. Um reembolso desse pagamento reverte a comissão da mesma maneira.

Pré-requisitos

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

  • RevenueCat Web Billing configurado com o Stripe
  • Stripe Connect configurado no seu painel do Insert Affiliate, usando a mesma conta do Stripe à qual o RevenueCat está conectado

Se você vai construir seu próprio checkout com o Web SDK, também precisa de:

  • RevenueCat Web SDK instalado e configurado
  • Insert Affiliate SDK inicializado na sua página

Se, em vez disso, você vai enviar os clientes para um Web Purchase Link hospedado, nenhum dos dois SDKs é necessário. Basta anexar os parâmetros UTM ao link.

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 na aba Payments & Payouts
  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 e produtos únicos sem construir seu próprio fluxo de checkout. Para rastrear a atribuição do afiliado, anexe os parâmetros UTM a esses links.

Essa abordagem não exige nenhum SDK, nem na web nem no seu app. Seja um site, um aplicativo de desktop ou um e-mail que monte o link, anexar os três parâmetros já é suficiente para a atribuição. Isso a torna a opção mais simples para plataformas que nossos SDKs não cobrem, como um aplicativo macOS ou desktop.

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

    Configurações da empresa com o menu Deep Linking Platform definido como RevenueCat Web Purchase Links

    Clique para ver em tamanho real

  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 (aba Payments & Payouts)
  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

Se você vende um produto único ou vitalício, faça esse teste especificamente com esse produto. Ele é atribuído através do mesmo pagamento no Stripe e aparece no painel como uma compra inicial.

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 (aba Payments & Payouts)
  • 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 a cobrança enquanto o Insert Affiliate rastreia a atribuição