Sign inGet Started

Ustawienia weryfikacji

Karta General na stronie Configure określa działanie każdej weryfikacji w Twoim obszarze roboczym. Ustala, jak długo kod pozostaje ważny, ile błędnych prób kończy weryfikację, po jakim czasie można wysłać nowy kod oraz do której witryny lub aplikacji na Androida należy kod.

Każde pole pokazuje obowiązującą wartość: Twoje nadpisanie, jeśli je ustawiono, a w przeciwnym razie domyślną wartość platformy Bird. Pole zapisuje się po jego opuszczeniu. Wartości Duration, Maximum Retries, Website i Android app hash są ustalane w chwili utworzenia weryfikacji, więc ich zmiana dotyczy nowych weryfikacji. Zmiana Retry Delay obowiązuje od następnego wywołania tworzącego, także dla weryfikacji, która już trwa.

Zmiana ustawienia wymaga uprawnienia verify_management na poziomie write, które mają role admin i developer. Rola analyst może wyświetlać stronę. Zobacz Użytkownicy, zespoły i role.

Karta General na stronie Configure z polami Duration, Maximum Retries, Retry Delay, Website i Android app hash

Cykl weryfikacji

UstawienieCo określaWartość domyślnaZakres
DurationJak długo weryfikacja pozostaje otwarta. Sprawdzenie po upływie tego czasu zwraca powód expired, a weryfikacja kończy się z powodem ttl_elapsed.10 minutOd 1 do 999 minut
Maximum RetriesIle błędnych kodów kończy weryfikację. Ostatni z nich kończy ją niepowodzeniem z powodem attempts_exhausted.5Od 1 do 10
Retry DelayCzas oczekiwania na ponowne wysłanie: minimalny odstęp, zanim do tego samego odbiorcy zostanie wysłany kolejny kod.60 sekundOd 0 do 3600 sekund
  • Duration zaczyna biec w chwili utworzenia weryfikacji. Ponowne wysłanie lub przełączenie na inny kanał wysyła nowy kod, ale zachowuje pierwotny czas wygaśnięcia, więc późne ponowne wysłanie nie wydłuża okna. W procesach uwierzytelniania ustaw najwyżej 10 minut; powody wyjaśnia strona Best practices.
  • Maximum Retries liczy błędne kody ze wszystkich kodów wysłanych w ramach weryfikacji, więc ponowne wysłanie go nie zeruje. Gdy sprawdzenie z błędnym kodem pozostawia weryfikację w toku, odpowiedź podaje liczbę pozostałych prób w attempts_remaining.
  • Retry Delay obowiązuje, gdy ponownie wywołujesz tworzenie dla tego samego odbiorcy. W okresie karencji wywołanie zwraca aktywną weryfikację bez wysyłania nowego kodu. Wysłanie kodu innym kanałem nie podlega temu ograniczeniu, ponieważ przełączenie kanału to inne żądanie niż ponowna prośba o ten sam kanał. Ustaw 0, aby wysyłać nowy kod przy każdym wywołaniu tworzenia, w granicach limitów na odbiorcę opisanych w Abuse guardrails.

Długości kodu nie ustawisz na tej stronie. Domyślnie kody mają sześć cyfr, a options.code_length ustawia od 4 do 8 cyfr dla pojedynczej weryfikacji; zobacz Options.

Autouzupełnianie

Website wskazuje witrynę, na której użytkownicy wpisują kody, na przykład https://login.example.com. Gdy witryna jest ustawiona, przeglądarki mogą podpowiadać kod tylko na tej witrynie, dzięki czemu użytkownik nie musi go kopiować. Pozostaw pole puste, aby wysyłać kody bez wskazania witryny.

Wpisz witrynę jako https://, a po nim domenę małymi literami, bez portu, ścieżki i końcowego ukośnika. Domena umiędzynarodowiona ma postać xn--, na przykład https://xn--bcher-kva.example dla bücher.example. Każda inna postać zostaje odrzucona, a komunikat podaje właściwą postać, jeśli taka istnieje. Użyj dokładnie tej witryny, na której wyświetla się pole kodu: formularz na login.example.com wymaga https://login.example.com, a nie https://example.com.

Gdy weryfikacja ma przypisaną witrynę, Verify dodaje ją do wiadomości z kodem:

  • SMS: wiadomość kończy się wierszem takim jak @login.example.com #123456, chyba że ustawiono Android app hash, który go zastępuje. Oznacz pole kodu atrybutem autocomplete="one-time-code", aby Safari i inne przeglądarki podpowiadały kod, i wywołaj na stronie WebOTP API, jeśli chcesz, aby przeglądarka wypełniała je bez stuknięcia. Dodatkowy wiersz może dodać segment SMS: w wielu językach wymagających kodowania Unicode, takich jak arabski, grecki czy rosyjski, kod powiązany z witryną zajmuje dwa segmenty zamiast jednego, co podwaja opłatę za SMS, a długa domena może mieć ten sam skutek w innych językach.
  • Email: wiadomość zawiera nagłówek OTP-Token z kodem i witryną, zgodnie z OTP-Token Internet-Draft, revision 01. Aplikacje pocztowe dopiero zaczynają odczytywać ten nagłówek, więc traktuj go jako uzupełnienie kodu w treści wiadomości.

Witryna zostaje ustalona w chwili utworzenia weryfikacji. Ponowne wysłanie, przejście na inny kanał zapasowy lub kolejne wywołanie tworzenia dla tego samego odbiorcy ją zachowuje.

Hash aplikacji na Androida

Android app hash wskazuje Twoją aplikację na Androida, dzięki czemu może ona odczytać kod z SMS za pomocą SMS Retriever API Google, bez uprawnienia SMS i bez stuknięcia. Wartość to 11-znakowy hash, który Google wylicza z nazwy pakietu aplikacji i certyfikatu podpisywania, na przykład FA+9qCX9VSu. Pozostaw pole puste, aby wysyłać kody bez wskazania aplikacji.

Gdy hash jest ustawiony, SMS to krótka wiadomość zakończona hashem w osobnym wierszu. Mieści się ona w 140 bajtach odczytywanych przez SMS Retriever, w każdym języku i przy każdej długości kodu:

Przykład kodu
12345678 is your verification code.
FA+9qCX9VSu

Krótka wiadomość pomija czas wygaśnięcia, ostrzeżenie i wiersz z witryną. E-mail się nie zmienia: zawiera nagłówek OTP-Token dokładnie tak samo jak bez hasha. Hash, podobnie jak witryna, zostaje ustalony w chwili utworzenia weryfikacji.

Jeśli nie chcesz wyliczać hasha, SMS User Consent API Google pozwala aplikacji odczytać kody Verify po jednym stuknięciu, bez ustawiania czegokolwiek na tej stronie.

Wyliczanie hasha aplikacji

Hash pochodzi z certyfikatu podpisywania aplikacji, więc Bird nie może go za Ciebie wyliczyć ani sprawdzić. Wylicz go poleceniem z przewodnika Google, podając swój magazyn kluczy, alias certyfikatu i nazwę pakietu:

Przykład kodu
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 podpisuje Twoją aplikację: jeśli używasz podpisywania aplikacji przez Google Play, pobierz certyfikat podpisywania aplikacji (deployment_cert.der) z sekcji App signing w Play Console i oblicz hash na jego podstawie, a nie na podstawie klucza przesyłania. Przewodnik Google pokazuje, jak najpierw zaimportować go do magazynu kluczy.
  • Sprawdź błędy: polecenie wypisuje 11 znaków nawet wtedy, gdy keytool zakończy się błędem, więc przed skopiowaniem hasha przeczytaj jego wynik.
  • Kompilacje debugowe: kompilacja debugowa jest podpisana innym kluczem, więc ma własny hash. Przykładowa klasa AppSignatureHelper od Google wypisuje hash uruchomionej kompilacji; usuń ją z aplikacji, gdy uzyskasz wartość.

Powiązanie kodu z witryną w pojedynczym żądaniu

Żądanie może wskazać własną witrynę za pomocą options.autofill_origin, która zastępuje pole Website dla tej weryfikacji. Używaj tej opcji, gdy jeden obszar roboczy obsługuje kilka witryn.

options.android_app_hash w ten sam sposób zastępuje pole Android app hash, na przykład aby wysłać hash kompilacji debugowej ze środowiska testowego.

Gdy pole kodu znajduje się w ramce iframe z innego źródła, na przykład w formularzu płatności osadzonym na stronie zamówienia sklepu, ustaw options.autofill_origin na witrynę ramki iframe, a options.autofill_top_level_origin na stronę otwartą w karcie przeglądarki. Wiersz SMS wskazuje wtedy obie witryny, jak w @shop.example #123456 @pay.example, co w każdym języku może dodać segment. Chrome automatycznie wypełnia taki formularz, gdy strona osadza ramkę iframe bezpośrednio i przyznaje jej allow="otp-credentials". W przypadku tych weryfikacji e-mail nie zawiera nagłówka OTP-Token, ponieważ nagłówek może wskazywać tylko jedną witrynę. Żądanie zostaje odrzucone z 422, gdy witryna najwyższego poziomu ma nieprawidłowy format, gdy ani żądanie, ani ta strona nie ustawia witryny albo gdy jest ona taka sama jak ta witryna.

Zarejestrowani nadawcy SMS

Jeśli wysyłasz SMS z własnego zarejestrowanego nadawcy, na przykład w ramach kampanii US 10DLC, przed ustawieniem witryny dodaj do kampanii przykładową wiadomość kończącą się wierszem powiązania, a przed ustawieniem hasha aplikacji Android przykład krótkiej wiadomości. Operatorzy mogą filtrować wiadomości, które różnią się od zarejestrowanych przykładów kampanii.

Rozwiązywanie problemów

  • Witryna zostaje odrzucona. Wartość nie ma wymaganego formatu. Wpisz format podany w komunikacie, na przykład https://example.com dla https://Example.com/.
  • Przeglądarka nie proponuje kodu. Sprawdź, czy witryna dokładnie odpowiada adresowi strony, łącznie z ewentualną subdomeną, i czy pole kodu ma autocomplete="one-time-code". W przypadku ramki iframe sprawdź, czy żądanie ustawia obie witryny i czy strona osadzająca przyznaje allow="otp-credentials". Automatyczne wypełnianie zależy też od przeglądarki: Chrome odczytuje wiersz SMS przez WebOTP, a Safari przez własne automatyczne wypełnianie kodów, natomiast Firefox nie obsługuje WebOTP (obsługa w przeglądarkach).
  • Aplikacja Android nie odczytuje kodu. Sprawdź, czy hash pochodzi z certyfikatu, którym podpisano zainstalowaną kompilację: z certyfikatu Play App Signing dla aplikacji zainstalowanej z Google Play i z klucza debugowego dla kompilacji debugowej. Aplikacja musi uruchomić SMS Retriever przed wysłaniem kodu.
  • Hash aplikacji Android zostaje odrzucony. Wartość musi mieć dokładnie 11 znaków spośród A–Z, a–z, 0–9, + i /, tak jak wypisuje ją powyższe polecenie.
  • Kod wygasł, zanim użytkownik go wpisał. Zanim zwiększysz wartość Duration, sprawdź czas prób w dzienniku Verify. Przyczyną jest zwykle wolna ścieżka dostarczania, a dłuższe okno osłabia kod.

Dalsze kroki

  • Wysyłanie weryfikacji: twórz i sprawdzaj weryfikacje, w tym z opcjami dla pojedynczych żądań.
  • Miejsca docelowe: wybierz kanały i ich kolejność dla każdego kraju docelowego.
  • Nadawcy i branding: zobacz wiadomości wysyłane przez Verify i wybierz nadawcę dla każdego kanału.