הגדרת CPID

כדי לזהות מנוי במהלך תקשורת עם ה-DPA, כלי GTAF משתמש במפתח משתמש. אפליקציות שיש להן גישה למספר ה-MSISDN של המשתמש יכולות להשתמש בו כ-user_key. מצד שני, אפליקציות שאין להן גישה למספר MSISDN צריכות ליצור מזהה של תוכנית סלולרית (CPID) בלי לגלות את מספר ה-MSISDN של המשתמש. בקטעים הבאים מתואר המנגנון שיוצר CPID.

זרימת שיחות של CPID

איור 2: תרשים זרימת השיחות להקמת CPID.

1. אפליקציה של Google ב-UE משתמשת ב-API פנימי של Google כדי לאחזר את כתובת ה-URL של נקודת הקצה של ה-CPID מ-GTAF. המפעיל מזוהה באמצעות כתובת ה-IP הציבורית של הלקוח וקוד המדינה (MCC) + קוד הרשת (MNC) של כרטיס ה-SIM הפעיל. במקרה של MVNO, ‏ Google תשתמש ב-SPN וב-GID1 כדי לקבוע את ה-MVNO
2. הלקוח שולח בקשת HTTP GET לנקודת הקצה של ה-CPID. יכול להיות שהמפעיל יתמוך בשליחת הבקשה באמצעות HTTPS.
3. יכול להיות שהמפעיל ישתמש בפונקציית בדיקת החבילות העמוקה שלו כדי לזהות את הבקשה ולהוסיף את מספר הטלפון של המשתמש לבקשה ככותרת HTTP.
4. נקודת הקצה של ה-CPID מקבלת את הבקשה, יוצרת את ה-CPID ומחזירה אותו למכשיר עם זמן החיים (TTL) שמציין כמה זמן המכשיר יכול להשתמש ב-CPID הזה.

המפעיל יכול גם להשתמש בכתובות IP במקום בשמות דומיין בכתובת ה-URL של נקודת הקצה של CPID אם הוא מעדיף זאת. יכול להיות שכתובות ה-IP יהיו במרחב כתובות פרטי, אבל לקוחות Google צריכים להיות מסוגלים להגיע אליהן בתוך הרשת של המפעיל.

הספק יספק ל-Google את הפרטים הבאים כחלק מתהליך ההצטרפות:

1. כתובת ה-URL של ה-CPID שאליה האפליקציות יפנו כדי לקבל CPID. חובה להזין CPID_URL אחד אבל המפעיל יכול לספק כמה כתובות URL כדי להגדיל את הזמינות.
2. רשימת קידומות ה-IP שבבעלות המפעיל, וקוד המדינה שבה נמצא הנייד (MCC) וקוד הרשת הסלולרית (MNC) שהמפעיל רוצה למפות לכתובות ה-URL של ה-CPID שסופקו. אם המפעיל משתמש ב-SPN או ב-GID1 כדי להבחין בין MVNO ברשת שלו, המפעיל צריך לספק גם את המידע הזה. ‫Google תשתמש במידע הזה כדי להתאים לקוחות לנקודות הקצה המתאימות של CPID, כמו שמוצג בשלב 1 באיור 2.

הפורמט של הבקשה הוא: GET CPID_URL מסיבות שקשורות לגרסאות קודמות, נקודת הקצה של CPID צריכה לתמוך בבקשה כמו הבקשה הבאה:

GET CPID_URL?app={app_id}

נקודת הקצה של ה-CPID יכולה להתעלם מפרמטר כתובת ה-URL‏ {app_id} כשיוצרים את ה-CPID. אבל היא חייבת להיות מסוגלת לטפל בבקשה שמכילה את הפרמטר.

הבקשה לנקודת הקצה של CPID עשויה לכלול את הכותרת Accept-Language. אם הכותרת כלולה, מחרוזות קריאות לאדם בעדכונים שספק ה-DPA שולח באמצעות Mobile Data Plan Sharing API חייבות להשתמש בהגדרות שסופקו בבקשת ה-CPID.

בכל פעם שהלקוח מנפיק בקשת GET CPID_URL, הוא חייב לקבל CPID חדש. אם יצירת ה-CPID הצליחה, נקודת הקצה של ה-CPID חייבת להחזיר תגובה מסוג 200 OK. גוף התשובה חייב להכיל מופע של CPIDResponse.

{
    "cpid": "<CPID_string>",
    "ttlSeconds": 2592000
}

ה-CPID שמוחזר חייב להיות תקף למשך ttlSeconds שניות, גם אם מנוי ביקש אחר כך CPID אחרים. ‫Google ממליצה להשתמש בערך TTL של 30 ימים, אבל לא פחות מ-14 ימים, כדי להשיג את חוויית המשתמש הטובה ביותר. ‫GTAF יקודד את ה-CPID בהתאם ל-RFC2396 בשיחות הבאות אל ה-DPA.

יצירת מזהה קמפיין

הדרך המומלצת ליצירת CPID בנקודת הקצה של CPID היא:

CPID_string = Base64(AES(MSISDN + TimeStamp + language, secret))

נקודת הקצה של ה-CPID משרשרת את ה-MSISDN, את השפה שנשלחת על ידי הלקוח בכותרת Accept-Language, ואת חותמת הזמן ברזולוציה גבוהה, ומצפינה אותם באמצעות AES באמצעות מפתח secret. חותמת הזמן צריכה להתאים למועד התפוגה של ה-CPID. הפלט המוצפן הוא בקידוד Base64. בנוסף, כשמשתמשים ב-CPID בכתובת URL, חובה לקודד את כתובת ה-URL כדי לטפל בתווים מיוחדים (/+=) שמשמשים ב-Base64. במיוחד כש-GTAF שולח קריאה ל-DPA או כש-DPA שולח קריאה ל-Mobile Data Plan Sharing API, ה-CPID חייב להיות מקודד בכתובת ה-URL.

בהתאם למצב של מפעיל מסוים, יכול להיות שיהיה קשה להטמיע את נקודת הקצה של CPID. אתגר ספציפי שנתקלים בו לעיתים קרובות הוא קבלת גישה ל-MSISDN בנקודת הקצה (endpoint) של CPID. נשמח לשתף את הלקחים שלמדנו בתהליך צירוף מפעילים. אם נתקלת בבעיות, אפשר לפנות אלינו.

אחסון CPID

לא צריך לאחסן במסד נתונים את מזהה ה-CPID שנוצר באמצעות המנגנון שמתואר למעלה. אפשר להפיק מה-CPID מידע רלוונטי לטיפול בשיחות עם ה-DPA.

1. כש-DPA מקבל שיחה מ-GTAF לגבי סטטוס התוכנית או מבצעים, אפשר לגזור את מספר ה-MSISDN על ידי פענוח ה-CPID וחילוץ מספר ה-MSISDN.
2. אפשר לפענח את מזהה ה-CPID כדי לחלץ את חותמת הזמן של התפוגה.

זמינות ודרישות קיבולת

אם הלקוחות לא יכולים לאחזר מזהה CPID, הם לא יכולים לגשת למידע כלשהו מממשק ה-API של תוכנית נתונים לנייד. לכן, על המפעיל לנקוט את האמצעים הנדרשים כדי להבטיח את הזמינות של נקודת הקצה של CPID. האמצעים האלה כוללים כמה מופעים של נקודת הקצה CPID ופונקציות DPI, ויתירות פיזית, באתר וברשת עבור שתי הפונקציות, וכן לוודא שיש מספיק משאבי מערכת ויכולת. בנוסף, לנקודת הקצה של ה-CPID ולפונקציית ה-DPI שמזריקה את הכותרת צריכה להיות קיבולת מספקת כדי לטפל בעומס של כל לקוחות Google שמבקשים CPID. בנקודת הקצה של CPID אפשר להשתמש בערכים גדולים יותר בשדה ttlSeconds כדי להקטין את התדירות שבה נוצרים מזהי CPID.

סוגי שגיאות

אם מתרחשת שגיאה, נקודת הקצה של ה-CPID חייבת להחזיר שגיאת HTTP עם גוף תגובה שחייב להכיל מופע של ErrorResponse. הודעת שגיאה טובה צריכה לכלול מידע שיכול לעזור בניפוי הבאגים שגורמים לשגיאה. לדוגמה, במקרה של CPID שתוקפו פג, צירוף של פרטים כמו יצירת ה-CPID ושעת התפוגה שלו יעזרו לנו לוודא שנקודת הקצה של ה-CPID פועלת כמתוכנן.

{
    "errorMessage": "<error message>",
    "cause": "USER_ROAMING"
}

נקודת הקצה (endpoint) של CPID חייבת להחזיר את הערכים הבאים בהתאם לתרחיש:

1. אם מתקבלת בקשת CPID לגבי משתמש שלא שייך לרשת של הספק (לדוגמה, משתמש ששייך לספק אחר אבל נמצא בנדידה ברשת שמשרתת את נקודת הקצה הזו של CPID) או שלא הביע הסכמה לשיתוף פרטי תוכנית הנתונים עם Google, נקודת הקצה של CPID חייבת להחזיר קוד סטטוס HTTP‏ 403 עם USER_ROAMING, ‏ USER_OPT_OUT או INELIGIBLE_FOR_SERVICE כסיבה.
2. אם מתקבלת בקשת CPID עם מספר טלפון לא תקין, נקודת הקצה של CPID חייבת להחזיר HTTP 400 עם סיבת השגיאה INVALID_NUMBER.
3. אם הבקשה לנקודת הקצה של CPID היא בפורמט שגוי בכל דרך אחרת, נקודת הקצה של CPID חייבת להחזיר HTTP 400 עם ERROR_CAUSE_UNSPECIFIED כסיבה.
4. במקרים אחרים, כל קוד שגיאת HTTP תואם הוא קביל. בפרט, HTTP 500 היא סיבת שגיאה מתאימה לכל כשל פנימי בנקודת הקצה (endpoint) של CPID.