Sign inGet Started

Impostazioni di verifica

La scheda General della pagina Configure definisce il comportamento di ogni verifica nel tuo spazio di lavoro. Controlla per quanto tempo resta valido un codice, quanti tentativi errati chiudono una verifica, dopo quanto tempo si può inviare un nuovo codice e a quale sito web o app Android appartiene il codice.

Ogni campo mostra il valore effettivo: il tuo valore personalizzato, se l'hai impostato, altrimenti il valore predefinito della piattaforma Bird. Un campo viene salvato quando lo lasci. Duration, Maximum Retries, Website e Android app hash vengono fissati alla creazione di una verifica, quindi una loro modifica vale per le nuove verifiche. Una modifica a Retry Delay vale dalla chiamata di creazione successiva, anche per una verifica già in corso.

Per modificare un'impostazione serve l'autorizzazione verify_management a livello write, inclusa nei ruoli admin e developer. Il ruolo analyst può visualizzare la pagina. Consulta Utenti, team e ruoli.

La scheda General della pagina Configure con i campi Duration, Maximum Retries, Retry Delay, Website e Android app hash

Ciclo di verifica

ImpostazioneCosa controllaPredefinitoIntervallo
DurationPer quanto tempo una verifica resta aperta. Un controllo eseguito dopo questo intervallo restituisce il motivo expired e la verifica termina con il motivo ttl_elapsed.10 minutiDa 1 a 999 minuti
Maximum RetriesQuanti codici errati chiudono una verifica. L'ultimo la fa fallire con il motivo attempts_exhausted.5Da 1 a 10
Retry DelayL'intervallo minimo tra un invio e il successivo: l'attesa minima prima che venga inviato un altro codice allo stesso destinatario.60 secondiDa 0 a 3600 secondi
  • Duration parte quando la verifica viene creata. Un nuovo invio o il passaggio a un altro canale invia un nuovo codice ma mantiene la scadenza originale, quindi un nuovo invio tardivo non estende la finestra. Per i flussi di autenticazione mantienilo a 10 minuti o meno; Best practice spiega perché.
  • Maximum Retries conta i codici errati su tutti i codici inviati per la verifica, quindi un nuovo invio non lo azzera. Un controllo con un codice errato che lascia la verifica in sospeso riporta i tentativi rimanenti in attempts_remaining.
  • Retry Delay si applica quando chiami di nuovo la creazione per lo stesso destinatario. Durante il periodo di attesa, la chiamata restituisce la verifica attiva senza inviare un nuovo codice. Invia il codice su un altro canale è escluso, perché il passaggio a un altro canale è una richiesta diversa da quella di ottenere di nuovo lo stesso canale. Impostalo a 0 per inviare un nuovo codice a ogni chiamata di creazione, entro i limiti per destinatario descritti in Protezioni contro gli abusi.

La lunghezza del codice non si imposta in questa pagina. Per impostazione predefinita i codici sono composti da sei cifre numeriche, e options.code_length imposta da 4 a 8 cifre per una singola verifica; vedi Opzioni.

Compilazione automatica

Website indica il sito in cui gli utenti inseriscono i codici, ad esempio https://login.example.com. Con un sito impostato, i browser possono proporre il codice su quel sito e su nessun altro, così l'utente non deve copiarlo. Lascia il campo vuoto per inviare codici che non indicano alcun sito.

Scrivi il sito come https:// seguito dal dominio in minuscolo, senza porta, percorso o barra finale. Un dominio internazionalizzato usa la forma xn--, ad esempio https://xn--bcher-kva.example per bücher.example. Qualsiasi altra forma viene rifiutata e, quando esiste, il messaggio indica la forma da inserire. Usa esattamente il sito che mostra il campo del codice: un modulo su login.example.com richiede https://login.example.com, non https://example.com.

Quando una verifica ha un sito, Verify lo aggiunge ai messaggi con il codice:

  • SMS: il messaggio termina con una riga come @login.example.com #123456, a meno che non sia impostato un Android app hash, che la sostituisce. Contrassegna il campo del codice con autocomplete="one-time-code" perché Safari e gli altri browser propongano il codice, e chiama la WebOTP API dalla pagina se vuoi che il browser lo compili senza un tocco. La riga aggiuntiva può aggiungere un segmento SMS: in molte lingue che richiedono la codifica Unicode, come arabo, greco o russo, un codice associato occupa due segmenti invece di uno, raddoppiando il costo SMS, e un dominio lungo può avere lo stesso effetto in altre lingue.
  • Email: il messaggio include un'intestazione OTP-Token con il codice e il sito, come definito dall'Internet-Draft OTP-Token, revisione 01. I client di posta stanno appena iniziando a leggere questa intestazione, quindi considerala un'aggiunta al codice nel messaggio.

Il sito viene fissato quando la verifica viene creata. Un nuovo invio, il ripiego su un altro canale o un'altra chiamata di creazione per lo stesso destinatario lo mantengono.

Hash dell'app Android

Android app hash indica la tua app Android, così l'app può leggere il codice dal SMS tramite la SMS Retriever API di Google, senza l'autorizzazione SMS e senza un tocco. Il valore è l'hash di 11 caratteri che Google ricava dal nome del pacchetto e dal certificato di firma della tua app, ad esempio FA+9qCX9VSu. Lascia il campo vuoto per inviare codici che non indicano alcuna app.

Con un hash impostato, il SMS è un messaggio breve che termina con l'hash su una riga a sé. Resta entro i 140 byte letti dalla SMS Retriever, in ogni lingua e con qualsiasi lunghezza del codice:

Esempio di codice
12345678 is your verification code.
FA+9qCX9VSu

Il messaggio breve omette la scadenza, l'avviso e la riga del sito web. L'email non cambia: include l'intestazione OTP-Token esattamente come farebbe senza un hash. Come il sito web, l'hash viene fissato alla creazione di una verifica.

Se preferisci non calcolare un hash, la SMS User Consent API di Google consente alla tua app di leggere i codici di Verify dopo un tocco, senza impostare nulla qui.

Calcolare l'hash dell'app

L'hash deriva dal certificato di firma della tua app, quindi Bird non può calcolarlo né verificarlo al posto tuo. Calcolalo con il comando riportato nella guida di Google, usando il keystore, l'alias del certificato e il nome del pacchetto:

Esempio di codice
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
  • Google Play firma la tua app: con Play App Signing, scarica il certificato di firma dell'app (deployment_cert.der) dalla sezione App signing di Play Console e calcola l'hash da questo certificato, non dalla chiave di caricamento. La guida di Google mostra come importarlo prima in un keystore.
  • Controlla gli errori: il comando stampa comunque 11 caratteri anche quando keytool non riesce, quindi leggi il suo output prima di copiare l'hash.
  • Build di debug: una build di debug è firmata con una chiave diversa, quindi ha un proprio hash. La classe di esempio AppSignatureHelper di Google stampa l'hash della build in esecuzione; rimuovila dall'app quando hai ottenuto il valore.

Associare un codice per singola richiesta

Una richiesta può indicare un proprio sito web con options.autofill_origin, che sostituisce Website per quella verifica. Usalo quando un solo spazio di lavoro serve più siti.

Allo stesso modo options.android_app_hash sostituisce Android app hash, ad esempio per inviare l'hash di una build di debug da un ambiente di test.

Quando il campo del codice si trova in un iframe cross-origin, come un modulo di pagamento incorporato nel checkout di un negozio, imposta options.autofill_origin sul sito web dell'iframe e options.autofill_top_level_origin sulla pagina aperta nella scheda del browser. La riga SMS indica allora entrambi i siti, come in @shop.example #123456 @pay.example, e questo può aggiungere un segmento in qualsiasi lingua. Chrome compila automaticamente quel modulo quando la pagina incorpora direttamente l'iframe e gli concede allow="otp-credentials". Per queste verifiche l'email non invia l'intestazione OTP-Token, perché l'intestazione può indicare un solo sito web. La richiesta viene rifiutata con 422 quando il sito web di primo livello non è valido, quando non è impostato alcun sito web né nella richiesta né in questa pagina, oppure quando coincide con quel sito web.

Mittenti SMS registrati

Se invii SMS dal tuo mittente registrato, come una campagna 10DLC negli Stati Uniti, aggiungi alla campagna un messaggio di esempio che termina con la riga del sito associato prima di impostare un sito web, e un esempio del messaggio breve prima di impostare un hash dell'app Android. Gli operatori possono filtrare un messaggio diverso dagli esempi registrati per la campagna.

Risoluzione dei problemi

  • Il sito web viene rifiutato. Il valore non è nel formato richiesto. Inserisci il formato suggerito dal messaggio, ad esempio https://example.com per https://Example.com/.
  • Il browser non propone il codice. Verifica che il sito web corrisponda esattamente all'indirizzo della pagina, compreso l'eventuale sottodominio, e che il campo del codice abbia autocomplete="one-time-code". Per un iframe, verifica che la richiesta imposti entrambi i siti web e che la pagina che lo incorpora conceda allow="otp-credentials". La compilazione automatica dipende anche dal browser: Chrome legge la riga SMS tramite WebOTP e Safari tramite la propria compilazione automatica dei codici, mentre Firefox non supporta WebOTP (supporto dei browser).
  • L'app Android non legge il codice. Verifica che l'hash provenga dal certificato che firma la build installata: il certificato di Play App Signing per un'app installata da Google Play e la chiave di debug per una build di debug. L'app deve avviare il SMS Retriever prima dell'invio del codice.
  • L'hash dell'app Android viene rifiutato. Il valore deve essere composto esattamente da 11 caratteri tra A e Z, tra a e z, tra 0 e 9, + e /, così come lo stampa il comando indicato sopra.
  • Un codice è scaduto prima che l'utente lo inserisse. Controlla i tempi dei tentativi nel log di Verify prima di aumentare Duration. Di solito la causa è un percorso di consegna lento, e una finestra più lunga indebolisce il codice.

Passaggi successivi

  • Invio delle verifiche: crea e controlla le verifiche, incluse le opzioni per singola richiesta.
  • Destinazioni: scegli i canali e il loro ordine per ogni paese di destinazione.
  • Mittenti e branding: visualizza i messaggi inviati da Verify e scegli il mittente per ogni canale.