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 [email protected]

Você poderia usar [email protected]

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, [email protected]).

  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 (aba Integrations)
  • 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
Purchase Verification Settings com RevenueCat selecionado, mostrando a URL do webhook e o valor do cabeçalho de autenticação do webhook do RevenueCat a copiar

Clique para ver em tamanho real

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.

Ainda vazio? Verifique se há contas de trabalho no dispositivo de teste

Se o referrer vier vazio em todas as instalações feitas em um telefone específico, verifique se esse telefone tem uma conta Google de trabalho ou escola conectada (por exemplo, uma conta do Google Workspace gerenciada pela sua empresa).

Quando há qualquer conta gerenciada no dispositivo, o Google Play pode descartar o referrer, e a Install Referrer API retorna o valor orgânico padrão em vez do seu código de afiliado. Isso acontece mesmo quando é uma conta pessoal do Gmail que faz a instalação, então trocar a conta ativa na Play Store não resolve.

Para confirmar, remova as contas de trabalho do dispositivo (Configurações → Senhas e contas) ou use um telefone que tenha apenas uma conta pessoal do Gmail. Depois, force o fechamento da Play Store, desinstale o app e clique no link de afiliado novamente.

O Google não documenta esse comportamento, mas desenvolvedores o relatam com frequência. Diferente da sessão obsoleta da Play Store acima, isso também pode afetar usuários reais que têm uma conta de trabalho no telefone pessoal. Para esses usuários, os códigos curtos são a alternativa.

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.