Esta página foi traduzida pela API Cloud Translation.

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.

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.

Acesse https://web-otp.glitch.me no Chrome 84 ou mais tarde em um dispositivo Android.
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 .

Observação:no momento, o Chrome só oferece suporte a chamadas de API WebOTP de iframes de origem cruzada. que não tenham mais de uma origem exclusiva na cadeia de ancestral. Na cenários a seguir:

a.com -> b.com
a.com -> b.com -> b.com
a.com -> a.com -> b.com
a.com -> b.com -> c.com

. É possível usar o WebOTP no b.com, mas não no c.com. O cenário a seguir também não é suportado devido à falta de demanda e complexidades de UX.

a.com -> b.com -> a.com (chama a API WebOTP)

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.

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

O que é a API WebOTP?

Confira na prática

Anotar uma tag <input>

Usar a API WebOTP

Detecção de recursos

Processar a OTP

Cancelando a mensagem

Formatar a mensagem SMS

Demonstrações

Usar WebOTP de um iframe de origem cruzada

Anotar origens vinculadas à mensagem de texto SMS

Configurar política de permissões

Usar o WebOTP no computador

Perguntas frequentes

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

Essa API é compatível com navegadores diferentes?

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

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

Como posso ajudar com esse recurso?

Recursos

Anotar uma tag `<input>`