Solução de problemas

Testando transações de sandbox antes de entrar em produção

Você pode testar completamente o Insert Affiliate usando os seguintes ambientes:

  • Builds locais
  • TestFlight
  • Faixas de teste interno ou fechado do Google Play

A atribuição e as compras funcionam em todos esses ambientes e aparecerão no seu painel do Insert Affiliate.

Se você usa o RevenueCat, as transações de sandbox são claramente rotuladas como tal.

Criando um afiliado de teste

Você pode criar facilmente contas de afiliados de teste usando aliases de e-mail.

Exemplo: se o seu e-mail fosse michael@insertaffiliate.com

Você poderia usar michael+testaffiliate@insertaffiliate.com

Guia de depuração

Log detalhado (verbose)

O log detalhado é uma configuração opcional nos nossos SDKs que gera informações de diagnóstico adicionais.

Ative isso ao investigar problemas com a sua integração.

Minhas transações de afiliados não estão aparecendo

Siga estas etapas de depuração em ordem. Só avance depois de confirmar que a etapa anterior funciona.

Isso ajuda a verificar se o problema está no Insert Affiliate ou no seu provedor de deep linking.

  1. Configure um método no seu app para inserir manualmente um código curto antes do checkout.

  2. Execute o app localmente, via TestFlight ou via teste interno/fechado do Google Play.

  3. Insira o código curto do seu afiliado de teste (por exemplo, michael+testaffiliate@insertaffiliate.com).

  4. Verifique nos seus logs a confirmação de que o código curto foi recebido.

  5. Faça uma compra e verifique se ela aparece no seu painel do Insert Affiliate.

Se a atribuição por código curto funcionar, mas o deep linking não → o problema está na sua integração de deep linking.

Verificando sua integração de deep linking

Use logs detalhados para confirmar cada etapa.

  1. Registre no log o link que o app recebe na inicialização.

    • Certifique-se de que ele corresponde ao que você espera.
    • Caso contrário, consulte a documentação do seu provedor de deep link.

  2. Depois de passar o link para o nosso SDK, registre no log o código curto do afiliado armazenado.

    • Ele deve corresponder ao código curto visível no seu painel.

Se tudo isso funcionar, o seu deep linking está correto.

Nesse caso, o seu problema está em passar o identificador do afiliado para a sua plataforma de verificação de compra/recibo (por exemplo, RevenueCat).

Minha integração funciona, mas apenas se o app já estiver instalado

Se a atribuição só funciona em instalações novas, o problema é quase sempre um dos seguintes:

1. O deep linking não está configurado corretamente

Registre no log o link que o app recebe após instalar pela app store a partir de um link clicado.

Se isso for registrado corretamente, prossiga para a etapa 2.

2. Você não está usando o callback "Short Code Set"

Nossos SDKs fornecem um callback que dispara assim que um código curto é armazenado.

Você deve usá-lo para encaminhar o identificador do afiliado para a sua plataforma de verificação de recibos (por exemplo, RevenueCat).

Meu deep linking funciona, mas as transações ainda não são rastreadas

Se você consegue ver o link, consegue recuperar o código curto correto e a atribuição parece correta - mas nenhuma transação aparece - verifique:

1. Tempo limite de atribuição

Se você configurou um tempo limite de atribuição, ele pode ter expirado.

Remova-o durante os testes e valide novamente.

2. Impedir transferência de afiliado

Se você ativou Impedir transferência de afiliado, novos links de afiliado não substituirão a atribuição existente.

Limpe o armazenamento do app ou reinstale para redefinir a atribuição durante os testes.

3. O código curto do afiliado não é passado para o seu sistema de verificação de recibos

Dependendo da sua configuração (RevenueCat, Iaptic, StoreKit direto / Play Billing), você deve passar o código curto durante a compra ou a validação do recibo.

Revise o ReadMe e a documentação do SDK no GitHub para a plataforma de compra escolhida.

Se você está usando o RevenueCat para validação de recibos, as etapas a seguir são obrigatórias. Pular qualquer uma delas impedirá que o Insert Affiliate receba os eventos de compra, mesmo que o deep linking e a atribuição por código curto estejam funcionando corretamente.

1. Webhook do RevenueCat para o Insert Affiliate (obrigatório para todos os SDKs)

Você deve configurar o RevenueCat para enviar eventos de compra ao Insert Affiliate via webhook.

2. Configuração do webhook

Acesse o RevenueCat e crie um novo webhook:

  • Configure o webhook com estas configurações:
    • Webhook URL: https://api.insertaffiliate.com/v1/api/revenuecat-webhook
    • Authorization header: Use o valor do seu painel do Insert Affiliate (você obterá isso na etapa 4)
    • Defina "Event Type" como "All events"

3. Nas configurações do seu painel do Insert Affiliate:

  • Navegue até as configurações de verificação
  • Defina o método de verificação de compra no app como RevenueCat

De volta ao seu painel do Insert Affiliate:

4. Localize o valor do cabeçalho de autenticação do webhook do RevenueCat

  • Copie esse valor
  • Cole-o como o valor do Authorization header na configuração do seu webhook do RevenueCat

Notificações de servidor da App Store / Play Store

O RevenueCat requer notificações servidor-a-servidor da App Store ou da Play Store para poder retransmitir as atualizações de assinatura e compra.

Certifique-se de ter configurado:

  • Apple App Store Server Notifications
  • Google Play Real-Time Developer Notifications (RTDN)

Ver a documentação de Server Notifications do RevenueCat →

Sem isso, o RevenueCat não receberá os dados de compra completos ou em tempo hábil — o que significa que o Insert Affiliate também não receberá.

5. Confirme o atributo do Insert Affiliate dentro do RevenueCat

  1. Abra uma compra dentro do seu painel do RevenueCat.

  2. Na página de detalhes da transação, procure o painel Attributes no lado direito.

  3. Você deve ver: insert_affiliate: <affiliate_short_code>

Se esse atributo estiver presente e correto → o RevenueCat está recebendo o código do afiliado com sucesso.

Se estiver ausente → o código curto não está sendo passado para o RevenueCat.

  • Isso significa que o problema está antes do RevenueCat (deep link → app → SDK → etapa de atributo).

Essa única verificação determina imediatamente se a falha está em:

  • Deep linking
  • Sua integração do SDK do Insert Affiliate
  • Ou na sua configuração do RevenueCat

6. Se o atributo existe, mas você ainda não vê as vendas no Insert Affiliate

Se insert_affiliate estiver visível dentro do RevenueCat, mas a venda não aparecer no seu painel do Insert Affiliate, então o problema é um dos seguintes:

a) Webhook não disparando ou mal configurado

Verifique novamente a URL do webhook e certifique-se de que:

  • Ele esteja ativo
  • Não tenha sido alterado
  • Nenhum cabeçalho de autenticação esteja faltando

7. Se o atributo estiver ausente

Se você não vê o atributo insert_affiliate:

  • O deep linking pode não estar passando o link correto para o seu app
  • O callback do código curto pode não estar sendo tratado
  • Você pode não estar definindo o setAttributes do RevenueCat no momento certo
  • O usuário pode não estar atribuído antes da compra ocorrer
  • O atributo pode estar sendo sobrescrito em outro lugar do seu código

Prossiga com:

  • Depuração de deep linking
  • Teste de código curto
  • Verificação dos callbacks do SDK
  • Verificação dos logs em tempo de execução para confirmar quando o atributo é definido

Se você está usando o Adapty para validação de recibos, as etapas a seguir são obrigatórias. Pular qualquer uma delas impedirá que o Insert Affiliate receba os eventos de compra, mesmo que o deep linking e a atribuição por código curto estejam funcionando corretamente.

1. Webhook do Adapty para o Insert Affiliate (obrigatório para todos os SDKs)

Você deve configurar o Adapty para enviar eventos de compra ao Insert Affiliate via webhook.

2. Configuração do webhook

  1. No seu painel do Insert Affiliate:

    • Defina In-App Purchase Verification como Adapty
    • Copie a Adapty Webhook URL
    • Copie o valor do Adapty Webhook Authorization Header

  2. No painel do Adapty:

    • Navegue até Integrations → Webhooks
    • Defina a Production URL como a URL do webhook do Insert Affiliate
    • Defina a Sandbox URL como a mesma URL do webhook
    • Cole o valor do cabeçalho de autorização em Authorization header value
    • Ative estas opções:
      • Exclude historical events
      • Send attribution
      • Send trial price
      • Send user attributes
    • Salve a configuração

3. Confirme o atributo do Insert Affiliate dentro do Adapty

  1. Acesse app.adapty.io/profiles/users

  2. Encontre e selecione o usuário que fez a compra de teste

  3. Procure a seção Custom attributes

  4. Você deve ver: insert_affiliate com o formato {SHORT_CODE}-{UUID}

    • Exemplo: SAVE20-a1b2c3d4-e5f6-7890-abcd-ef1234567890

Se esse atributo estiver presente e correto → o Adapty está recebendo o código do afiliado com sucesso.

Se estiver ausente → o código curto não está sendo passado para o Adapty.

  • Isso significa que o problema está antes do Adapty (deep link → app → SDK → etapa updateProfile).

Essa única verificação determina imediatamente se a falha está em:

  • Deep linking
  • Sua integração do SDK do Insert Affiliate
  • Ou na sua configuração do Adapty

4. Se o atributo existe, mas você ainda não vê as vendas no Insert Affiliate

Se insert_affiliate estiver visível dentro do Adapty, mas a venda não aparecer no seu painel do Insert Affiliate, então o problema é um dos seguintes:

a) Webhook não disparando ou mal configurado

Verifique novamente a configuração do webhook e certifique-se de que:

  • Tanto a Production URL quanto a Sandbox URL estejam definidas corretamente
  • O valor do cabeçalho de autorização esteja correto
  • Send user attributes esteja ativado
  • O webhook esteja salvo e ativo

b) Opções de webhook ausentes

Certifique-se de que todas as opções necessárias estejam ativadas:

  • Exclude historical events
  • Send attribution
  • Send trial price
  • Send user attributes

5. Se o atributo estiver ausente

Se você não vê o atributo insert_affiliate:

  • O deep linking pode não estar passando o link correto para o seu app
  • O callback do código curto pode não estar sendo tratado
  • Você pode não estar chamando Adapty.updateProfile com o identificador do afiliado
  • O usuário pode não estar atribuído antes da compra ocorrer
  • O atributo pode estar sendo sobrescrito em outro lugar do seu código

Prossiga com:

  • Depuração de deep linking
  • Teste de código curto
  • Verificação dos callbacks do SDK
  • Verificação dos logs em tempo de execução para confirmar quando updateProfile é chamado

Android: Install Referrer não funciona durante os testes

Se você está testando o fluxo "app não instalado" no Android (deep linking diferido via Google Play Install Referrer) e a atribuição não está sendo aplicada após a instalação, a causa mais comum é uma sessão obsoleta da Google Play Store.

O problema

Quando a Google Play Store já está aberta na página de listagem do seu app e você navega para a mesma página novamente por meio de um link de afiliado, o Google Play ignora o parâmetro referrer na URL. Isso significa que a Install Referrer API retorna dados vazios e a atribuição é perdida.

Isso acontece com frequência durante os testes porque você está repetidamente instalando e desinstalando o mesmo app, mantendo a Play Store aberta nessa página entre as tentativas.

A solução

Antes de cada teste do fluxo de app não instalado:

  1. Force o fechamento da Google Play Store — vá em Configurações → Apps → Google Play Store → Forçar parada, ou execute adb shell am force-stop com.android.vending
  2. Desinstale o app
  3. Em seguida, clique no link de afiliado e instale

Isso garante que a Play Store processe a URL do referrer como uma navegação nova, que é como os usuários reais a experimentarão — eles não terão a Play Store já aberta na página do seu app.

Importante

Esse é apenas um problema de teste. Usuários reais que clicam em um link de afiliado pela primeira vez não terão a Play Store aberta na página do seu app, então o referrer será capturado corretamente.

Com Insert Links, sim, você pode.

Com outros provedores, você precisa verificar a documentação deles.

  1. Toque no link de afiliado com o app desinstalado.

  2. Quando for levado à página da app store, não instale o app.

  3. Em vez disso, instale o app localmente.

  4. Se a sua configuração de Insert Links estiver correta, a atribuição se comportará exatamente como se você tivesse instalado pela app store.