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

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

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

אימות

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

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

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

אם הארגון להגנה על מידע (DPA) אינו תומך בשפה שהמשתמש ביקש, הוא יכול להשתמש בשפת ברירת מחדל ולהשתמש בשדה LanguageCode כדי לציין את הבחירה שלו.

תיאור API

ב-GTAF נעשה שימוש במפתח משתמש, שמזהה מנוי למפעיל, בתגובה לשאילתות DPA של האופרטור. כש-GTAF שולח שאילתה לגבי הרשות להגנה על מידע (DPA) מטעם אפליקציות עם גישה ל-MSISSDN, ייתכן ש-MATAF ישתמש ב-MSISSDN. ברמה גבוהה, ה-API של תוכנית הנתונים המוצעים מורכב מהרכיבים הבאים:

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

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

אינטראקציה עם GTAF-DPA

איור 4. אפשר להתקשר ולקבל בקשות לתוכניות נתוני משתמשים.

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

1. הלקוח מבקש סטטוס של חבילת נתונים ו/או מידע אחר על ידי קריאה ל-Google API פרטי. הלקוח כולל את מפתח המשתמש בבקשה אל GTAF.
2. GTAF משתמש במפתח משתמש ובמזהה לקוח כדי להריץ שאילתה ב-DPA של האופרטור. מזהי הלקוחות הנתמכים הם 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 פונה אליו בשם DPA מזוהה באמצעות CLIENT_ID. בהתאם להסכם שבין הלקוח והמפעיל של Google, ה-DPA יכול להתאים אישית את התגובה ל-GTAF. אם התגובה מוצלחת, הרשות להגנה על מידע (DPA) חייבת להחזיר HTTP 200 סבירה עם גוף תגובה שמייצג PlanStatus. אם מדובר בשגיאות, אפשר לעיין בקטע מקרי שגיאה.

{
  "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)כדי ליצור מודל למקרה שבו מודול של התוכנית משותף בין אפליקציות מרובות (למשל 500 MB למשחק ולמוזיקה). ה-PMTC הבאים מוגדרים מראש: 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 פונה אליו בשם DPA מזוהה באמצעות CLIENT_ID. בהתאם להסכם שבין הלקוח והמפעיל של Google, ה-DPA יכול להתאים אישית את התגובה ל-GTAF. הפרמטר האופציונלי להקשר הוא ההקשר שבו הבקשה נשלחת. בדרך כלל זוהי מחרוזת שהאפליקציה מעבירה לאופרטור דרך GTAF.

אם הצלחה, DPA חייב להחזיר HTTP 200 סביר עם גוף תגובה שמייצג 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 Services. זאת כדי להבטיח חוויית משתמש טובה למשתמשים ב-Google Play Services.

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

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

רכישת נתונים

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

בקשת עסקה

כאשר היא מקבלת בקשה מלקוח, 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 רק עבור עסקה שבוצעה בהצלחה או עסקה שבוצעה בתור. אם יש שגיאות, כדאי לעיין בקטע תרחישים לדוגמה. אם העסקה התבצעה בתור, ה-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 SHELA יקבל את ההנחה שהתוכנית הופעלה.

רישום CPID

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

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

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

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

ה-API הזה רלוונטי רק למפעילים שתומכים במודול של חבילת הגלישה בחבילת הגלישה של Google Play. כדי לשלוח התראות בצורה מהימנה למשתמש, ה-DPA MAY מאחסן את ה-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 הזה. אם הרשות להגנה על מידע (DPA) בחרה להטמיע את ה-API להסכמה, המשתמש חייב לשמור את סטטוס ההסכמה העדכני ביותר לכל משתמש. במאמר בחירה של CPID מוסבר איך להשתמש בפרטי סטטוס ההסכמה.

אם הצלחה, DPA חייב להחזיר HTTP 200 סביר עם גוף תגובה ריק. למקרים של שגיאות, כדאי לעיין בתרחישים של שגיאה.