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

Para garantir a melhor experiência do usuário, verifique se há conexão de dados móveis antes iniciando uma solicitação de autenticação silenciosa.

Se o dispositivo não tiver uma conexão de dados móveis ativa, não inicie a etapa de Autenticação Silenciosa e passe diretamente para o próximo canal de verificação (SMS, RCS, voz etc.). Isso evita tentativas desnecessárias de solicitação e reduz o tempo total de verificação.

Observação: O Biblioteca do Cliente Atualmente, verifica a conectividade durante a execução. Ele lança exceções (como sdk_no_data_connectivity) quando são detectados problemas após o início da solicitação. Consulte Comportamento em caso de tempo limite para saber como lidar com essas exceções de tempo de execução.

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 uma situação em que os redirecionamentos não são recebidos corretamente pelo aplicativo móvel, possivelmente devido a problemas de rede durante a solicitação de check_url:

Vazão recomendada

Inicie a solicitação de autenticação silenciosa usando o SDK.
Se o SDK lançar uma exceção (por exemplo, sdk_no_data_connectivity), capture-o e chame imediatamente o seu backend’s next_workflow ponto final.
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.
Caso contrário, aguarde o retorno de chamada normal de autenticação.

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.