Autenticação silenciosa – Melhores práticas
Ignorar o Wi-Fi e forçar a conexão de dados móveis com os SDKs
A autenticação silenciosa requer uma conexão ativa de dados móveis. Se a solicitação for feita por Wi-Fi, ocorrerá um erro. Para garantir que a solicitação seja bem-sucedida mesmo quando o usuário estiver conectado ao Wi-Fi, a Vonage oferece uma solução nativa iOS e Android SDKs que exigem uma conexão de dados móveis.
O uso dos SDKs também ajuda a minimizar o impacto na experiência do usuário em casos extremos:
- Verificações de conectividade (por exemplo
sdk_no_data_connectivity) para que você possa acionar uma transição de failover mais rápida e sem interrupções. - Gerenciamento de tempo limite entre redirecionamentos para reduzir o tempo de espera em condições de baixa velocidade de dados móveis.
- Compatibilidade com o iOS 26 nos mercados em que for aplicável (por exemplo, Espanha).
Além disso, os SDKs da Vonage lidam com redirecionamentos HTTP (até 10) e gerenciam os tempos de espera (5 segundos, reiniciando após cada redirecionamento).
Use pontos de extremidade regionais para reduzir a latência
Para melhorar a latência da Autenticação Silenciosa, recomendamos usar o endpoint regional da Vonage que corresponda à localização do seu usuário final:
- América do Norte:
api-us.vonage.com - Europa:
api-eu.vonage.com - Ásia:
api-ap.vonage.com
Ao utilizar endpoints regionais, você garante que as solicitações sejam encaminhadas pelo caminho mais curto possível, o que ajuda a minimizar os atrasos causados por redirecionamentos.
Observação: O uso de um endpoint não regional (global) fará com que o tráfego dos EUA seja roteado pelos EUA. No entanto, todo o restante do tráfego, incluindo o proveniente da Ásia-Pacífico (AP), será roteado pela Europa, o que pode resultar em maior latência.
Front-end
A autenticação silenciosa no Verify oferece uma maneira fácil e direta de autenticar um usuário, proporcionando uma experiência de usuário aprimorada em comparação com outros canais.
Nos casos de criação de novas contas, o aplicativo móvel não terá acesso ao número de telefone do usuário final; portanto, esse número deverá ser coletado por meio de um campo de entrada na tela de boas-vindas. Por outro lado, um usuário final que já possua uma Account e esteja tentando fazer um login sem senha já terá seu número de telefone armazenado. Nesse caso, o usuário final poderá ver campos de texto pré-preenchidos, e a única ação necessária será selecionar “Verify”.
Durante a experiência de autenticação silenciosa, certifique-se de que o usuário esteja familiarizado com o processo e ciente de que a autenticação está ocorrendo em segundo plano.
Estado “Em andamento”
Para definir as expectativas enquanto a autenticação é executada em segundo plano, recomenda-se:
- Exiba uma roda giratória ou algum mecanismo de feedback semelhante para que o usuário final saiba que o aplicativo móvel está realizando a tarefa de autenticação.
- Como alternativa, exiba uma tela específica com o mesmo indicador de carregamento e um texto adicional.
Caminho para o Sucesso
Se a autenticação silenciosa for concluída com sucesso, o usuário deve ser direcionado para uma página de confirmação de sucesso, sem precisar digitar um código.
Caminho alternativo
No caso de uma falha durante o fluxo de autenticação silenciosa, a interface do aplicativo precisa ser ajustada para que o usuário possa inserir o código PIN para concluir o processo de autenticação de duas etapas (2FA). Esse código será enviado por meio dos canais de failover.
Em resumo, a figura abaixo ilustra as duas jornadas do usuário: a caminho para o sucesso (A autenticação silenciosa é concluída em segundo plano) e o caminho alternativo (o usuário é solicitado a inserir um código de failover).

Tratamento de erros e tempos limite na autenticação silenciosa
Devido à sua natureza, a Autenticação Silenciosa pode ser afetada por condições externas, como a falta de conectividade de dados móveis ou interrupções temporárias na rede. Para garantir uma experiência de usuário tranquila, seu aplicativo móvel deve contar com o Biblioteca do Clienteo tratamento de exceções integrado, em vez de implementar suas próprias verificações de rede e gerenciamento de tempo limite.
Quando o SDK encontrar um problema, ele lançará exceções específicas que indicam o que deu errado. Por exemplo, sdk_no_data_connectivity, gerado quando não há conexão de dados móveis disponível.
Evite iniciar a autenticação silenciosa sem dados móveis
Antes de iniciar uma solicitação de autenticação silenciosa, use o Bibliotecas de clientes para executar explicitamente uma verificação prévia da conectividade celular. Se o SDK detectar que os dados móveis não estão disponíveis (por exemplo, se o dispositivo estiver conectado apenas ao Wi-Fi ou não tiver sinal), ele retorna false (iOS) ou CellularStatus.Unavailable (Android). Seu aplicativo deve verificar esse resultado e prosseguir para o canal alternativo. Isso evita tentativas desnecessárias de solicitação e reduz o tempo total de verificação. Para obter detalhes sobre a implementação, consulte o README da biblioteca do cliente iOS ou README da biblioteca do cliente Android.
Se a verificação prévia falhar, o canal de autenticação silenciosa deve ser ignorado. Seu backend ainda pode chamar POST /v2/verify, mas deve fazê-lo sem o canal de autenticação silenciosa, utilizando apenas os canais alternativos escolhidos (por exemplo, SMS, RCS ou voz). Nesse caso, nenhum check_url é retornado e next_workflow não é necessário, pois o canal alternativo é iniciado diretamente.
Nota: Se ocorrerem problemas de conectividade após a criação da solicitação Verify (por exemplo, uma interrupção na rede durante o carregamento check_url), o SDK pode lançar exceções como sdk_no_data_connectivity. Nesse caso, use o valor retornado request_id e ligar next_workflow imediatamente por meio do seu backend. Veja Comportamento em caso de tempo limite para mais detalhes.
Comportamento em caso de tempo limite
Seu aplicativo deve interceptar essas exceções e notificar seu backend para chamar o next_workflow terminal imediatamente. Isso garante que o fluxo de verificação continue sem problemas, mesmo quando o fluxo de trabalho de autenticação silenciosa falhar ou não puder prosseguir.
Se o aplicativo móvel não realizar nenhuma ação para avançar para o próximo fluxo de trabalho, o sistema entrará automaticamente em tempo limite após 60 segundos e seguirá para o próximo fluxo de trabalho.
O diagrama de sequência abaixo ilustra dois cenários de falha: (1) a verificação prévia do SDK detecta que os dados móveis não estão disponíveis — a autenticação silenciosa é ignorada (portanto, não há check_url é retornado), e (2) uma solicitação de Verify é criada com sucesso, mas o aplicativo móvel não consegue concluir o fluxo de redirecionamento durante o carregamento check_url (por exemplo, devido a problemas de rede):
Vazão recomendada
- Antes de iniciar a Autenticação Silenciosa, chame explicitamente o método de pré-verificação do SDK para verificar a conectividade de celular. Para obter detalhes sobre a implementação, consulte o README da biblioteca do cliente iOS ou README da biblioteca do cliente Android.
- Se a verificação prévia retornar
false(iOS) ouCellularStatus.Unavailable(Android), ignore o canal de autenticação silenciosa. Seu backend ainda pode chamarPOST /v2/verify, mas deveria fazê-lo sem o canal de autenticação silenciosa — utilizando apenas os canais alternativos escolhidos por você (por exemplo, SMS, RCS ou voz). Nesse caso, nenhumcheck_urlé retornado enext_workflownão é necessário, pois o canal alternativo é iniciado diretamente. - Se a verificação prévia for bem-sucedida, inicie a Autenticação Silenciosa e solicite
check_urlpor meio do seu backend (POST /v2/verify). - Aguarde até que a autenticação silenciosa seja concluída em segundo plano. Se for bem-sucedida, passe para o estado autenticado.
- Se ocorrer uma exceção após a criação de uma solicitação de Verify (por exemplo, durante o carregamento
check_url), capture-o e chame seu backend para acionarnext_workflow(requerrequest_id). - Se nenhuma resposta ou chamada de retorno for recebida dentro do tempo limite interno do seu aplicativo (por exemplo, antes do padrão de 60 segundos), chame
next_workflowtambém.
Essa abordagem minimiza o tempo de espera, melhora a experiência do usuário e garante que seu backend sempre avance para a etapa correta do fluxo de trabalho.
next_workflow Comportamento de nova tentativa
Quando next_workflow Se a função for chamada enquanto a Autenticação Silenciosa ainda estiver concluindo sua configuração, o Verify coloca o evento na fila e tenta executá-lo novamente internamente por um curto período.
Se a autenticação silenciosa demorar mais do que o normal para iniciar e next_workflow se for chamada muito cedo no fluxo, a janela de repetição pode expirar. Nesse caso, a API retorna um erro HTTP 409 Conflict, solicitando que você tente novamente:
{
"type": "https://developer.vonage.com/en/api-errors/verify-v2#conflict",
"title": "Conflict",
"detail": "The operation cannot be performed at this time. Please try again later.",
"instance": "my-trace-id-trigger-next-replication-delay"
}
Cenários de failover
Nesta seção, listamos todos os cenários que podem ocorrer durante uma solicitação de autenticação silenciosa e oferecemos recomendações para implementações de failover, a fim de garantir a melhor experiência possível para o usuário final.
Alguns cenários acionam uma transição automática imediata para o próximo canal; no entanto, há casos em que a transição só é acionada após o tempo limite padrão de 60 segundos da autenticação silenciosa. Consulte a tabela abaixo, que resume os diferentes cenários de falha:
| Cenário | Motivo da falha | Código de falha | Resposta a falhas | Failover imediato? |
|---|---|---|---|---|
| 1 | Erro silencioso de autenticação | HTTP 409 | { "title": "Silent Auth error", "detail": "The Silent Auth request could not be completed due to formatting or the carrier is not supported."} |
Sim |
| 2 | Erro de MSISDN | HTTP 409 | { "title": "MSISDN Error", "detail": "Device MSISDN does not match."} |
Sim |
| 3 | Rede não compatível | HTTP 412 | { "title": "Network not supported", "detail": "Device number does not resolve to a supported Mobile Network Operator."} |
Sim |
| 4 | Erro de IP | HTTP 412 | { "title": "IP Error", "detail": "IP Address does not resolve to a cellular device."} |
Sim |
| 5 | Erros no SDK para iOS/Android | -- | sdk_no_data_connectivity, sdk_connection_error, sdk_redirect_error, sdk_error |
Não |
| 6 | next_workflow recebido muito cedo durante a configuração da Autenticação Silenciosa |
HTTP 409 | { "title": "Conflict", "detail": "The operation cannot be performed at this time. Please try again later."} |
Não |
Faturamento por autenticação silenciosa
Quando uma solicitação de Autenticação Silenciosa é iniciada, ela gera um lançamento referente à taxa da plataforma Verify e um ou dois lançamentos adicionais que representam o uso da Autenticação Silenciosa. O lançamento marcado como INITIATED nunca é cobrado. No total, uma única solicitação de Autenticação Silenciosa pode ter até três registros associados.
Testes
Para testar a autenticação silenciosa do Verify, você pode fazer o seguinte:
- Uso números virtuais.
- Permitir a listagem de números para redes compatíveis por meio do Registro de Rede.
Se um cliente precisar enviar tráfego em tempo real, ele deverá se cadastrar junto à operadora de celular por meio do Registro de Rede.