How can we help?

Pesquisa

Configurar a Validação de recibos

  • Atualizado

Resumo: A validação de recibos mensura a receita de compras in-app e assinaturas e a verifica junto às lojas de aplicativos, garantindo resultados precisos de retorno sobre gasto com anúncios (ROAS).

Fazer upgrade para a nova Validação de recibos

A Validação de recibos legada será desativada em 7 de setembro de 2026; consulte o Boletim: a Validação de recibos legada foi descontinuada. Se o seu aplicativo usa a Validação de recibos legada, migre para a nova realizando as etapas de configuração abaixo. Antes de começar, revise as principais diferenças e prepare a migração.

O que há de novo na Validação de recibos

Área Legado Nova validação de recibos
Método do SDK validateAndLogInAppPurchase (legado/v1) validateAndLogInAppPurchase (v2), mesmo nome e nova assinatura no iOS e Android
Entrada de preço e moeda Informado na chamada do SDK Extraído automaticamente da loja
Tipo de compra Não obrigatório Parâmetro PurchaseType obrigatório (assinatura ou compra avulsa)
Configuração das definições de receita Não obrigatório Obrigatório (página Definições de receita)
Fonte do valor de af_revenue Valor informado na chamada do SDK Valor bruto retornado pela loja; qualquer valor personalizado informado na chamada do SDK vai para o objeto custom_data do evento
Granularidade do evento de compra Um único evento af_purchase para todos os tipos de transação Eventos distintos por tipo de transação: af_purchase, af_ars_trial_started, af_ars_subscription_started e variantes de sandbox
Suporte ao StoreKit 2 (iOS) Não suportado Com suporte.
Filtragem de fraude Com limitação Aprimorado no Android e no iOS
Disponibilidade do SDK Removido do SDK da AppsFlyer v7.0.0+ Disponível a partir do Android v6.17.5, iOS v6.17.8 e plugins v6.17.8 em diante
Registro validado de evento de compra Com suporte até 7 de setembro de 2026 Em andamento

Prepare a migração

Antes de iniciar a migração, revise as seguintes considerações:

  • Faça a migração gradualmente sem interromper a experiência dos usuários existentes. Habilitar a nova Validação de recibos no dashboard da AppsFlyer não afeta as versões do aplicativo que ainda usam o método legado. Ambos continuam funcionando até a descontinuação do legado em 7 de setembro de 2026.
  • Espere mudanças na receita após a migração. A nova Validação de recibos usa o valor bruto retornado pela loja, enquanto a Validação de recibos legada usava o valor de receita informado na chamada do SDK. Se a chamada do SDK informou um valor não bruto, os dashboards e os postbacks de parceiros, que agora refletem valores brutos, mostrarão um número diferente após a migração. Para receita líquida, use ROI360 Store Revenue. Consulte Configurar a receita da loja do ROI360.
  • Informe seus parceiros de UA sobre a mudança na receita. As ad networks que costumavam receber receita não bruta do postback af_purchase verão valores diferentes após a migração.
  • Planeje o cronograma de lançamento do seu aplicativo. Após setembro 7, 2026, os usuários em versões do aplicativo criadas com versões do SDK anteriores ao Android v6.17.5 ou iOS v6.17.8 deixarão de gerar eventos af_purchase validados. Lance a nova versão do seu aplicativo com antecedência suficiente para alcançar a maior parte da sua base de usuários antes do encerramento.

Mudar para o ROI360 Store Revenue

Mudar para o ROI360 Store Revenue não exige alteração no SDK, já que ambos os produtos usam o mesmo método validateAndLogInAppPurchase (v2). Adicionar o Purchase Connector para detecção automática de compras é opcional.

Para mais informações e instruções de configuração, consulte Configurar a receita da loja no ROI360.

Escritórios

 Nota

Para mais informações sobre a Validação de recibos, incluindo como ela funciona e como habilitá-la na AppsFlyer, consulte Sobre a Validação de recibos.

Para configurar a Validação de recibos, conclua as etapas a seguir na ordem:

  1. Configurar credenciais da loja (iOS e Android)
    • iOS: Configure as chaves do App Store Connect (chave In-App Purchase, Key ID e Issuer ID) na AppsFlyer para habilitar a Validação de recibos.
    • Android: Configure uma conta de serviço do Google Cloud, defina as permissões necessárias no Google Play Console e faça upload da chave JSON da conta de serviço para a AppsFlyer.
  2. Implementar a API do SDK validateAndLog: Prepare os desenvolvedores para integrar a API do SDK validateAndLog da AppsFlyer e configurar o ambiente sandbox para testes.
  3. Testar a implementação da API do SDK validateAndLog: Faça compras e assinaturas de teste no sandbox no iOS e no Android para verificar se os eventos de Validação de recibos são gerados e registrados corretamente pela AppsFlyer.
  4. Verificar e atualizar configurações: Confirme se o tipo de produto está definido como Validação de recibos e revise os status da chave da loja e da integração do SDK para garantir a mensuração precisa e contínua da receita.
  5. Lançar as versões do aplicativo com a API do SDK validateAndLog: Lance versões atualizadas do aplicativo com a API do SDK validateAndLog integrada, garantindo que os sinalizadores de sandbox estejam desativados e que os eventos in-app obrigatórios não sejam bloqueados pelas regras de validação.

Etapa 1 (iOS): configurar as chaves do App Store Connect

Na etapa 1, obtenha as seguintes credenciais no App Store Connect e insira-as na página de Revenue Settings da plataforma AppsFlyer.

  • In-App Purchase key
  • ID da chave
  • Issuer ID

Antes de começar:

  • Para configurar as credenciais, você deve realizar ações tanto no App Store Connect quanto na AppsFlyer. Durante a configuração, mantenha as abas da App Store Connect e da AppsFlyer abertas.
  • Seu aplicativo iOS requer StoreKit v1 ou v2, que fornece a estrutura necessária para gerenciar compras in-app e assinaturas.

1.1 Crie as App Store Connect Keys

Para definir as credenciais do iOS, siga estas etapas:

  1. No App Store Connect, vá para Users and Access.

  2. Vá para Users and Access > Integrations e, na lista Keys , selecione In-App Purchase.

  3. Clique em + para gerar uma nova chave de In-App Purchase.

  4. Digite um nome para sua chave de API.
  5. Clique em Gerar.
  6. Clique em Download In-App Purchase Key ao lado da chave que você acabou de gerar para fazer o download. Atenção: você só pode baixar a chave uma vez.

  7. Copie o Key ID da chave que você acabou de gerar e cole-o na configuração de compras & assinaturas da AppsFlyer, em Key ID.

  8. Copie o Issuer ID. Observação: se o Issuer ID não aparecer na parte superior da página, crie uma chave de API do App Store Connect (com qualquer nível de acesso). Depois disso, o Issuer ID aparece na parte superior da página da chave de In-App Purchase.

1.2 Definir a chave do App Store Connect

  1. Ative a Validação de recibos. #habilitar-validação-de-recibo
  2. Na etapa App Store Connect keys , clique em  Upload no campo In-App Purchase key para fazer upload do arquivo p8.

  3. Na seção intitulada App Store Connect keys, cole os valores que você copiou do App Store Connect.

    • ID da chave
    • Issuer ID
  4. Clique Validate keys para garantir que as chaves inseridas estejam corretas. Observação: a ação Validate keys pode não funcionar se seu aplicativo ainda não tiver sido publicado na App Store.
  5. Clique Save and Next.

Passo 1 (Android). Configure a service account key e permissões

Na etapa 1, obtenha as seguintes credenciais de Google Play e Google Cloud e insira-as na página Revenue Settings na plataforma AppsFlyer.

Antes de começar:

  • A configuração da mensuração de receita de compras in-app e assinaturas envolve etapas realizadas na Google Cloud Platform, Google Play Console e na interface da AppsFlyer. Recomendamos manter as três abas abertas durante a configuração.
  • A configuração na IU da AppsFlyer requer permissões de administrador.

1.1 Vincule sua conta de desenvolvedor do Google Play ao seu projeto do Google Cloud

Pré-requisitos: acesso ao Google Play Console e a um projeto do Google Cloud.

Para vincular sua conta de desenvolvedor do Google Play ao seu projeto do Google Cloud, siga estas etapas:

  1. No Google Play Console, acesse sua conta de desenvolvedor do Google Play.
  2. Vincule a conta ao seu projeto Google Cloud. Para obter instruções, consulte este artigo de ajuda do Google.

  3. Ative a Google Play Developer API. Para obter instruções, consulte este artigo de ajuda do Google.

1.2 Configure sua conta de serviço na plataforma Google Cloud

Pré-requisitos: acesso à plataforma Google Cloud.

Para configurar sua service account, siga estas etapas:

  1. Crie ou localize a service account:

    1. Acesse a seção Service Accounts na plataforma Google Cloud e clique CREATE SERVICE ACCOUNT.
    2. Insira os detalhes da service account.
    3. Copie o endereço de e-mail.
    4. Clique Create and continue.
    5. Na etapa Grant this service account access to the project , selecione a função de assinante do Pub/Sub .

    6. Clique Continue > Done.

  2. Faça o download da service account private key:

    1. Na plataforma Google Cloud, acesse a seção Service accounts , localize na lista a conta desejada (a que você acabou de criar) e clique no ícone More actions .
    2. Clique Manage keys.

    3. Clique em Add key > Create new key.

    4. No pop-up Create private key popup, under Key type, selecione JSON, e clique Create.

    5. Clique Create. O arquivo JSON de chave privada é baixado.

    6. Salve o arquivo de chave JSON, que você fará o upload para a AppsFlyer mais tarde. Nota! Você deve salvar a chave. ela não poderá ser recuperada depois. Se você não salvá-la, terá que criar uma chave totalmente nova.

1.3 Defina permissões de acesso à API no Google Play Console

Pré-requisitos: acesso ao Google Play Console.

Observação: pode levar algum tempo (às vezes até 24 horas) após a configuração das credenciais e permissões da conta de serviço para poder usá-las. Isso pode fazer com que você receba mensagens de erro em etapas posteriores.

Para definir permissões de acesso à API no Google Play Console:

  1. No Google Play Console, vá para Users and permissions, encontre a conta de serviço que você criou, e clique Invite new users.

  2. Digite o endereço de e-mail que você copiou ao configurar sua conta de serviço na etapa 1.2.1.3.

  3. Na seção Permissions , vá para a aba Account permissions , e selecione ambas:

    • Visualizar dados financeiros, pedidos e respostas à pesquisa de cancelamento.
    • Gerenciar pedidos e assinaturas

  4. Na aba App permissions , clique Add app, then select your app. Adicione vários aplicativos, se necessário.

  5. Clique Invite user.

  6. No popup de confirmação, clique Send invite.

1.4 Envie a chave privada da conta de serviço para a AppsFlyer

Faça o upload e valide a chave JSON do Google que você baixou em step 1.2.

Pré-requisitos: acesso de administrador à AppsFlyer.

Para fazer o upload da chave privada da conta de serviço para a AppsFlyer, siga estas etapas:

  1. Ative a validação de recibos.
  2. Na etapa Service Account Key and Permissions , no campo Upload Google JSON key , clique em  Upload.
  3. Faça o upload do arquivo JSON que você baixou em step 1.2.

  4. Clique Validar chave. Atenção:

    • após definir as credenciais e permissões da conta de serviço, pode levar até 24 horas para que você possa usá-las. Isso pode fazer com que você receba mensagens de erro ao tentar validar a chave ou realizar um teste de validação.
    • Para contornar o tempo de espera de 24 horas, no Google Play Console, navegue até qualquer aplicativo, depois vá para Monetize > Products > Subscriptions/In-app products, e faça uma alteração. Por exemplo, edite a descrição do seu produto e salve-a. Isso geralmente atualiza imediatamente as credenciais e permissões da conta. Feito isso, você pode desfazer as alterações.
  5. Clique Next. A etapa implementação do SDK é aberta.

3. Implementar o SDK

Nesta etapa, você prepara seus desenvolvedores para integrar a API validateAndLog do SDK e configurar um ambiente sandbox para testes. As versões mínimas do SDK que oferecem suporte à API validateAndLog mais recente são 6.17.5 para Android e 6.17.8 para iOS.

Para implementar a API validateAndLog do SDK, siga estas etapas:

  1. Na etapa implementação do SDK, copie a mensagem pré-escrita exibida no dashboard.

  2. Envie-a para seus desenvolvedores. ela inclui:

    • o nome e o ID do aplicativo
    • Um link para o guia de integração do SDK.
    • Instruções para configurar o ambiente sandbox (sandbox = true).
    • Etapas de teste (usando TestFlight).

    Essa mensagem fornece todas as informações que os seus desenvolvedores precisam para concluir a integração e começar os testes.

  3. Clique Next. A etapa Verify SDK implementation é aberta.

3. Verifique a implementação do SDK

Teste a integração de receita de compras in-app e assinaturas em um ambiente sandbox para confirmar que o conector do SDK está integrado corretamente e que as notificações do servidor estão configuradas corretamente e são recebidas pela AppsFlyer.

Testar a implementação do SDK

Para verificar se a AppsFlyer recebeu payloads validateAndLog válidos do seu aplicativo nos últimos 7 dias, execute estas etapas:

  1. Na etapa Verify SDK implementation, clique em Test SDK implementation.
  2. Revise os resultados, incluindo o carimbo de data/hora do payload mais recente recebido pela AppsFlyer. Observe que essa verificação confirma apenas que as solicitações estão chegando à AppsFlyer e não verifica a integridade nem a exatidão dos dados.
  3. Para validar totalmente a implementação, continue com as etapas de teste abaixo.

Considerações sobre o ambiente Sandbox

No ambiente sandbox:

  • Apenas eventos de compra inicial fazem com que a API validateAndLog do SDK produza um evento que é registrado pela AppsFlyer. Um evento de compra in-app é chamado de af_purchase_sandbox_sdk. Um evento de assinatura é chamado de af_ars_sandbox_sdk.
  • Eventos de sandbox têm uma receita de 0.
  • Para Android, os testes realizados por testadores de licença resultam em eventos sandbox mesmo que o ambiente sandbox no SDK não esteja configurado.

Teste a receita de compras in-app e assinaturas

Para testar a receita de compras in-app e assinaturas:

  1. Diga aos seus desenvolvedores para seguirem as instruções deles para configurar o ambiente de sandbox para a API do SDK validateAndLog.
  2. Faça uma compra de teste ou uma assinatura com o License Tester no Google Play e o TestFlight no iOS. 

  3. Verifique se os eventos de teste são exibidos de uma das seguintes formas:

  4. Procure os seguintes eventos de teste:

    • O af_purchase_sandbox_sdk para um evento de compra.
    • O af_ars_sandbox_sdk para um evento de assinatura.

  5. Certifique-se de que os eventos de teste incluam o seguinte:

    • Uma receita com valor 0 (para não distorcer os relatórios reais da AppsFlyer).
    • Um af_sandbox_revenue parâmetro que inclui o valor da receita do produto comprado, garantindo que a receita correta seja reportada.
    • Um parâmetro af_validated é true. Se af_validated for false, volte para a etapa 2 acima e valide a chave fornecida pela loja
    • Um parâmetro af_validation_type é receipt_validation.

4. Verifique e atualize as configurações

Depois de concluir a configuração das definições acima e salvar as etapas acima, você será redirecionado para a visualização de configuração ativa, na qual poderá verificar ou atualizar as seguintes configurações:

  1. Verifique se o Tipo de produto é Validação de recibos
  2. Verifique se Verify purchases with the App Store está ativado.

  3. Verifique ou atualize as seguintes configurações:

    • A configuração da chave da App Store 
    • A configuração da integração do SDK setup

5. Lance as versões do aplicativo com a API do SDK validateAndLog

Com tudo das etapas anteriores configurado e a API do SDK validateAndLog da AppsFlyer integrada ao seu aplicativo, diga aos seus desenvolvedores para lançarem a versão do aplicativo com a API do SDK validateAndLog integrada.

Antes de os desenvolvedores publicarem a nova versão do aplicativo, certifique-se de que:

  • Os eventos in-app que você quer capturar como compra in-app ou assinatura não sejam bloqueados por nenhuma das regras de validação que você configurou na AppsFlyer.
  • Seus desenvolvedores têm todas as flags de sandbox definidas como false.

Depois que o aplicativo com a API do SDK validateAndLog for lançado, os eventos de compra in-app e de assinatura serão gerados e disponibilizados em todos os dashboards da AppsFlyer, bem como em relatórios de dados agregados e relatórios de dados brutos.

Os eventos só são gerados para usuários que atualizaram para uma versão do aplicativo que inclui a API SDK validateAndLog. Como resultado, é esperada uma discrepância entre os dados de receita do aplicativo e os dados da loja até que a versão atualizada do aplicativo seja totalmente adotada.

This article was translated using AI and may contain errors. For the most accurate information, please refer to the English version using the language selector.

Share article: