במסמך הזה מתואר תהליך היצירה של מערכת לבדיקת כתובות שתטפל במגוון תשובות מ-Address Validation API. במאמר הזה נסביר איך לבנות את הלוגיקה שלכם כדי להשתמש בצורה נכונה בתשובה, לחקור אותות אחרים מה-API, ואיך לבקש מידע נוסף מהלקוחות.
באופן כללי, תגובת ה-API קובעת את הדרכים הבאות שהמערכת שלכם צריכה לטפל בכתובת:
- תיקון – הכתובת באיכות נמוכה. עליך לבקש מידע נוסף.
- אישור – הכתובת באיכות גבוהה אבל עם שינויים בכתובת הקלט. יכול להיות שתתבקשו לאשר.
- אישור – הכתובת באיכות גבוהה. ניתן לאשר את הכתובת שצוינה.
מטרת המפתח
במסמך הזה מוסבר איך לשנות את המערכת כדי לנתח את התגובה מה-API בצורה הטובה ביותר ולהחליט מה לעשות עם הכתובות שסופקו. הקוד המדומה הבא ממחיש את התהליך האפשרי.
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.
הלוגיקה המדויקת תלויה במצב שלכם. פרטים נוספים זמינים בהנחיות ההטמעה. אפשר גם להשתמש בהטמעה של הלוגיקה הזו בקוד פתוח, שנמצאת בספריית הרכיבים המורחבת.
סקירה כללית של תהליך העבודה
הטבלה הבאה מסכמת שתי פעולות שניתן לבצע במערכת:
- תהליך העבודה שצריך להשתמש בו בהתאם לאופן הפעולה, לאישור ולתיקון.
- האותות הראשונים שצריך לבדוק מהתשובה. האותות שמתוארים כאן מגיעים מהמאפיין
verdict, והם לא האותות היחידים שצריך לבדוק, אבל הם מספקים אינדיקטור ראשוני לאיכות הכתובת. כל סוג התנהגות תואם לקטע במסמך הזה, שמתאר סימנים נוספים שאולי צריך לחקור.
| התנהגות המערכת | |||
|---|---|---|---|
| תיקון הכתובת |
התשובה מ-
|
||
| אישור הכתובת |
התשובה מ-
|
||
| אישור הכתובת |
תגובת ה-API לאימות כתובת מציינת כתובת באיכות מצוינת.
|
||
הנחיות להטמעה
כשאתם מתכננים את האופן שבו המערכת שלכם תגיב לאותות מה-API לאימות כתובת, תוכלו להיעזר בהמלצות הבאות כדי ליצור מודל תגובה יעיל יותר. עם זאת, אלו רק המלצות, אז כדאי לזכור שההטמעה צריכה להתאים למודל העסקי שלכם.
| הנחיות | פרטים | |
|---|---|---|
| רמת סיכון |
חשוב להביא בחשבון את רמת הסבלנות כלפי המצב שלך בזמן איזון בין בקשות לתיקונים לבין אישור הכתובת כפי שהוזנה. |
ה-API לאימות כתובת מחזיר מגוון אותות שאפשר לשלב עם רמת הסיכון כדי לבצע אופטימיזציה של תהליך האימות. לדוגמה, אם בכתובת יש מספר בית שלא אושר, עדיין אפשר לקבל אותו. לעומת זאת, אם הפעילות העסקית שלכם דורשת רמת דיוק גבוהה יותר של כתובות, יכול להיות שתתבקשו לשלוח הודעה למשתמש. דוגמאות שיכולות להשתייך לכל אחת מהקטגוריות האלה, ראו מספר בית שלא אושר מחוץ לארה"ב בקטע אישור כתובת – דוגמאות. |
| קבלת כתובות |
מומלץ לאפשר למערכת לקבל את הרשומה המקורית אם הלקוח לא מגיב להנחיות. |
במקרים כאלה, יכול להיות שהלקוח הזין כתובת שאינה במערכת, למשל כתובת של אתר חדש. |
| שליחת משוב |
כששולחים מחדש בקשה לאימות כתובת, אפשר
גם לשלוח בקשה לנקודת הקצה (endpoint) |
כך Google תדע איך טיפלת בסוף התשובה הסופית. איך מטפלים בכתובות שעודכנו |
תיקון כתובת
מתקנים כתובת כאשר התוצאות מציינות בבירור שלא ניתן למסור אותה. לאחר מכן המערכת יכולה לבקש מהלקוח לספק את המידע הנדרש, ולאחר מכן לשלוח מחדש את תהליך העבודה כדי לקבל כתובת למסירה.
תיקון אותות
ה-API לאימות כתובת מספק כמה אותות שמיידעים אתכם אם צריך לתקן את הכתובת.
1. רמת הפירוט של האימות ורכיבים חסרים
שני האותות הבאים מספקים את הזיהוי הטוב ביותר לכתובת בעייתית:
- כשהשדה
validationGranularityהואOTHER, המערכת צריכה לחקור את האותות של רכיבי הכתובת כדי להבין איפה התרחשה השגיאה ואיך לתקן אותה. - בכל פעם שאובייקט
addressשעבר עיבוד מחזיר שדהmissingComponentTypes, המערכת צריכה לבדוק אם הרכיב הזה קיים. בנוסף, רכיבים חסרים מעבדים כתובת חלקית ולא ניתן למסור אותה.
2. אותות אחרים
ה-API לאימות כתובת מספק גם אותות אחרים כדי לעזור לאבחן בעיות ספציפיות:
| רכיבים חשודים | כשרמת האישור של טיפוסים בני מנייה (enum) לרכיב היא UNCOMFIRMED_AND_SUSPICIOUS, סביר להניח שהרכיב שגוי.
|
|---|---|
| רכיב שלא נפתר | unresolvedToken הוא חלק מהקלט שלא מזוהה כחלק תקין של כתובת. |
3. אותות של כתובת בארה"ב
שדות מסוימים שרלוונטיים רק לכתובות בארה"ב מספקים אות שימושי לכך שלא ניתן לספק את הכתובת וצריך לתקן אותה. אם צריך לתקן את הכתובת, אתם צריכים לראות את הפרטים הבאים:
dpvConfirmation
|
N, D או ריק.
|
|---|
לפרטים על dpvConfirmation ראו טיפול בכתובות בארצות הברית.
אישור כתובת
מאשרים כתובת כשבתוצאה מצוין שה-API לאימות כתובת הסקת מסקנות או ביצע שינויים ברכיבי הכתובת כדי להפיק כתובת מאומתת. במקרים כאלה יש לכם כתובת למשלוח, אבל עדיף להיות בטוחים יותר שהכתובת שמתקבלת היא הכתובת שהלקוח התכוון אליה.
כדי לספק ללקוח את ההנחיות הנכונות, הלוגיקה שלכם תזהה את הרכיבים שסומנו על ידי השירות כדי לקבוע איזו פעולה או סימון של ה-API הוחל על הרכיב, כמו inferred, replaced או spellCorrected.
פרטים נוספים מופיעים בקטע AddressComponent בחומר העזר.
אישור האותות
ה-API לאימות כתובת מספק כמה אותות כדי להודיע לכם אם צריך לאשר כתובת.
1. רמת פירוט האימות
אפשר לקבל validationGranularity של ROUTE ומעלה, אבל PREMISE או SUBPREMISE הם אות חזק יותר למסירה.
2. אותות אחרים
כשאתם מחליטים לאמת את הכתובת מול הלקוח, אנחנו מקבלים בתוצאה גם את הפרטים הבאים כדי לקבוע אילו רכיבים צריך לבדוק:
| נתונים משוערים | כשהשדה hasInferredComponents הוא true, אפשר לדעת שה-API מילא פרטים שהתקבלו מרכיבי כתובת אחרים.
|
|---|---|
| הנתונים שהוחלפו | כשהשדה hasReplacedComponents הוא true, ה-API החליף את הנתונים שהוזנו בנתונים שהוא קבע שהכתובת תקינה.
|
3. אותות של כתובת בארה"ב
שדות מסוימים שרלוונטיים רק לכתובות בארה"ב מציינים שהלוגיקה שלכם צריכה לאשר את הפרטים מול הלקוח. אחד מהתנאים הבאים מתקיימים:
dpvConfirmation
|
S
לפרטים על |
|---|---|
| תגובה לבקשה | מכיל את השדה missingComponentType עם הערך subpremise.
|
אישור כתובת
מאשרים כתובת אם מתקבלת החלטה ברמת ודאות גבוהה שהכתובת ניתנת למסירה ואפשר להשתמש בה ללא אינטראקציה נוספת של הלקוח בתהליך במורד הזרם.
אישור האותות
ה-API לאימות כתובת מספק כמה אותות כדי להודיע לכם אם צריך לאשר כתובת.
1. רמת פירוט האימות
הערך validationGranularity של PREMISE ומעלה קביל, אבל במקרים מסוימים, הערך ROUTE עדיין מציין כתובת למשלוח.
2. אותות אחרים
החלטה לגבי כתובת באיכות גבוהה צריכה לכלול גם את הפרטים הבאים:
- לא הוחלפו נתונים. במקרה הזה,
hasReplacedComponents: FALSE. - לא נגזרו רכיבים. במקרה הזה,
hasInferredComponents: FALSE.
3. אותות של כתובת בארה"ב
חלק מהשדות שרלוונטיים רק לכתובות בארה"ב מציינים כתובת באיכות גבוהה שאפשר לשלוח אליה. לכתובת קבילה בארה"ב, צריך להופיע הפרטים הבאים:
dpvConfirmation
|
Y
לפרטים על |
|---|