תחילת העבודה עם שיתוף חבילת גלישה

הסברים על המונחים

  • ‫GTAF: פונקציית אפליקציית התנועה של Google. שירות של Google שמטמיע את Data Plan Sharing API ופועל מול DPAs בשם אפליקציות Google. אפליקציות של Google יכולות לשלוח שאילתות ל-GTAF כדי לקבל מידע על תוכנית הנתונים של המשתמש. לחלופין, אם אפליקציות Google נרשמות ב-GTAF, ‏ GTAF יכול לשלוח עדכונים לגבי תוכנית הנתונים של המשתמש.
  • ‫MSISDN: מספר ספרייה בינלאומי של מנוי לתחנה ניידת, מספר שמזהה באופן ייחודי מינוי ברשת סלולרית. ידוע גם כמספר טלפון.
  • נקודת קצה של CPID: שירות שמיושם על ידי מפעילי רשתות סלולריות ומייצר מזהה של תוכנית סלולרית (CPID) שאפשר להשתמש בו כדי לחפש את פרטי חבילת הגלישה של המשתמש. מזהה CPID מאפשר לאפליקציה לשלוח שאילתה לגבי פרטים של חבילת גלישה של משתמש בלי לגשת למספר ה-MSISDN של המשתמש. בהמשך מפורט התהליך ליצירת מזהי CPID.
  • מפתח משתמש: מפתח משתמש הוא מחרוזת שאפשר להשתמש בה כדי לזהות את תוכנית הנתונים של המשתמש. יכול להיות שזה יהיה ה-CPID או ה-MSISDN של אפליקציות שיש להן גישה ל-MSISDN.
  • ‫DPA: סוכן תוכנית נתונים, שירות שמיושם על ידי מפעילי רשתות סלולריות שמשתף עם GTAF מידע על תוכנית הנתונים של המשתמש. ה-DPA יכול לשתף מידע עם GTAF באמצעות שילוב של שליחת נתונים באמצעות Google Mobile Data Plan Sharing API והטמעה של Data Plan Agent API. אפשר גם להשתמש ב-DPA כנקודת הקצה של CPID.
  • ‫UE: ציוד משתמש, מכשיר שבו המשתמש משתמש.

שפת הדרישות

מילות המפתח MUST,‏ MUST NOT,‏ REQUIRED,‏ SHALL,‏ SHALL NOT,‏ SHOULD,‏ SHOULD NOT,‏ RECOMMENDED,‏ MAY ו-OPTIONAL במדריכים האלה מפורשות כמו שמתואר ב-RFC 2119.

שיתוף חבילת גלישה

באופן כללי, שיתוף חבילת הגלישה מורכב משלושה חלקים:

  1. מנגנון ליצירה ולעדכון של מזהה תוכנית סלולרית (CPID) שאפשר להשתמש בו כמפתח משתמש. אפליקציות שיש להן גישה ל-MSISDN יכולות להשתמש בו כמפתח משתמש.
  2. ‫Google Mobile Data Plan Sharing API שמאפשר ל-DPA לשלוח ל-Google מידע על חבילת הגלישה של המשתמש. לדוגמה, אם ה-DPA רוצה לשלוח למשתמש הודעה על מבצע, הוא יכול לשלוח הודעה ל-GTAF, שבתורו ישלח הודעה למשתמש.
  3. ‫Data Plan Agent API שהוטמע על ידי ה-DPA, שמאפשר ל-GTAF לשלוח שאילתות ל-DPA כדי לקבל מידע על תוכנית הנתונים של המשתמש. לדוגמה, אם אפליקציה רוצה להציג למשתמש את היתרה הנוכחית בחבילת הגלישה, היא יכולה לשלוח שאילתה ל-GTAF, שבתורה שולחת שאילתה ל-DPA.

בהמשך הדף מוסבר על המינוח שקשור לתוכניות נתונים, ואיך אפשר ליצור CPID. בהמשך מפורטים Google Mobile Data Plan Sharing API ו-Data Plan Agent API.

הסברים על המונחים בחבילת גלישה

הסכימה של planStatus שמוגדרת ב-API צריכה להיות מסוגלת לייצג תוכניות נתונים שמפעילים מציעים למשתמשים. ה-API תומך בהגדרת תוכניות נתונים שבהן המשתמשים מחויבים בתעריף שונה על כל התנועה למערך מסוים של כתובות URL (למשל, כל התנועה אל ‎ *.acmefake.com מחויבת בתעריף שונה). בנוסף, ה-API תומך בתוכניות נתונים שמציעות תעריפים שונים לסוגים מסוימים של פעולות באפליקציה. אנחנו קוראים לתוכניות האלה תוכניות נתונים של אפליקציות משנה. דוגמה לתוכנית נתונים של אפליקציית משנה היא הצעה של גלישה בסרטונים בחינם (כלומר, ללא תעריף), בעוד שצפייה בסרטונים בתוך האפליקציה גורעת נתונים מיתרת הנתונים של המנוי. אפליקציית הסרטונים חייבת להיות מסוגלת לקבל את המידע הזה כשמתבצעת שאילתה לגבי פרטי חבילת הגלישה.

במאמר הזה נציג כמה מונחים שקשורים לחבילות נתונים. באיור 1 מוצגות דוגמאות לחבילות נתונים שמייצגות את המושגים שאנחנו רוצים להציג.

חבילת גלישה: חבילת שירותים לנייד ברמה העליונה שמנוי רוכש. היא יכולה להיות פשוטה כמו 'חבילת גלישה של 10GB ל-30 יום', או מורכבת יותר ולהיות מוגדרת כקבוצה של רכיבים, שנקראים גם מודולים. חבילת גלישה כוללת:

  • שם תוכנית הגלישה, למשל ACME Red.
  • מזהה תוכנית הנתונים, שמשמש להתייחסות לתוכנית, למשל במהלך רכישות.
  • זמן התפוגה, שבו יפוג התוקף של חבילת הגלישה.
  • קטגוריית המינוי, אם המינוי הוא בתשלום מראש או בתשלום לאחר השימוש.

מודול תוכנית: רכיב של תוכנית נתונים. מודול תוכנית כולל:

  • שם המודול, למשל 'ערבי צפייה בסרטונים בחינם'.
  • הקצב המקסימלי, רוחב הפס שהמודול הזה מציע למשתמש.
  • חלונות זמן גמישים, חלונות זמן שבמהלכם אפשר להציע הנחה למשתמש.

  • קטגוריית התנועה של מודול התוכנית (PMTC), תיאור של תנועת הנתונים שהמודול חל עליה. ה-PMTC יכול להיות כללי כמו *כל תנועת האינטרנט *או ספציפי כמו תנועה שנוצרת או נצרכת על ידי אפליקציה אחת או יותר, אתרים או אפילו מסלולי משתמשים בתוך אפליקציה אחת. דוגמאות לסוג האחרון הן 'מוזיקה ללא הגבלה', 'חבילת נתונים של 100MB לסרטונים (VDP)', 'נתונים ללא הגבלה למשחקים' ו'גלישה בסרטונים ללא הגבלה'. כדי להקל על הגדרת PMTCs, הגדרנו את ה-PMTCs הבאים: ‏GENERIC, VIDEO, VIDEO_BROWSING, VIDEO_OFFLINE1, MUSIC, GAMING, SOCIAL, MESSAGING ו-PMTC_UNSPECIFIED.

  • מגבלת נפח נתונים או מגבלת זמן: אחרי ההפעלה, תוקף מודול התוכנית פג כשמגיעים למגבלת נפח הנתונים או למגבלת הזמן (במקרה של תוכניות מבוססות זמן, למשל, חריגה ממגבלת הזמן של 600 דקות גישה לאינטרנט במהלך 7 הימים הבאים). באיור 1 שלמטה, מנוי יכול לקנות מודול תוכנית, כחלק מ-ACME Blue, שמספק 1GB של תנועת משתמשים כללית שצריך להשתמש בה תוך שבוע מההפעלה לפני שהיא פגה.

Data Plan API Sample Plan

איור 1. תוכניות גלישה לדוגמה.

יצירת 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 כדי להגדיל את הזמינות. 1. רשימת קידומות ה-IP שבבעלות המפעיל, וקוד המדינה לנייד (MCC) וקוד הרשת לנייד (MNC) שהמפעיל רוצה למפות לכתובות ה-CPID_URL שסופקו. אם המפעיל משתמש ב-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 שניות. ‫GTAF יקודד את ה-CPID בהתאם ל-RFC2396 בשיחות הבאות אל ה-DPA.

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

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

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

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

הדרך המומלצת ליצירת 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 הוא שלא צריך מסד נתונים של מספרי CPID ו-MSISDN תקינים בנקודת הקצה של ה-DPA וה-CPID.

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

דרישות אבטחה

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

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

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

הערות

  1. ה-PMTC ‏VIDEO_OFFLINE מציין שהתוכנית מתאימה רק לצפייה אופליין (לדוגמה, איכות חוויית צפייה בסטרימינג נמוכה מאוד). הוא לא תלוי בחלון FlexTime. ↩