Verificar números de telefone na Web com a API WebOTP

Ajudar usuários com OTPs recebidas por SMS

Eiji Kitamura

O que é a API WebOTP?

Hoje em dia, a maioria das pessoas no mundo possui um dispositivo móvel, e os desenvolvedores estão geralmente usam números de telefone como identificador para os usuários dos serviços.

Há várias maneiras de confirmar números de telefone, mas um número A senha única (OTP) enviada por SMS é uma das mais comuns. Enviando este código ao servidor do desenvolvedor demonstra o controle do número de telefone.

Essa ideia já está implantada em muitos cenários para alcançar:

  • Número de telefone como identificador do usuário. Ao se inscrever serviço, alguns sites pedem um número de telefone em vez de um endereço de e-mail e use-o como um identificador de conta.
  • Verificação em duas etapas. Ao fazer login, um site pede um código único enviado por SMS, além de uma senha ou outro fator de conhecimento, para receber segurança dos dados.
  • Confirmação do pagamento. Quando um usuário faz um pagamento, o código único enviado por SMS pode ajudar a verificar a intenção da pessoa.

O processo atual gera atrito para os usuários. Como encontrar uma OTP em um SMS e copiar e colar no formulário é complicado, reduzindo em jornadas ideais do usuário. O easing há muito tempo solicitações para a Web de muitos dos maiores desenvolvedores do mundo. O Android tem uma API que faz exatamente isso. Assim como No iOS e Safari

A API WebOTP permite que o aplicativo receba mensagens especialmente formatadas vinculadas domínio do seu app. Você pode receber programaticamente uma OTP por um SMS enviar uma mensagem e confirmar um número de telefone para o usuário com mais facilidade.

Confira na prática

Digamos que um usuário queira confirmar o número de telefone em um site. O site envia uma mensagem de texto ao usuário por SMS e ele insere a OTP da para confirmar a propriedade do número de telefone.

Com a API WebOTP, essas etapas são fáceis de usar, basta um toque para o usuário, demonstrados no vídeo. Quando a mensagem de texto chega, uma página inferior aparece e solicita que o usuário confirme o número de telefone. Depois de clicar no botão Verificar, na página inferior, o navegador cola a OTP no formulário e a formulário é enviado sem que o usuário precise pressionar Continuar.

Todo o processo está diagramado na imagem abaixo.

Diagrama da API WebOTP

Veja a demonstração. Ele não pede seu número de telefone ou enviar um SMS para o dispositivo, mas você pode enviar um de outro dispositivo copiando o texto da demonstração. Isso funciona porque não importa quem é o remetente ao usar a API WebOTP.

  1. Acesse https://web-otp.glitch.me no Chrome 84 ou mais tarde em um dispositivo Android.
  2. Envie a seguinte mensagem de texto SMS de outro telefone.
Your OTP is: 123456.

@web-otp.glitch.me #12345

Você recebeu o SMS e viu a solicitação para inserir o código na área de entrada? É assim que a API WebOTP funciona para os usuários.

O uso da API WebOTP consiste em três partes:

  • Uma tag <input> com a anotação correta
  • JavaScript no seu app da Web
  • Texto de mensagem formatado enviado por SMS.

Primeiro, vou abordar a tag <input>.

Anotar uma tag <input>

O próprio WebOTP funciona sem nenhuma anotação HTML, mas para navegadores diferentes compatível, é altamente recomendável adicionar autocomplete="one-time-code" a tag <input> em que você espera que o usuário insira uma OTP.

Isso permite que o Safari 14 ou versões mais recentes sugiram que o usuário preencha o <input> automaticamente. com uma OTP ao receberem um SMS com o formato descrito em Formatar a mensagem SMS, mesmo que o serviço não seja compatível com WebOTP.

HTML

<form>
  <input autocomplete="one-time-code" required/>
  <input type="submit">
</form>

Usar a API WebOTP

Como a WebOTP é simples, basta copiar e colar o código a seguir trabalho. De qualquer forma, vou explicar o que está acontecendo.

JavaScript

if ('OTPCredential' in window) {
  window.addEventListener('DOMContentLoaded', e => {
    const input = document.querySelector('input[autocomplete="one-time-code"]');
    if (!input) return;
    const ac = new AbortController();
    const form = input.closest('form');
    if (form) {
      form.addEventListener('submit', e => {
        ac.abort();
      });
    }
    navigator.credentials.get({
      otp: { transport:['sms'] },
      signal: ac.signal
    }).then(otp => {
      input.value = otp.code;
      if (form) form.submit();
    }).catch(err => {
      console.log(err);
    });
  });
}

Detecção de recursos

A detecção de recursos é a mesma de muitas outras APIs. Ouvindo O evento DOMContentLoaded aguardará até que a árvore do DOM esteja pronta para consulta.

JavaScript

if ('OTPCredential' in window) {
  window.addEventListener('DOMContentLoaded', e => {
    const input = document.querySelector('input[autocomplete="one-time-code"]');
    if (!input) return;
    …
    const form = input.closest('form');
    …
  });
}

Processar a OTP

A API WebOTP é bastante simples. Usar navigator.credentials.get() para receber a OTP. O WebOTP adiciona uma nova opção otp a esse método. Ele tem apenas uma propriedade: transport, cujo valor precisa ser uma matriz com a string 'sms'.

JavaScript

    …
    navigator.credentials.get({
      otp: { transport:['sms'] }
      …
    }).then(otp => {
    …

Isso aciona o fluxo de permissões do navegador quando uma mensagem SMS chega. Se a permissão for concedida, a promessa retornada é resolvida com um objeto OTPCredential.

Conteúdo do objeto OTPCredential recebido

{
  code: "123456" // Obtained OTP
  type: "otp"  // `type` is always "otp"
}

Em seguida, transmita o valor da OTP ao campo <input>. Enviar o formulário diretamente vai eliminar a etapa que exige que o usuário toque em um botão.

JavaScript

    …
    navigator.credentials.get({
      otp: { transport:['sms'] }
      …
    }).then(otp => {
      input.value = otp.code;
      if (form) form.submit();
    }).catch(err => {
      console.error(err);
    });
    …

Cancelando a mensagem

Caso o usuário insira uma OTP manualmente e envie o formulário, você poderá cancelar a chamada get() usando uma instância AbortController no objeto options.

JavaScript 

    …
    const ac = new AbortController();
    …
    if (form) {
      form.addEventListener('submit', e => {
        ac.abort();
      });
    }
    …
    navigator.credentials.get({
      otp: { transport:['sms'] },
      signal: ac.signal
    }).then(otp => {
    …

Formatar a mensagem SMS

A API em si deve parecer simples o suficiente, mas há algumas coisas que você precisa saber antes de usá-lo. A mensagem deve ser enviada depois de navigator.credentials.get() é chamado e precisa ser recebido no dispositivo em que get() foi chamado. Por fim, a mensagem precisa aderir ao seguinte: formatação:

  • A mensagem começa com um texto legível por humanos (opcional) que contém um número de quatro a dez sequência alfanumérica de caracteres com pelo menos um número na última linha para o URL e a OTP.
  • A parte do domínio do URL do site que invocou a API precisa ser precedida por @.
  • O URL precisa conter uma cerquilha ("#") seguido pela OTP.

Exemplo:

Your OTP is: 123456.

@www.example.com #123456

Aqui estão alguns exemplos ruins:

Exemplo de texto SMS incorreto Por que isso não funciona
Here is your code for @example.com #123456 Espera-se que @ seja o primeiro caractere da última linha.
Your code for @example.com is #123456 Espera-se que @ seja o primeiro caractere da última linha.
Your verification code is 123456

@example.com\t#123456		 Um único espaço é esperado entre @host e #code.
Your verification code is 123456

@example.com  #123456		 Um único espaço é esperado entre @host e #code.
Your verification code is 123456

@ftp://example.com #123456		 Não foi possível incluir o esquema do URL.
Your verification code is 123456

@https://example.com #123456		 Não foi possível incluir o esquema do URL.
Your verification code is 123456

@example.com:8080 #123456		 A porta não pode ser incluída.
Your verification code is 123456

@example.com/foobar #123456		 Não é possível incluir o caminho.
Your verification code is 123456

@example .com #123456		 Não há espaços em branco no domínio.
Your verification code is 123456

@domain-forbiden-chars-#%/:<>?@[] #123456		 Nenhum caractere proibido no domínio.
@example.com #123456

Mambo Jumbo		 @host e #code devem ser a última linha.
@example.com #123456

App hash #oudf08lkjsdf834		 @host e #code devem ser a última linha.
Your verification code is 123456

@example.com 123456		 # ausente.
Your verification code is 123456

example.com #123456		 @ ausente.
Hi mom, did you receive my last text @ e # ausentes.

Demonstrações

Teste várias mensagens com a demonstração: https://web-otp.glitch.me

Também é possível bifurcá-la e criar sua versão: https://glitch.com/edit/#!/web-otp.

Usar WebOTP de um iframe de origem cruzada

A inserção de uma OTP por SMS em um iframe de origem cruzada normalmente é usada para pagamento. a confirmação, especialmente com o 3D Secure. Ter o formato comum para dar suporte iframes de origem cruzada, a API WebOTP oferece OTPs vinculados a origens aninhadas. Por exemplo:

  • Um usuário visita shop.example para comprar um par de sapatos com um cartão de crédito.
  • Depois de inserir o número do cartão de crédito, o provedor de pagamento integrado mostrará um formulário de bank.example em um iframe solicitando que o usuário verifique a número de telefone para agilizar o pagamento.
  • O bank.example envia um SMS com uma OTP ao usuário para que ele possa inseri-lo para confirmar sua identidade.

Para usar a API WebOTP em um iframe de origem cruzada, você precisa fazer duas coisas:

  • Anotar a origem do frame superior e a origem do iframe no texto do SMS mensagem.
  • Configurar a política de permissões para permitir que o iframe de origem cruzada receba OTP diretamente do usuário.
.
a API WebOTP em um iframe em ação.

Confira a demonstração em https://web-otp-iframe-demo.stackblitz.io.

Anotar origens vinculadas à mensagem de texto SMS

Quando a API WebOTP é chamada de dentro de um iframe, a mensagem de texto SMS deve inclua a origem do frame superior precedida por @ seguida pela OTP precedida por # e a origem do iframe precedida por @ na última linha.

Your verification code is 123456

@shop.example #123456 @bank.exmple

Configurar política de permissões

Para usar o WebOTP em um iframe de origem cruzada, o incorporador precisa conceder acesso a esse API via política de permissões otp-credentials para evitar problemas do seu modelo. Em geral, há duas maneiras de atingir esse objetivo:

via cabeçalho HTTP:

Permissions-Policy: otp-credentials=(self "https://bank.example")

pelo atributo allow iframe:

<iframe src="https://bank.example/…" allow="otp-credentials"></iframe>

Veja mais exemplos sobre como especificar uma política de permissões .

Usar o WebOTP no computador

No Chrome, o WebOTP oferece suporte a detecção de mensagens SMS recebidas em outros dispositivos para ajudam os usuários a concluir a verificação do número de telefone no computador.

API WebOTP no computador.

Esse recurso exige que o usuário faça login na mesma Conta do Google nos dois para computadores e para Android.

Tudo que os desenvolvedores precisam fazer é implementar a API WebOTP em seu site para computador, da mesma forma que em seu site móvel, mas nenhum truque especial é obrigatórios.

Saiba mais detalhes em Verificar um número de telefone no computador usando a API WebOTP.

Perguntas frequentes

A caixa de diálogo não aparece, embora eu esteja enviando uma mensagem formatada corretamente. O que deu errado?

Há algumas ressalvas ao testar a API:

  • Se o número de telefone do remetente estiver na lista de contatos do destinatário, esta A API não será acionada devido ao design da API SMS User Consent.
  • Se você estiver usando um perfil de trabalho no seu dispositivo Android e o WebOTP não funcionar, tente instalar e usar o Chrome no seu perfil pessoal (ou seja, o mesmo perfil no qual você recebe mensagens SMS).

Verifique novamente o formato para ver se o SMS está formatado corretamente.

Essa API é compatível com navegadores diferentes?

O Chromium e o WebKit concordaram com o formato de mensagem de texto SMS e a Apple anunciou o suporte do Safari para ele a partir do iOS 14 e macOS Big Sur. Embora o Safari não seja compatível com a API JavaScript WebOTP, anotando um elemento input com autocomplete=["one-time-code"], o padrão o teclado sugere automaticamente que você insira a OTP caso a mensagem SMS esteja em conformidade com o formato.

É seguro usar o SMS como forma de autenticação?

Embora a OTP por SMS seja útil para verificar um número de telefone quando ele é o primeiro fornecido, a verificação do número de telefone via SMS deverá ser usada cuidadosamente para a reautenticação, já que as operadoras podem sequestrar e reutilizar os números de telefone. A WebOTP é um mecanismo conveniente de reautenticação e recuperação, mas os serviços combine-o com outros fatores, como um desafio de conhecimento, ou use o API Web Authentication para uma autenticação forte.

Onde informo bugs na implementação do Google Chrome?

Você encontrou um bug na implementação do Chrome?

  • Registre um bug em https://new.crbug.com. Incluir o máximo de detalhes possível, instruções simples para reprodução e Defina Componentes como Blink>WebOTP.

Como posso ajudar com esse recurso?

Você planeja usar a API WebOTP? Seu apoio público nos ajuda a priorizar e mostra a outros fornecedores de navegador como é fundamental oferecer suporte a eles. Envie um tweet para @ChromiumDev usando a hashtag #WebOTP e informe onde e como você o utiliza.

Recursos