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) ou CellularStatus.Unavailable (Android), ignore o canal de autenticação silenciosa. Seu backend ainda pode chamar POST /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, nenhum check_url é retornado e next_workflow nã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_url por 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 acionar next_workflow (requer request_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_workflow també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.