Sign inGet Started

Configurações de verificação

A aba General da página Configure define como cada verificação do seu espaço de trabalho se comporta. Ela controla por quanto tempo um código permanece válido, quantas tentativas erradas encerram uma verificação, quanto tempo depois um novo código pode ser enviado e a qual site ou aplicativo Android o código pertence.

Cada campo mostra o valor efetivo: a sua substituição, quando você definiu uma, ou então o padrão da plataforma da Bird. Um campo é salvo quando você sai dele. Duration, Maximum Retries, Website e Android app hash são fixados quando uma verificação é criada, então uma alteração neles vale para novas verificações. Uma alteração em Retry Delay vale para a próxima chamada de criação, inclusive para uma verificação já em andamento.

Para alterar uma configuração, é preciso ter a permissão verify_management no nível write, incluída nas funções admin e developer. A função analyst pode visualizar a página. Consulte Usuários, equipes e funções.

A aba General da página Configure com os campos Duration, Maximum Retries, Retry Delay, Website e Android app hash

Ciclo da verificação

ConfiguraçãoO que controlaPadrãoIntervalo
DurationPor quanto tempo uma verificação fica aberta. Uma checagem feita após esse período retorna o motivo expired, e a verificação termina com o motivo ttl_elapsed.10 minutosDe 1 a 999 minutos
Maximum RetriesQuantos códigos incorretos encerram uma verificação. O último faz a verificação falhar com o motivo attempts_exhausted.5De 1 a 10
Retry DelayO intervalo de reenvio: a espera mínima antes que outro código seja enviado ao mesmo destinatário.60 segundosDe 0 a 3.600 segundos
  • A Duration começa a contar quando a verificação é criada. Um reenvio ou uma troca para outro canal envia um novo código, mas mantém a expiração original, então um reenvio tardio não estende a janela. Para fluxos de autenticação, mantenha o valor em 10 minutos ou menos; Best practices explica o motivo.
  • Maximum Retries conta os códigos errados de todos os códigos enviados para a verificação, então um reenvio não zera essa contagem. Uma checagem com um código errado que deixa a verificação pendente informa as tentativas restantes em attempts_remaining.
  • Retry Delay se aplica quando você chama a criação novamente para o mesmo destinatário. Durante o intervalo de espera, a chamada retorna a verificação ativa sem enviar um novo código. Enviar o código por outro canal é uma exceção, porque trocar de canal é uma solicitação diferente de pedir o mesmo canal de novo. Defina o valor como 0 para enviar um novo código a cada chamada de criação, dentro dos limites por destinatário descritos em Abuse guardrails.

O tamanho do código não fica nesta página. Por padrão, os códigos têm seis dígitos numéricos, e options.code_length define de 4 a 8 dígitos para uma verificação; consulte Options.

Preenchimento automático

Website indica o site onde seus usuários digitam os códigos, como https://login.example.com. Com um site definido, os navegadores podem oferecer o código nesse site e em nenhum outro, o que poupa o usuário de copiá-lo. Deixe o campo vazio para enviar códigos que não indicam nenhum site.

Escreva o site como https:// seguido do domínio em letras minúsculas, sem porta, caminho ou barra final. Um domínio internacionalizado usa a forma xn--, por exemplo https://xn--bcher-kva.example para bücher.example. Qualquer outra forma é rejeitada, e a mensagem indica a forma correta quando ela existe. Use exatamente o site que exibe o campo do código: um formulário em login.example.com precisa de https://login.example.com, e não de https://example.com.

Quando uma verificação tem um site, o Verify o adiciona às mensagens com o código:

  • SMS: a mensagem termina com uma linha como @login.example.com #123456, a menos que um Android app hash esteja definido, que a substitui. Marque o campo do código com autocomplete="one-time-code" para que o Safari e outros navegadores ofereçam o código, e chame a API WebOTP na página se quiser que o navegador o preencha sem um toque. A linha extra pode acrescentar um segmento de SMS. Em muitos idiomas que exigem codificação Unicode, como árabe, grego ou russo, um código vinculado ocupa dois segmentos em vez de um, o que dobra a cobrança de SMS. Um domínio longo pode ter o mesmo efeito em outros idiomas.
  • Email: a mensagem inclui um cabeçalho OTP-Token com o código e o site, conforme definido no Internet-Draft OTP-Token, revisão 01. Os aplicativos de e-mail estão apenas começando a ler esse cabeçalho, então trate-o como um complemento ao código na mensagem.

O site é fixado quando a verificação é criada. Um reenvio, um fallback para outro canal ou outra chamada de criação para o mesmo destinatário mantém esse site.

Android app hash

Android app hash identifica o seu aplicativo Android, para que ele possa ler o código do SMS por meio da API SMS Retriever do Google, sem a permissão SMS e sem nenhum toque. O valor é o hash de 11 caracteres que o Google deriva do nome do pacote e do certificado de assinatura do seu aplicativo, como FA+9qCX9VSu. Deixe o campo vazio para enviar códigos que não indicam nenhum aplicativo.

Com um hash definido, o SMS é uma mensagem curta que termina com o hash em uma linha própria. Ela fica dentro dos 140 bytes que o SMS Retriever lê, em qualquer idioma e com qualquer tamanho de código:

Exemplo de código
12345678 is your verification code.
FA+9qCX9VSu

A mensagem curta omite a expiração, o aviso e a linha do site. O e-mail não muda: ele inclui o cabeçalho OTP-Token exatamente como faria sem um hash. Assim como o site, o hash é fixado quando a verificação é criada.

Se você preferir não calcular um hash, a API SMS User Consent do Google permite que o seu aplicativo leia os códigos do Verify após um toque, sem nada para definir aqui.

Calcular o hash do aplicativo

O hash vem do certificado de assinatura do seu aplicativo, então a Bird não pode calculá-lo nem verificá-lo por você. Calcule-o com o comando do guia do Google, usando o seu keystore, o alias do certificado e o nome do pacote:

Exemplo de código
keytool -exportcert -alias KEY_ALIAS -keystore MY_KEYSTORE.keystore | xxd -p | tr -d "[:space:]" | echo -n com.example.myapp `cat` | sha256sum | tr -d "[:space:]-" | xxd -r -p | base64 | cut -c1-11
  • O Google Play assina seu app: com a Play App Signing, baixe o certificado de assinatura do app (deployment_cert.der) na seção App signing do Play Console e calcule o hash a partir dele, e não da sua chave de upload. O guia do Google mostra como importá-lo antes para um keystore.
  • Verifique se há erros: o comando ainda imprime 11 caracteres quando keytool falha, então leia a saída dele antes de copiar o hash.
  • Builds de depuração: um build de depuração é assinado com outra chave, então tem um hash próprio. A classe de exemplo AppSignatureHelper do Google imprime o hash do build em execução; remova-a do seu app depois de obter o valor.

Vincular um código por solicitação

Uma solicitação pode definir o próprio site com options.autofill_origin, que substitui Website para essa verificação. Use essa opção quando um espaço de trabalho atende a vários sites.

options.android_app_hash substitui Android app hash da mesma forma, por exemplo para enviar o hash de um build de depuração a partir de um ambiente de teste.

Quando o campo do código fica em um iframe de outra origem, como um formulário de pagamento incorporado ao checkout de uma loja, defina options.autofill_origin como o site do iframe e options.autofill_top_level_origin como a página aberta na aba do navegador. A linha SMS passa então a indicar os dois sites, como em @shop.example #123456 @pay.example, o que pode acrescentar um segmento em qualquer idioma. O Chrome preenche automaticamente esse formulário quando a página incorpora o iframe diretamente e concede a ele allow="otp-credentials". O e-mail não envia o cabeçalho OTP-Token nessas verificações, porque o cabeçalho só pode indicar um site. A solicitação é rejeitada com 422 quando o site de nível superior está malformado, quando nenhum site está definido na solicitação nem nesta página, ou quando ele é igual a esse site.

Remetentes SMS registrados

Se você envia SMS pelo seu próprio remetente registrado, como uma campanha 10DLC nos EUA, adicione à campanha uma mensagem de exemplo que termine com a linha vinculada antes de definir um site, e um exemplo da mensagem curta antes de definir um hash de app Android. As operadoras podem filtrar uma mensagem diferente dos exemplos registrados na campanha.

Solução de problemas

  • O site é rejeitado. O valor não está no formato exigido. Informe o formato sugerido na mensagem, por exemplo https://example.com para https://Example.com/.
  • O navegador não oferece o código. Verifique se o site corresponde exatamente ao endereço da página, incluindo qualquer subdomínio, e se o campo do código tem autocomplete="one-time-code". Para um iframe, verifique se a solicitação define os dois sites e se a página que o incorpora concede allow="otp-credentials". O preenchimento automático também depende do navegador: o Chrome lê a linha SMS pelo WebOTP e o Safari pelo seu preenchimento automático de códigos, enquanto o Firefox não oferece suporte ao WebOTP (suporte dos navegadores).
  • O app Android não lê o código. Verifique se o hash vem do certificado que assina o build instalado: o certificado da Play App Signing para um app instalado pelo Google Play e a chave de depuração para um build de depuração. O app precisa iniciar o SMS Retriever antes de o código ser enviado.
  • O hash do app Android é rejeitado. O valor precisa ter exatamente 11 caracteres entre A e Z, a e z, 0 e 9, + e /, como o comando acima o imprime.
  • Um código expirou antes de o usuário digitá-lo. Confira o tempo das tentativas no log do Verify antes de aumentar Duration. Normalmente a causa é uma rota de entrega lenta, e uma janela mais longa enfraquece o código.

Próximos passos