ממשק API של סוכן תוכנית הנתונים

למה בחרנו לעשות זאת?

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

אימות

לפני ש-GTAF יכול להתקשר, ה-DPA צריך לאמת את GTAF. כחלק מתהליך צירוף המפעיל, נבדוק את התוקף של אישור ה-SSL של DPA. נכון לעכשיו, אנחנו דורשים שימוש ב-OAuth2 לאימות הדדי. פרטים על האופן שבו GTAF מאמת את עצמו מול DPA מופיעים במאמר בנושא אימות של סוכן תוכנית נתונים.

אינטרנציונליזציה

בקשות GTAF אל ה-DPA כוללות כותרת Accept-Language שמציינת את השפה שבה צריכים להיות המחרוזות שניתנות לקריאה על ידי בני אדם (לדוגמה, תיאורי תוכניות). בנוסף, תשובות של DPA (‏PlanStatus,‏ PlanOffers) כוללות שדה חובה languageCode, שהערך שלו הוא קוד השפה BCP-47 (לדוגמה, ‫("en-US") של התגובה.

אם ה-DPA לא תומך בשפה שהמשתמש ביקש, הוא יכול להשתמש בשפת ברירת מחדל ולציין את הבחירה שלו בשדה languageCode.

תיאור ה-API

כש-GTAF שולח שאילתה ל-DPA של המפעיל, הוא משתמש במפתח משתמש שמזהה מנוי של המפעיל. כש-GTAF שולח שאילתה ל-DPA בשם אפליקציות שיש להן גישה ל-MSISDN, ‏ GTAF עשוי להשתמש ב-MSISDN. באופן כללי, ה-API של סוכן תוכנית הנתונים המוצע מורכב מהרכיבים הבאים:

1. מנגנון לשליחת שאילתה לגבי סטטוס תוכנית הנתונים של המשתמש.
2. מנגנון להפעלת שאילתות ב-DPA כדי לקבל מידע על חבילות נתונים למשתמש.
3. מנגנון לביצוע שינויים בתוכנית הנתונים של המשתמש (למשל, רכישת תוכנית חדשה).
4. מנגנון לשיתוף מזהי ה-CPID שאפשר להשתמש בהם כדי לשלוח התראות למשתמשים.
5. מנגנון לשיתוף הבחירות של המשתמשים לגבי הרשמה לשירות שלנו.

בהמשך המסמך מוסבר על כל אחד מרכיבי ה-API האלה. אלא אם צוין אחרת במפורש, כל התקשורת חייבת להתבצע באמצעות HTTPS (עם אישור SSL תקף של DPA). בהתאם לתכונות הספציפיות שנתמכות, יכול להיות שמפעיל יבחר להטמיע את כל רכיבי ה-API האלה או רק חלק מהם.

GTAF-DPA Interaction

איור 4. תרשים זרימת שיחה לבקשה ולקבלת מידע על תוכנית נתונים של משתמש.

איור 4 מציג את רצף הפעולות שקשורות לשאילתה של לקוח לגבי סטטוס חבילת הגלישה של המשתמש ופרטים נוספים על חבילת הגלישה. תרשים זרימת השיחות הזה משותף לקריאות ל-API שמופעלות על ידי הלקוח ב-UE.

1. הלקוח שולח בקשה לסטטוס של תוכנית הנתונים ו/או למידע אחר באמצעות קריאה לממשק Google API פרטי. הלקוח כולל את מפתח המשתמש בבקשה ל-GTAF.
2. כדי לשלוח שאילתה ל-DPA של המפעיל, GTAF משתמש במפתח המשתמש ובמזהה לקוח. מזהי הלקוח הנתמכים הם mobiledataplan ו-youtube. כש-DPA מקבל שיחה עם אחד ממזהי הלקוח האלה, הוא חייב להגיב עם פרטי התוכנית שהלקוח יכול להשתמש בהם.
3. ‫GTAF מחזיר את המידע המבוקש ללקוח, ומידע התוכנית נשמר במטמון של GTAF עד לתאריך התפוגה שצוין ב-DPA.

שלבים 1 ו-3 באיור 4 הם ממשקי API פרטיים של Google, ולכן לא מתואר מידע נוסף לגביהם. שלב 2 הוא API ציבורי שמתואר בהמשך. ה-DPA חייב להתייחס לכותרת ה-HTTP‏ Cache-Control: no-cache כשמגישים את הקריאות האלה ל-API מ-GTAF.

שליחת שאילתות לגבי הסטטוס של תוכנית נתונים

כדי לקבל את סטטוס התוכנית, GTAF שולח את בקשת ה-HTTP הבאה:

GET DPA_URL/{userKey}/planStatus?key_type={CPID,MSISDN}&client_id=CLIENT_ID

הלקוח שבשמו GTAF יוצר קשר עם רשות הגנת המידע מזוהה באמצעות CLIENT_ID. בהתאם להסכם בין לקוח Google לבין המפעיל, רשות ה-DPA יכולה להתאים אישית את התגובה ל-GTAF. במקרה של הצלחה, ה-DPA חייב להחזיר HTTP 200 OK עם גוף תגובה שמייצג PlanStatus. בקטע Error Cases מוסבר מה צפוי לקרות במקרה של שגיאות.

{
  "plans": [{
    "planName": "ACME1",
    "planId": "1",
    "planCategory": "PREPAID",
    "expirationTime": "2017-01-29T01:00:03.14159Z", // req.
    "planModules": [{
      "moduleName": "Giga Plan", // req.
      "trafficCategories": ["GENERIC"],
      "expirationTime": "2017-01-29T01:00:03.14159Z", // req.
      "overUsagePolicy": "BLOCKED",
      "maxRateKbps": "1500",
      "description": "1GB for a month", // req.
      "coarseBalanceLevel": "HIGH_QUOTA"
    }]
  }],
  "languageCode": "en-US", // req.
  "expireTime": "2018-06-14T08:41:27-07:00", // req.
  "updateTime": "2018-06-07T07:41:22-07:00", // req.
  "title": "Prepaid Plan"
  "planInfoPerClient": {
    "youtube": {
      "rateLimitedStreaming": {
        "maxMediaRateKbps": 256
      }
    }
  }
}

בתוכניות שמשלמים עליהן בסוף התקופה, expirationTime חייב להיות תאריך החידוש של התוכנית (כלומר, התאריך שבו יתרת הנתונים מתעדכנת או נטענת מחדש).

כל מודול תוכנית עשוי להכיל כמה קטגוריות תנועה של מודול תוכנית (PMTCs)כדי ליצור מודל למקרה שבו מודול תוכנית משותף בין כמה אפליקציות (למשל, ‫500MB (למשחקים ולמוזיקה). הגדרנו מראש את המאפיינים הבאים של תנועת גולשים שניתן למדוד: GENERIC, VIDEO, VIDEO_BROWSING, VIDEO_OFFLINE, MUSIC, GAMING, SOCIAL and MESSAGING. מומלץ שמפעילים יפנו לצוותים שונים ב-Google כדי להגיע להסכמה לגבי קבוצת קטגוריות התנועה והסמנטיקה שלהן שרלוונטיות לאפליקציות שונות של Google.

שאילתות לגבי מבצעים של תוכניות

הכלי GTAF שולח את בקשת ה-HTTP הבאה כדי לקבל הצעות לתוכניות מהספק:

GET DPA_URL/{userKey}/planOffer?key_type={CPID,MSISDN}&client_id=CLIENT_ID&context={purchaseContext}

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

אם הפעולה בוצעה ללא שגיאות, פלטפורמת ה-DPA חייבת להחזיר HTTP 200 OK עם גוף תגובה שמייצג PlanOffer. במאמר תרחישי שגיאה מוסבר מה צפוי לקרות במקרה של שגיאות.

{
    "offers": [
      {
        "planName": "ACME Red", // req.
        "planId": "turbulent1", // req.
        "planDescription": "Unlimited Videos for 30 days.", // req.
        "promoMessage": "Binge watch videos.",
        "languageCode": "en_US", // req.
        "overusagePolicy": "BLOCKED",
        "cost": { // req.
          "currencyCode": "INR",
          "units": "300",
          "nanos": 0
        },
        "duration": "2592000s",
        "offerContext": "YouTube",
        "trafficCategories": ["VIDEO"],
        "quotaBytes": "9223372036850",
        "filterTags": ["repurchase", "all"]
      }
    ],
    "filters" : [
      {
        "tag": "repurchase",
        "displayText": "REPURCHASE PLANS"
      },
      {
        "tag": "all",
        "displayText": "ALL PLANS"
      }
    ]
    "expireTime": "2019-03-04T00:06:07Z" // req.
}

הסדר של תוכניות הנתונים במערך offers עשוי לקבוע את הסדר שבו תוכניות הנתונים מוצגות למשתמשים. בנוסף, אם האפליקציה יכולה להציג רק x תוכניות בגלל מגבלות בממשק המשתמש או מגבלות אחרות, והתגובה מכילה רק y > x תוכניות, רק x התוכניות הראשונות יוצגו. ‫GTAF משתף עד 50 תוכניות אם האפליקציה שמבצעת שאילתה לגבי מבצעים היא מודול חבילת הגלישה לנייד, שהוא חלק משירותי Google Play. המטרה היא להבטיח חוויית משתמש טובה למשתמשים בשירותי Google Play.

למבצעים של שדרוג יש פרמטר אופציונלי filterTags שהוא מערך של תגים שמצורפים לכל התוכניות. כל התגים האלה צריכים להיות זהים לתג שהוא אובייקט בתוך Filter. ‫Filter הוא אובייקט ברמה הראשונה שמכיל tuple<tag, displaytext="">. ‏ Filter היא רשימה מאוחדת של מסננים שיוצגו בממשק המשתמש. המשתמש יכול לסנן בלחיצה על DisplayText. התג שמתאים ל-displayText משמש לסינון המבצעים.</tag,>

חשוב לציין שלמפעיל חייב להיות מנגנון למימוש בקשת רכישה של כל מבצע שמוצע למשתמש. אפשר להשתמש באפשרות formOfPayment בתשובה כדי לציין ל-GTAF את המנגנון שדרכו המשתמש יחויב על כל רכישה.

רכישת חבילת גלישה

ממשק ה-API של תוכנית הרכישה מגדיר איך GTAF יכול לרכוש תוכניות דרך ה-DPA. ‫GTAF יוזם את העסקה לרכישת חבילת גלישה אחת מ-DPA. הבקשה חייבת לכלול מזהה עסקה ייחודי (transactionId) כדי לעקוב אחרי בקשות ולמנוע ביצוע כפול של עסקאות. הרשות להגנה על מידע חייבת להגיב בתשובה של הצלחה או כישלון.

Transaction Request

אחרי ש-GTAF מקבל בקשה מלקוח, הוא שולח בקשת POST ל-DPA. כתובת ה-URL של הבקשה היא:

POST DPA_URL/{userKey}/purchasePlan?key_type={CPID,MSISDN}&client_id=CLIENT_ID

כאשר userKey הוא CPID או MSISDN. גוף הבקשה הוא מופע של TransactionRequest שכולל את השדות הבאים:

{
  "planId": string,         // Id of plan to be purchased. Copied from
                            // offers.planId field returned from a
                            // Upsell Offer request,
                            // if available. (req.).
  "transactionId": string,  // Unique request identifier (req.)
  "offerContext": string,   // Copied from from the
                            // offers.offerContext, if available.
                            // (opt.)
  "callbackUrl": string     // URL that the DPA can call back with response once
                            // it has handled the request.
}

תגובה לעסקה

ה-DPA יפיק תגובה מסוג 200-OK רק לעסקה שבוצעה בהצלחה או לעסקה שהוכנסה לתור. בקטע Error Cases מוסבר מה צפוי לקרות במקרה של שגיאות. במקרה של עסקה בתור, ה-DPA ימלא רק את סטטוס העסקה וישאיר את שאר השדות בתגובה ריקים. ה-DPA חייב להתקשר חזרה ל-GTAF עם תשובה אחרי שטרנזקציה שהוכנסה לתור טופלה. גוף התשובה הוא מופע של TransactionResponse שכולל את הפרטים הבאים:

{
  "transactionStatus": "SUCCESS",

  "purchase": {
    "planId": string,               // copied from request. (req.)
    "transactionId": string,        // copied from request. (req.)
    "transactionMessage": string,   // status message. (opt.)
    "confirmationCode": string,     // DPA-generated confirmation code
                                    // for successful transaction. (opt.)
    "planActivationTime" : string,  // Time when plan will be activated,
                                    // in timestamp format. (opt.)
  },

  // walletInfo is populated with the balance left in the user's account.
  "walletBalance": {
    "currencyCode": string,       // 3-letter currency code defined in ISO 4217.
    "units": string,              // Whole units of the currency amount.
    "nanos": number               // Number of nano units of the amount.
  }
}

אם הערך planActivationTime חסר, מערכת GTAF תניח שהתוכנית הופעלה.

רישום של CPID

כשלקוח שתומך בהתראות מקבל CPID חדש מנקודת הקצה של CPID, הוא רושם את ה-CPID ב-GTAF אם תנאי הלקוח מאפשרים ל-GTAF לעשות זאת. אם הלקוח רושם את ה-CPID ב-GTAF בהצלחה, אז GTAF ירשום את ה-CPID ב-DPA באמצעות קריאת ה-API הבאה:

POST DPA_URL/{userKey}/registerCpid?key_type={CPID,MSISDN}&client_id=CLIENT_ID

כאשר userKey הוא ה-CPID ומזהה הלקוח היחיד שנתמך הוא mobiledataplan. גוף הבקשה הוא מופע של RegisterCpidRequest והוא מכיל את השעה שאחריה אי אפשר להשתמש ב-CPID לשליחת התראות. הוא נראה כך:

{"staleTime": "2017-01-29T01:00:03.14159Z"}

ממשק ה-API הזה רלוונטי רק למפעילים שרוצים לתמוך במודול 'תוכנית נתונים לנייד' בשירותי Google Play. כדי לשלוח התראות למשתמש בצורה מהימנה, פלטפורמת ה-DPA עשויה לאחסן את מזהה ה-CPID האחרון שנרשם לכל משתמש. הוראות לשימוש ב-CPID הרשום לשליחת התראות מפורטות במאמר בנושא בחירת CPID.

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

הסכמה

יכול להיות ש-GTAF ישלח את הבקשה הבאה כדי להעביר את העדפת הסכמת המשתמשים אל הספק.

POST DPA_URL/{userKey}/consent?key_type={CPID,MSISDN}&client_id=CLIENT_ID

כאשר userKey הוא CPID או MSISDN. גוף הבקשה הוא מופע של SetConsentStatusRequest. אם הפעולה בוצעה ללא שגיאות, גוף התגובה יהיה ריק.

כל שיחה מ-GTAF אל DPA כפופה לתנאים ולהגבלות של לקוח Google שמבצע את השיחה. בהתאם לאפליקציות שה-DPA רוצה לתמוך בהן, המפעיל מחליט אם ה-DPA מטמיע את ה-API הזה. אם רשות הגנת הנתונים בוחרת להטמיע את Consent API, היא חייבת לשמור את סטטוס ההסכמה האחרון של כל משתמש. כאן אפשר לקרוא הנחיות לשימוש במידע על סטטוס ההסכמה.

אם הפעולה בוצעה ללא שגיאות, פלטפורמת ה-DPA חייבת להחזיר HTTP 200 OK עם גוף תגובה ריק. במאמר תרחישי שגיאה מוסבר מהי התגובה הצפויה במקרה של שגיאות.