Sign inGet Started
Rozpocznij
Przewodniki
Referencja API
SDK
CLI
Baza wiedzy
Changelog

Migracja Verify od innego dostawcy

Skorzystaj z tego przewodnika, aby przenieść telefoniczne i e-mailowe jednorazowe kody weryfikacyjne (OTP) od innego dostawcy weryfikacji do Bird Verify. Zakres prac jest niewielki, bo powierzchnia integracji jest niewielka: dwa wywołania zastępują parę create-and-check twojego obecnego dostawcy, a Bird odpowiada za kod, wiadomość i kanał dostarczenia.
Jedna różnica strukturalna wyznacza kształt pracy. Bird nie ma obiektu usługi per aplikacja ani identyfikatora weryfikacji, który musiałbyś śledzić. Weryfikacja jest identyfikowana przez odbiorcę, więc oba wywołania przyjmują ten sam to, a stan, który musi utrzymywać twoja integracja, spada do zera.
Lista kroków migracji:
  1. Zmapuj wywołania create i check
  2. Ustaw kanały, kraje i nadawcę
  3. Przenieś cykl życia weryfikacji
  4. Przełącz webhooki
  5. Przepnij ruch po jednym czasie życia kodu
Kroki 1 i 3 zależą od tego, od którego dostawcy odchodzisz. Twój przewodnik po dostawcy zawiera mapowanie pole po polu i translację statusów.

1. Zmapuj wywołania create i check

POST /v1/verify/verifications wysyła kod weryfikacyjny. Najmniejsze żądanie to odbiorca:
Przykład kodu
curl -X POST https://us1.platform.bird.com/v1/verify/verifications \
  -H "Authorization: Bearer $BIRD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to": {"phone_number": "+15551234567"}}'
POST /v1/verify/verifications/check przesyła to, co wpisał użytkownik, identyfikując weryfikację tym samym odbiorcą i kodem. Pełne dane żądań i odpowiedzi znajdziesz w Wysyłanie weryfikacji.
Cztery różnice do obsłużenia podczas przenoszenia:
  • Odbiorca jest kluczem. Dostawcy, którzy zwracają SID lub ID weryfikacji, oczekują go z powrotem przy sprawdzeniu. Bird dopasowuje po zbiorze adresów, i dopasowanie musi być dokładne: weryfikacji utworzonej z e-mailem i numerem telefonu nie odnajdziesz, podając tylko jedno z nich. Kolumnę przechowującą ID weryfikacji dostawcy możesz usunąć.
  • Błędny kod zwraca 200. Odpowiedź zawiera success: false, reason o wartości incorrect_code, expired lub attempts_exhausted oraz attempts_remaining. Ścieżkę błędów zarezerwuj dla awarii żądań. Gdy weryfikacja osiągnie stan końcowy, kolejne sprawdzenia zwracają 404 zamiast success: false.
  • Bird generuje kod i nigdy go nie zwraca. Nie ma parametru niestandardowego kodu, więc integracja, która dostarczała własny kod weryfikacyjny lub odczytywała go, by wysłać samodzielnie, nie ma tu odpowiednika.
  • Oba endpointy przyjmują Idempotency-Key. Powtórzone żądanie po upływie limitu czasu zwraca oryginalną odpowiedź bez wysyłania kolejnego kodu i bez zużywania próby.
Opcje per żądanie są celowo nieliczne: options.code_length i options.channels, które zmieniają kolejność lub zawężają kanały dla jednego żądania. Wszystko inne to konfiguracja obszaru roboczego, a nie pole w wywołaniu wysyłki.

2. Ustaw kanały, kraje i nadawcę

Bird dostarcza kody przez e-mail, SMS, WhatsApp i Telegram. Dla odbiorcy telefonicznego większość krajów próbuje najpierw WhatsApp z SMS jako rezerwą, a dostarczanie przechodzi do następnego kanału w planie, gdy wysyłka się nie powiedzie. Ustaw kolejność lub wyłącz kanał per kraj na stronie Countries; przy okazji wyłącz kraje, których nie obsługujesz, bo nieużywany kierunek to narażenie na pompowanie SMS, a nie zasięg.
Dwie luki warto sprawdzić względem obecnego przepływu, zanim ustalisz datę:
  • Nie ma kanału połączenia głosowego ani cichego uwierzytelniania sieciowego. Przepływ, który dla użytkowników nieodbierających SMS przełącza się na połączenie telefoniczne, wymaga tu innego rozwiązania.
  • Wybierz nadawcę przed przełączeniem. E-mail, SMS i WhatsApp domyślnie korzystają z Bird Verify i mogą zamiast tego używać Authifly. Możesz też użyć zweryfikowanej domeny e-mail, istniejącego identyfikatora nadawcy SMS lub połączonego numeru WhatsApp z zatwierdzonym szablonem uwierzytelniania. Telegram korzysta z własnego zweryfikowanego konta powiadomień. Jeśli chcesz zachować nadawcę SMS, którego Twoi użytkownicy już rozpoznają, sprawdź, czy jest obsługiwany i zarejestrowany w każdym kraju docelowym. Nadawcy i branding opisuje dostępne opcje i zachowanie awaryjne.
Jeśli używasz własnego numeru WhatsApp, wybierz istniejący zatwierdzony szablon uwierzytelniania w konfiguracji Verify. Bird kontroluje treść wiadomości e-mail i SMS. Nie możesz przekazać identyfikatora szablonu ani niestandardowej treści wiadomości w pojedynczym żądaniu weryfikacji.

3. Przenieś cykl życia weryfikacji

Weryfikacja pozostaje w stanie pending, dopóki się nie rozstrzygnie: verified, gdy poprawny kod dotrze na czas, failed z powodem attempts_exhausted lub undeliverable, albo expired z powodem ttl_elapsed. Zmapuj stany końcowe swojego dotychczasowego dostawcy na te trzy i traktuj reason jako otwarty enum.
Czasy kształtujące twój UI to ustawienia obszaru roboczego na stronie Configure: jak długo kod jest ważny, ile prób sprawdzenia ma użytkownik i jak długo trwa cooldown przed ponownym wysłaniem. Ustaw je tak, aby odpowiadały temu, czego doświadczają twoi użytkownicy, zamiast przepisywać teksty w UI. Długość kodu to jedyna wartość, którą możesz też ustawić per żądanie. Wartości domyślne i zakresy znajdziesz w Ustawienia weryfikacji.
Dwa zachowania zwykle zastępują kod, który już masz:
  • Ponowne wysłanie to ponowne wywołanie create. Wywołaj create z tym samym odbiorcą: w trakcie cooldownu zwróci aktywną weryfikację bez wysyłania, a po jego upływie wyśle nowy kod. Każdy kod wysłany w ramach aktywnej weryfikacji pozostaje ważny, dopóki weryfikacja się nie rozstrzygnie, więc użytkownik, który wpisze pierwszy kod po przyjściu drugiego, nie zostanie za to ukarany.
  • "I didn't get a code" ma własny endpoint. POST /v1/verify/verifications/next-channel przechodzi do następnego kanału w planie i natychmiast tam wysyła, ignorując cooldown ponownego wysłania, ale zachowując ważność, budżet prób i weryfikację. Podepnij go pod przycisk zamiast zapętlać ponowne wysyłki na kanale, który nie dociera.
Nad twoimi ustawieniami działają zabezpieczenia platformy, których nie konfigurujesz: limit wysyłek na adres na godzinę i limit sprawdzeń na odbiorcę, oba sygnalizowane przez 429 i Retry-After. Jeśli twój obecny dostawca pozwalał podnieść limity żądań per endpoint i to zrobiłeś, porównaj swój szczyt z wartościami w Zabezpieczenia przed nadużyciami przed przepięciem.

4. Przełącz webhooki

Verify emituje zdarzenia na dwóch osiach. Zdarzenia sesji, verify.verification.created, verify.verification.verified i verify.verification.failed, dotyczą samej weryfikacji. Zdarzenia prób, verify.attempt.sent, verify.attempt.delivered i verify.attempt.undelivered, dotyczą każdego pojedynczego wysłania kodu, więc ponowne wysłanie lub przełączenie kanału dodaje próby do tej samej sesji. Subskrybuj endpoint na interesujące Cię typy za pomocą POST /v1/webhooks; payloady znajdziesz w Zdarzenia Verify.
Subskrybuj zdarzenia sesji, których potrzebuje Twoja integracja. verify.verification.failed obejmuje ślepy zaułek dostarczania: uruchamia się z reason: "undeliverable", gdy plan kanałów jest wyczerpany, a zarejestrowane błędy wskazują, że żaden kod nie został wysłany; last_attempt_reason podaje przyczynę błędu na ostatnim próbowanym kanale. Weryfikacja, która wygaśnie lub wyczerpie liczbę prób sprawdzenia, nie emituje zdarzenia sesji, więc te dwa wyniki pobieraj z odpowiedzi na wywołanie check.
Te zdarzenia służą analityce, alertom i narzędziom wsparcia. Decyzja o uwierzytelnieniu pochodzi z wywołania check, które odpowiada synchronicznie, a przepływ logowania nigdy nie powinien czekać na webhook, żeby wpuścić użytkownika. Dostarczanie działa w trybie at-least-once i bez gwarancji kolejności, z podpisem zgodnym ze Standard Webhooks, więc deduplikuj po nagłówku webhook-id tak samo jak przy każdym innym zdarzeniu Bird.

5. Przełączaj po jednym czasie życia kodu naraz

Verify nie ma symulowanych odbiorców: tym, co warto testować, jest dotarcie kodu. Uruchom integrację z numerem telefonu i skrzynką pocztową, które kontrolujesz, na każdym włączonym kanale, zanim ruszysz produkcję.
Samo przełączenie ma jedną regułę, którą łatwo przeoczyć. Kod wystawiony przez starego dostawcę nie może być zweryfikowany przez Bird i odwrotnie. Przełączaj więc na poziomie wywołania create, a przez czas jednego życia kodu kieruj każde wywołanie check do dostawcy, który wystawił daną weryfikację. W praktyce:
  1. Zapisuj, który dostawca utworzył każdą aktywną weryfikację.
  2. Zacznij wysyłać część nowych weryfikacji przez Bird i sprawdzaj je względem Bird.
  3. Sprawdzaj starsze weryfikacje względem starego dostawcy, dopóki ostatnia nie wygaśnie, czyli przez jeden okres ważności kodu plus margines.
  4. Zwiększ udział Bird, gdy wskaźniki konwersji dla pierwszej kohorty wyglądają dobrze, a potem wycofaj starą ścieżkę.
Obserwuj konwersję, nie samo dostarczanie. Strona Verifications i metryki Verify pokazują wysyłki, dostarczenia oraz liczbę weryfikacji, które osiągnęły verified. To ta liczba mówi, czy kolejność kanałów lub nowa tożsamość nadawcy kosztuje Cię rejestracje.

Migracja z konkretnego dostawcy

  • Twilio Verify: Services stają się ustawieniami obszaru roboczego, VerificationCheck zamienia się w sprawdzenie po kluczu odbiorcy, translacja kanałów i statusów
  • Prelude: niemal identyczny kształt create-and-check; sygnały routingu i cicha weryfikacja to elementy, które się nie przenoszą

Następne kroki

Powiązane zasoby

Kontynuuj z dokumentacją, przewodnikami i przykładami dotyczącymi tego tematu. Zasoby są w języku angielskim.

Obejrzyj przewodnikVerify phone numbers at signupZrozum koncepcjęWhat does OTP mean? One-time passwords explainedPoznaj możliwościCustomer verificationPodążaj ścieżką naukiBuild your first integration
Wypróbuj ćwiczenie i uzyskaj brief wdrożeniowy