A partir de agosto de 2026, novas integrações devem procurar vp_token dentro de data, junto ao campo protocol, e não presumir que ele está na raiz da resposta; nesta semana, compare o JSON real com o exemplo Android e ajuste o parser antes de investigar ausência de credencial. Essa orientação se aplica à integração com Credential Manager; integrações existentes em migração devem seguir a instrução oficial para tratar as estruturas pertinentes. A leitura no cliente não substitui a validação criptográfica no servidor. A documentação Android descreve a estrutura atual e as orientações de implementação.
Este guia é para quem integra a verificação de e-mail em um aplicativo Android e encontrou uma resposta que o código não consegue interpretar.
Também serve a responsáveis técnicos que avaliam a migração e a QA que precisa comprovar os caminhos de sucesso, recusa e código por e-mail.
Última atualização: 28 de outubro de 2026. Dados conferidos na documentação de implementação da Android Digital Credentials API e na visão geral oficial da verificação de e-mail.
O campo ausente pode ser um problema de caminho, não de credencial
Quando uma integração retorna uma resposta, mas o código relata que vp_token não existe, há pelo menos duas hipóteses diferentes: o aparelho não forneceu uma credencial utilizável ou o parser está consultando um caminho que já não corresponde à estrutura recebida. Tratar as duas como o mesmo erro leva a correções ruins: por exemplo, direcionar toda pessoa usuária ao código por e-mail quando o defeito está apenas na leitura do JSON.
A alteração confirmada pela documentação Android é estrutural: a resposta passou a incluir protocol e data, e o vp_token fica dentro de data. Portanto, um parser que procura apenas response.vp_token pode não encontrar o campo, mesmo quando a resposta contém dados relevantes. Para integrações iniciadas a partir de agosto de 2026, a orientação é adotar o formato novo. Para integrações existentes durante a migração, consulte a documentação atual sobre compatibilidade e transição; não infira prazo, versão mínima ou comportamento de retirada por conta própria.
O primeiro diagnóstico deve usar a resposta efetivamente recebida, não apenas a mensagem genérica do aplicativo. Compare sua forma com o exemplo oficial, verificando a presença de protocol, a estrutura de data e o local de vp_token. Não transforme uma ausência em um caminho esperado em evidência de que a credencial não foi disponibilizada.
O teste do formato de resposta separa análise de validação
No teste do formato de resposta da verificação de e-mail da Android Digital Credentials API, o objetivo inicial é provar que o cliente reconhece a estrutura, não que a credencial seja autêntica. São etapas distintas: a análise transforma uma resposta em campos que o aplicativo consegue tratar; a validação verifica se esses dados podem ser aceitos para a operação solicitada.
Leia a resposta de forma controlada. Confirme qual campo identifica o protocolo, siga a estrutura de data conforme o formato retornado e localize vp_token no ponto indicado pela documentação. Evite conversões ou decodificações extras sem respaldo no formato oficial: uma transformação aplicada duas vezes, por exemplo, pode alterar o conteúdo e esconder o erro original. A implementação deve respeitar a representação real observada no retorno do Credential Manager.
Depois de localizar os dados, o cliente ainda não deve decidir que a conta está autenticada. A aplicação pode encaminhar a resposta necessária ao servidor para verificação; o servidor, por sua vez, deve aplicar as verificações criptográficas e de confiança previstas para a credencial e para o protocolo. A especificação OpenID for Verifiable Presentations é referência para o fluxo OpenID4VP, enquanto o modelo de dados de credenciais verificáveis do W3C descreve conceitos e estrutura das credenciais. Nenhum desses documentos autoriza tratar a simples extração de um endereço de e-mail como validação concluída.
Na prática, classifique o resultado em camadas: “resposta recebida”, “estrutura reconhecida”, “dados encaminhados” e “validação de servidor aprovada ou recusada”. Essa separação facilita descobrir se o defeito está no parser do cliente, no transporte para o servidor ou na verificação. Também impede que uma tela de sucesso apareça antes de a aplicação ter uma decisão confiável.
A implementação deve acompanhar o estado da integração
Uma integração nova e uma integração já implantada não têm necessariamente o mesmo trabalho de correção. Para uma implementação nova, use o formato documentado atualmente, teste a leitura de protocol e data e evite criar dependência de uma estrutura antiga por conveniência. Para um sistema em migração, defina conscientemente como o cliente reconhece as respostas necessárias durante a transição, seguindo a orientação oficial vigente.
Não implemente uma tentativa silenciosa de “adivinhar” a estrutura. Se o parser testar caminhos diferentes sem registrar qual formato foi encontrado, uma alteração futura pode ser confundida com sucesso, embora o aplicativo esteja interpretando a resposta de modo incompleto. Uma abordagem mais segura é identificar o formato de entrada, aplicar o parser correspondente e produzir um resultado explícito para estruturas desconhecidas. Isso ajuda a falhar de forma controlada, sem converter uma resposta inesperada em aprovação.
Para revisar a implementação, siga este fluxo:
- Capture uma resposta de teste do próprio aplicativo ou de um ambiente autorizado e remova os valores sensíveis antes de compartilhar o registro.
- Compare a forma do objeto com o exemplo oficial; não conclua que falta uma credencial apenas porque o caminho antigo não encontrou
vp_token. - Confira se o parser identifica
protocole percorredataaté o campo previsto para o formato recebido. - Teste uma resposta com campo esperado ausente, uma resposta com estrutura diferente da prevista e uma resposta que não corresponda a nenhum formato reconhecido.
- Confirme que cada caso termina em um estado explícito: análise reconhecida, resposta incompleta ou resposta inesperada. Não atribua aprovação criptográfica ao sucesso do parser.
- No servidor, verifique a assinatura, a confiança no emissor, a vinculação com o titular e o nonce original, de acordo com o protocolo e com a implementação oficial.
- Exercite os caminhos de credencial indisponível, resposta recusada e falha na validação, verificando se o aplicativo oferece uma alternativa apropriada sem mascarar a causa.
- Repita os testes de ponta a ponta em ambiente isolado e registre, de forma redigida, o formato recebido e o resultado do servidor.
A orientação de segurança Android reforça que a adoção de credenciais digitais exige tratar confiança e validação como parte do fluxo, não como detalhe cosmético do cliente. Consulte as recomendações oficiais de confiança e segurança ao definir o que pode resultar em criação de conta ou login.
Perguntas frequentes sobre o diagnóstico
Onde fica o vp_token na resposta nova?
Procure primeiro protocol; em seguida, examine data e localize nele o vp_token. Não use a existência de um campo na raiz como pressuposto para todas as respostas. Compare a estrutura observada com o exemplo Android da integração e com a representação efetivamente fornecida pela biblioteca. Se os nomes de campos estiverem presentes, mas a leitura falhar, verifique também se o parser espera tipos ou níveis de aninhamento diferentes.
Por que o código antigo não encontra o vp_token?
O caso mais comum a investigar é um parser que consulta o campo na raiz, enquanto o formato novo o coloca dentro de data. Nesse cenário, o caminho consultado retorna campo ausente, mas isso não demonstra que não exista credencial utilizável. Inspecione a forma redigida da resposta, identifique se o código atende uma integração nova ou em migração e ajuste a leitura com base na documentação atual, em vez de adicionar um fallback especulativo.
Qual estrutura uma integração nova ou em migração deve aceitar?
Para novas integrações iniciadas a partir de agosto de 2026, a orientação Android é usar o formato novo, com protocol e data. Em uma migração de integração existente, trate os formatos indicados pela documentação para a transição; não presuma que o formato antigo continuará aceito indefinidamente. Confirme a nota oficial mais recente antes de remover compatibilidade, pois o andamento da migração pode mudar e não deve ser deduzido de exemplos isolados.
O que ainda precisa ser validado no servidor?
O servidor precisa validar a credencial e não apenas aceitar o e-mail que o cliente conseguiu ler. Conforme o protocolo adotado, isso inclui verificar assinatura e confiança no emissor, confirmar a vinculação com o titular e conferir o nonce original. Só depois da decisão do servidor a aplicação deve tratar a operação como aprovada. Uma análise bem-sucedida no dispositivo é evidência de que o parser encontrou dados, não de que esses dados são autênticos.
A alternativa por e-mail deve ser testada como fluxo separado
A credencial pode estar indisponível, a resposta pode ser inesperada ou a validação do servidor pode recusar o material recebido. Em cada situação, a aplicação deve apresentar uma alternativa que faça sentido para a política do produto. Se essa alternativa for um código enviado por e-mail, teste o caminho inteiro: emissão da mensagem, recebimento controlado, inserção do código e atualização do estado de verificação na aplicação.
Um e-mail observado na caixa de teste prova apenas que uma mensagem de teste chegou a um destino controlado. Não prova que o Credential Manager retornou uma credencial, que vp_token estava correto ou que o servidor validou assinatura, emissor, titular e nonce. Da mesma forma, uma resposta válida do servidor não comprova que o processo de recuperação por e-mail funciona. Mantenha evidências separadas para cada camada.
Ao preparar os dados de teste, evite usar endereços pessoais de colegas ou informação real de usuários. Além de misturar mensagens de teste com comunicações de trabalho, isso pode expor dados pessoais em ambientes, capturas de tela e registros de QA. O guia de cuidados com dados em testes pode ajudar a definir como reduzir essa exposição. Para diagnosticar especificamente mensagens de código que não chegam, consulte também o guia de solução para códigos de registro não recebidos.
A matriz de regressão precisa provar limites diferentes
A matriz abaixo ajuda a escolher o que cada teste realmente confirma. As avaliações são qualitativas: indicam a evidência produzida por cada verificação, não uma pontuação de confiabilidade.
| Verificação | Evidência que produz | O que não comprova | Prioridade |
|---|---|---|---|
Leitura de protocol e data |
O cliente reconhece a estrutura recebida | Autenticidade da credencial | Alta |
Localização de vp_token |
O parser encontra o campo no caminho esperado | Assinatura válida ou confiança no emissor | Alta |
| Validação no servidor | Resultado das verificações de credencial aplicadas pelo backend | Entrega do código por e-mail | Alta |
| Recebimento de e-mail de teste | A mensagem chegou ao destino controlado | Validade de uma credencial digital | Média |
| Estado final da aplicação | A interface reflete aprovação, recusa ou alternativa | Correção de cada camada, se testada isoladamente | Alta |
Use ainda uma lista de revisão antes de aprovar a alteração:
- O formato novo foi comparado com a documentação Android atual?
- A integração nova segue o formato atual, enquanto a migração trata apenas os formatos oficialmente pertinentes?
- Uma resposta incompleta ou desconhecida gera recusa controlada, sem ser convertida em sucesso?
- O servidor realiza as verificações de credencial antes de permitir criação de conta ou login?
- O fluxo de código por e-mail é exercitado separadamente, incluindo recebimento e atualização do estado no aplicativo?
- Os registros de teste omitem valores pessoais e dados sensíveis?
A tabela seguinte relaciona falhas observadas com a próxima ação. Use-a para evitar que a equipe corrija o componente errado.
| Sintoma observado | Próxima verificação | Interpretação segura |
|---|---|---|
vp_token aparece como ausente |
Inspecionar protocol e o conteúdo de data |
Pode ser caminho de leitura antigo; ainda não prova ausência de credencial |
| O parser encontra os campos, mas o servidor recusa | Revisar a validação e a resposta do backend | Análise concluída não significa validação aprovada |
| A credencial não está disponível | Exibir a alternativa definida pelo produto | Registrar como indisponibilidade, sem simular sucesso |
| O código por e-mail chega, mas a conta não muda de estado | Verificar a validação do código e a atualização no aplicativo | Recebimento da mensagem não comprova fechamento do fluxo |
| A estrutura recebida não corresponde ao esperado | Falhar de modo controlado e registrar formato redigido | Não inventar compatibilidade nem aceitar dados desconhecidos |
Feche o diagnóstico sem misturar as evidências
Para corrigir uma falha de análise, comece pelo caminho do campo: o código antigo pode procurar vp_token na raiz, enquanto o formato atual o organiza em data e inclui protocol. Depois confirme se a implementação é nova ou está em migração; por fim, prove separadamente a validação do servidor e a alternativa de e-mail. Essa ordem evita tratar uma resposta mal interpretada como falta de credencial ou como aprovação de identidade.
Se a equipe precisar validar somente o recebimento de um código no fluxo de fallback, um endereço temporário de teste pode ajudar a manter mensagens de QA separadas da caixa pessoal. FwdQuick pode ser avaliado como uma opção para esse uso, sem atribuir ao serviço a validação de Digital Credentials API nem garantia de entrega. Para consultar a opção de recebimento disponível, acesse FwdQuick; mantenha a prova de credencial e a prova de e-mail como resultados independentes.
Perguntas frequentes
Em qual parte da resposta nova devo procurar o vp_token?
No formato documentado para a integração atual, verifique primeiro o campo protocol e, em seguida, procure o vp_token dentro de data, em vez de pressupor que ele existe na raiz. Compare a resposta recebida com o exemplo oficial e preserve a estrutura original durante a inspeção. O caminho exato deve seguir o formato retornado pela biblioteca e a documentação Android vigente.
Por que meu código antigo não encontra o vp_token?
O parser pode estar buscando o campo na raiz da resposta, conforme a estrutura anterior, enquanto a estrutura atual envolve os dados em protocol e data. Isso produz um campo ausente para aquele caminho, mas não prova que a credencial esteja ausente. Registre a forma da resposta sem dados pessoais e confirme se a integração deve lidar com o formato novo ou com uma fase de migração.
Uma integração nova precisa aceitar a estrutura antiga também?
Para uma integração iniciada a partir de agosto de 2026, a orientação oficial é implementar o formato novo. Uma integração existente em migração deve seguir a instrução oficial para tratar as estruturas pertinentes durante a transição, sem manter compatibilidade antiga por suposição. Confirme a orientação e o andamento da descontinuação na documentação Android antes de remover qualquer ramo de compatibilidade.
O que o servidor ainda precisa verificar depois que o cliente lê o e-mail?
A leitura do campo pelo cliente não autentica a credencial. Antes de criar a conta ou permitir o login, o servidor deve validar a credencial segundo o protocolo: verificar a assinatura e a confiança no emissor, conferir a vinculação com o titular e validar o nonce original. O conjunto concreto de verificações depende do formato usado; siga as orientações oficiais e não trate um e-mail extraído como prova suficiente.
Escolha a rota conforme a duração do e-mail
Crie um endereço temporário para receber uma única mensagem; para pedidos, recuperação ou notificações contínuas, entre na conta e crie um alias de encaminhamento.