Tworzenie logiki weryfikacji

W tym dokumencie opisujemy proces tworzenia systemu sprawdzania adresów, który obsługuje różne odpowiedzi z interfejsu Address Validation API. Wyjaśniamy w nim, jak tworzyć logikę, aby prawidłowo korzystać z odpowiedzi, badać inne sygnały z interfejsu API oraz kiedy i jak prosić klientów o więcej informacji.

Odpowiedź interfejsu API określa ogólnie, w jaki sposób system powinien obsługiwać adres:

• Popraw – adres jest niskiej jakości. Powinieneś poprosić o więcej informacji.
• Potwierdź – adres jest wysokiej jakości, ale różni się od adresu wejściowego. Może pojawić się prośba o potwierdzenie.
• Accept – adres jest wysokiej jakości. Możesz zaakceptować podany adres.

Przeznaczenie klucza

Ten dokument pomoże Ci zmodyfikować system, aby jak najlepiej analizować odpowiedź interfejsu API i określać kolejne działania, które należy podjąć w przypadku podanych adresów. Poniższy pseudokod ilustruje możliwy przepływ.

if (the API response indicates significant problems in the address)
    FIX - prompt the user to fix the address
else if (the API response indicates less significant problems in the address)
    CONFIRM - confirm with the user that the address is correct
else
    ACCEPT - continue with the address returned by the API.

Dokładna logika zależy od Twojej sytuacji. Więcej informacji znajdziesz w wskazówkach dotyczących implementacji. Możesz też użyć naszej implementacji open source tej logiki, która znajduje się w bibliotece komponentów rozszerzonych.

Omówienie przepływu pracy

Tabela poniżej zawiera podsumowanie 2 działań w Twoim systemie:

1. Przepływ pracy, którego należy użyć na podstawie zachowania związanego z poprawianiem, potwierdzaniem i akceptowaniem.
2. Pierwsze sygnały do sprawdzenia w odpowiedzi. Sygnały opisane poniżej pochodzą z usługi verdict i nie są jedynymi sygnałami, które należy sprawdzić, ale stanowią wstępny wskaźnik jakości adresu. Każdy typ zachowania odpowiada sekcji w tym dokumencie, która zawiera opis dodatkowych sygnałów, które warto sprawdzić.

zachowanie systemu,
Popraw adres	Odpowiedź od verdict wskazuje na brak ważnych informacji, które należy podać. Adres zwrócony przez interfejs API może nie być odpowiedni do dostarczenia przesyłki. Przepływ pracy W razie potrzeby sprawdź komponenty adresu. Poproś klienta o rozwiązanie problemów z adresem. Poproś o weryfikację zaktualizowanego adresu. Kontynuuj z adresem. Sygnały dotyczące oceny Spełniony jest dowolny z tych warunków: validationGranularity ustawiono na OTHER. addressComplete to false.
Potwierdź adres	Odpowiedź z verdict wskazuje adres dostawy, ale wprowadza zmiany w oryginalnym wejściu: wnioskuje dane, które są poprawione pod względem pisowni lub które można potwierdzić. Przepływ pracy Korekty: W razie potrzeby sprawdź komponenty adresu. Poproś o weryfikację zaktualizowanego adresu. Kontynuuj z adresem. Nie wymaga korekty: Kontynuuj z adresem. Sygnały dotyczące oceny Wszystkie te warunki muszą być spełnione: validationGranularity zawiera ROUTE addressComplete to true. hasInferredComponents pole to true LUB hasReplacedComponents pole to true.
Zaakceptuj adres	Odpowiedź interfejsu Address Validation API wskazuje adres o doskonałej jakości. Przepływ pracy Użyj zwróconego adresu. Sygnały dotyczące oceny Wszystkie te warunki muszą być spełnione: validationGranularity zawiera co najmniej PREMISE. addressComplete to true. Brak wywnioskowanych lub zastąpionych komponentów.

Wskazówki dotyczące implementacji

Podczas projektowania sposobu, w jaki system reaguje na sygnały weryfikacji adresu, poniższe zalecenia mogą pomóc w utworzeniu skuteczniejszego modelu odpowiedzi. Są to jednak tylko rekomendacje, więc pamiętaj, że wdrożenie powinno być dostosowane do Twojego modelu biznesowego.

	Wskazówki	Szczegóły
Poziom ryzyka	Przy ustalaniu równowagi między wyświetlaniem prośby o poprawki a akceptowaniem wpisanego adresu weź pod uwagę poziom tolerancji w Twojej sytuacji.	Interfejs Address Validation API zwraca różne sygnały, które możesz uwzględnić w poziomie ryzyka, aby zoptymalizować proces weryfikacji. Jeśli na przykład adres ma niepotwierdzony numer ulicy, możesz go zaakceptować. Z drugiej strony, jeśli Twoja firma wymaga większej precyzji adresu, możesz poprosić użytkownika o podanie dokładniejszych informacji. Przykład, który może należeć do obu kategorii, znajdziesz w sekcji Niepotwierdzony numer domu spoza Stanów Zjednoczonych w artykule Akceptowanie adresu – przykłady.
Akceptowanie adresów	Warto zezwolić systemowi na zaakceptowanie pierwotnego wpisu, jeśli klient nie odpowie na prośby.	W takich przypadkach klient mógł wpisać adres, którego nie ma w systemie, np. w przypadku nowej konstrukcji.

Wypróbuj wersję demonstracyjną W dalszej części tego dokumentu znajdziesz różne przykłady, które pomogą Ci zrozumieć opisany powyżej proces naprawiania, potwierdzania i akceptowania. Wyniki tych przykładów możesz sprawdzić, wpisując je w wersji demonstracyjnej weryfikacji adresu w interfejsie Maps JavaScript API.

Poprawianie adresu

Popraw adres, jeśli wyniki wyraźnie wskazują, że nie można dostarczyć przesyłki. System może wtedy poprosić klienta o podanie niezbędnych informacji, a następnie ponownie uruchomić proces, aby uzyskać adres dostawy.

Sygnały dotyczące poprawek

Interfejs Address Validation API udostępnia szereg sygnałów, które informują, czy adres wymaga poprawy.

1. Granularność weryfikacji i brakujące komponenty

Te 2 sygnały najlepiej wskazują na problematyczny adres:

• Gdy pole validationGranularity ma wartość OTHER, system powinien zbadać sygnały komponentów adresu, aby dowiedzieć się więcej o tym, gdzie wystąpił błąd i jak go naprawić.
• Za każdym razem, gdy przetworzony obiekt address zwraca pole missingComponentTypes, system powinien sprawdzić ten komponent. Brakujące komponenty również sprawiają, że adres jest niekompletny i nie można go dostarczyć.

2. Inne sygnały

Interfejs Address Validation API udostępnia też inne sygnały, które pomagają diagnozować konkretne problemy:

Podejrzane komponenty	Jeśli wyliczenie poziomu potwierdzenia komponentu to UNCOMFIRMED_AND_SUSPICIOUS, prawdopodobnie komponent jest nieprawidłowy.
Nierozwiązany komponent	unresolvedToken to część danych wejściowych, która nie została rozpoznana jako prawidłowa część adresu.

3. Sygnały dotyczące adresu w Stanach Zjednoczonych

Niektóre pola mające zastosowanie tylko do adresów w Stanach Zjednoczonych stanowią przydatny sygnał, że adres jest nieprawidłowy i należy go poprawić. W przypadku adresu, który wymaga poprawy, zobaczysz te informacje:

dpvConfirmation	Może to być N, D lub wartość pusta.

Więcej informacji o dpvConfirmation znajdziesz w artykule Obsługa adresów w Stanach Zjednoczonych.

Przykłady poprawionych adresów

Potwierdzanie adresu

Adres jest potwierdzany, gdy wynik wskazuje, że interfejs Address Validation API wywnioskował lub zmienił komponenty adresu, aby uzyskać zweryfikowany adres. W takich przypadkach masz adres dostawy, ale chcesz mieć większą pewność, że wynikowy adres jest tym, o który chodziło klientowi.

Aby zapewnić klientowi odpowiednie podpowiedzi, Twoja logika powinna identyfikować komponenty oznaczone przez usługę, aby określić, jakie działanie lub flagę interfejs API zastosował do komponentu, np. inferred, replaced lub spellCorrected. Więcej informacji znajdziesz w sekcji AddressComponent w dokumentacji.

Uwaga: przy podejmowaniu decyzji, czy potwierdzić adres u klienta, czy zaakceptować go jako prawidłowy, weź pod uwagę poziom ryzyka.

Potwierdzanie sygnałów

Interfejs Address Validation API udostępnia szereg sygnałów, które informują, czy adres powinien zostać potwierdzony.

1. Szczegółowość weryfikacji

Dopuszczalna jest validationGranularity na poziomie co najmniej ROUTE, ale PREMISE lub SUBPREMISE dają silniejszy sygnał dostarczalności.

2. Inne sygnały

Decydując się na potwierdzenie adresu przez klienta, w ramach weryfikacji podajemy też te informacje, aby określić, które komponenty należy sprawdzić:

Dane wywnioskowane	Gdy pole hasInferredComponents ma wartość true, oznacza to, że interfejs API wypełnił informacje uzyskane z innych komponentów adresu.
Zastąpione dane	Gdy pole hasReplacedComponents ma wartość true, interfejs API zastępuje wpisane dane danymi, które uzna za prawidłowe dla adresu.

3. Sygnały dotyczące adresu w Stanach Zjednoczonych

Niektóre pola, które mają zastosowanie tylko w przypadku adresów w Stanach Zjednoczonych, wskazują, że logika powinna potwierdzić szczegóły z klientem. Spełniony jest jeden z tych warunków:

dpvConfirmation	S Więcej informacji o dpvConfirmation znajdziesz w artykule Obsługa adresów w Stanach Zjednoczonych.
Odpowiedź dotycząca adresu	Zawiera pole missingComponentTypes o wartości subpremise. Uwaga: jeśli pole zawiera typy inne niż subpremise, działanie zostanie zakwalifikowane do kategorii poprawiania adresu. Pełną listę typów adresów znajdziesz w dokumentacji Geocoding API.

Przykłady potwierdzania adresu

Akceptowanie adresu

Adres jest akceptowany, gdy wynik wskazuje na wysoki stopień pewności, że adres jest prawidłowy i może być używany w dalszym procesie bez konieczności interakcji z klientem.

Akceptowanie sygnałów

Interfejs Address Validation API udostępnia szereg sygnałów, które informują, czy adres powinien zostać potwierdzony.

1. Szczegółowość weryfikacji

Dopuszczalny jest validationGranularity o wartości PREMISE lub wyższej, ale w niektórych przypadkach ROUTE nadal wskazuje adres, pod który można dostarczyć przesyłkę.

2. Inne sygnały

Werdykt dotyczący adresu wysokiej jakości powinien też zawierać te informacje:

• Brak zastąpionych danych. W tym przypadku hasReplacedComponents: FALSE.
• Brak wywnioskowanych komponentów. W tym przypadku hasInferredComponents: FALSE.

3. Sygnały dotyczące adresu w Stanach Zjednoczonych

Niektóre pola mające zastosowanie tylko do adresów w Stanach Zjednoczonych wskazują na adres wysokiej jakości, pod który można dostarczyć przesyłkę. Prawidłowy adres w Stanach Zjednoczonych powinien zawierać te informacje:

dpvConfirmation	Y Więcej informacji o  dpvConfirmation znajdziesz w artykule Obsługa adresów w Stanach Zjednoczonych.

Akceptowanie przykładowych adresów