API ตัวแทนแพ็กเกจข้อมูล

แรงจูงใจ

ดังที่ได้กล่าวไว้ในภาพรวม ว่า DPA ต้องนํา API การแชร์แพ็กเกจอินเทอร์เน็ตมือถือของ Google ร่วมกับ Agent ของ Data Plan ออก ทั้งนี้ขึ้นอยู่กับกรณีการใช้งานที่โอเปอเรเตอร์ต้องการรองรับ เอกสารนี้อธิบาย Data Plan Agent API ที่ Google จะใช้เพื่อระบุแพ็กเกจอินเทอร์เน็ตมือถือของผู้ใช้ ดึงข้อมูลเกี่ยวกับแพ็กเกจเหล่านี้ และซื้อแพ็กเกจอินเทอร์เน็ต

การตรวจสอบสิทธิ์

ก่อนที่ GTAF จะโทรได้ DPA จะต้องตรวจสอบสิทธิ์ GTAF เราจะตรวจสอบความถูกต้องของใบรับรอง SSL ของ DPA ซึ่งเป็นส่วนหนึ่งของกระบวนการเริ่มต้นใช้งาน ปัจจุบันเรากําหนดให้ใช้ OAuth2 สําหรับการตรวจสอบสิทธิ์ร่วมกัน โปรดดูรายละเอียดเกี่ยวกับวิธีที่ GTAF ตรวจสอบสิทธิ์ตัวเองกับ DPA ใน Data Agent Agent Authentication

การก้าวสู่ระดับสากล

คําขอ GTAF ที่ส่งไปยัง DPA จะมีส่วนหัว Allow-Language ซึ่งระบุภาษาที่สตริงที่ผู้ใช้อ่านได้ (เช่น คําอธิบายแผน) นอกจากนี้ การตอบสนองของ DPA (PlanStatus, PlanOffers) จะรวมช่อง languageCode ที่จําเป็นซึ่งมีค่าเป็นรหัสภาษา BCP-47 (เช่น "en-US") ของคําตอบ

หาก DPA ไม่สนับสนุนภาษาที่ผู้ใช้ขอ จะใช้ภาษาเริ่มต้นและใช้ช่อง LanguageCode ในการระบุตัวเลือกได้

คําอธิบาย API

GTAF ใช้คีย์ผู้ใช้ ซึ่งจะระบุผู้สมัครใช้บริการให้กับโอเปอเรเตอร์เมื่อดู DPA ของผู้ให้บริการ เมื่อ GTAF ค้นหา DPA ในนามของแอปพลิเคชันที่มีสิทธิ์เข้าถึง MSISDN แล้ว GTAF MAY จะใช้ MSISDN API ของ Data Plan Agent ในระดับสูงจะประกอบด้วยคอมโพเนนต์ต่อไปนี้

1. กลไกการค้นหาสถานะแพ็กเกจข้อมูลผู้ใช้
2. กลไกในการค้นหา DPA สําหรับข้อเสนอของแพ็กเกจอินเทอร์เน็ตสําหรับผู้ใช้
3. กลไกการเปลี่ยนแปลงแผนข้อมูลของผู้ใช้ (เช่น ซื้อแผนใหม่)
4. กลไกในการแชร์ CPID ที่ใช้เพื่อส่งการแจ้งเตือนให้ผู้ใช้ได้
5. กลไกแชร์ตัวเลือกของผู้ใช้ว่าจะลงชื่อสมัครใช้บริการของเราหรือไม่

ส่วนที่เหลือของเอกสารนี้จะอธิบายเกี่ยวกับแต่ละองค์ประกอบ API เหล่านี้ การสื่อสารทั้งหมดต้องเกิดขึ้นผ่าน HTTPS (พร้อมใบรับรอง DPA SSL ที่ถูกต้อง) เว้นแต่จะระบุไว้เป็นอื่นอย่างชัดแจ้ง โอเปอเรเตอร์อาจเลือกใช้งานคอมโพเนนต์ 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 DPA ปรับแต่งการตอบสนองของ GTAF ได้โดยขึ้นอยู่กับข้อตกลงระหว่างไคลเอ็นต์ของ Google และโอเปอเรเตอร์ ในกรณีที่สําเร็จ 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 DPA ปรับแต่งการตอบสนองของ GTAF ได้โดยขึ้นอยู่กับข้อตกลงระหว่างไคลเอ็นต์ของ Google และโอเปอเรเตอร์ พารามิเตอร์บริบทที่ไม่บังคับ จะระบุบริบทของแอปพลิเคชันที่มีคําขอ ซึ่งโดยปกติจะเป็นสตริงที่แอปพลิเคชันส่งผ่านไปยังโอเปอเรเตอร์ผ่าน 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 เนื่องจาก UI หรือข้อจํากัดอื่นๆ และการตอบกลับมี y > x แพ็กเกจจะแสดงเฉพาะ x แพ็กเกจแรกเท่านั้น GTAF จะแชร์แพ็กเกจได้สูงสุด 50 แพ็กเกจหากแอปพลิเคชันที่ใช้ค้นหาข้อเสนอเป็นโมดูลแพ็กเกจอินเทอร์เน็ตมือถือซึ่งเป็นส่วนหนึ่งของบริการ Google Play ทั้งนี้เพื่อให้มั่นใจว่าผู้ใช้จะได้รับประสบการณ์ที่ดีจากบริการ Google Play

ข้อเสนอการขายต่อยอดมีตัวกรองแท็กเป็นพารามิเตอร์ที่ไม่บังคับซึ่งเป็นอาร์เรย์ของแท็กที่แนบมากับแต่ละแผน ตัวกรองเหล่านี้ทั้งหมดควรจับคู่กับแท็กซึ่งเป็นออบเจ็กต์ภายในตัวกรอง Filter เป็นออบเจ็กต์ระดับแรกที่มี tuple<tag, displaytextgclidquot;"> Filter เป็นรายการตัวกรองแบบรวมซึ่งจะแสดงผลใน UI ผู้ใช้สามารถกรองได้โดยคลิก DisplayText แท็กที่เกี่ยวข้องกับ DisplayText จะใช้เพื่อกรองข้อเสนอ</tag,>

โปรดทราบว่าโอเปอเรเตอร์ต้องมีกลไกในการดําเนินการตามคําขอซื้อสําหรับข้อเสนอทั้งหมดแบบขยายเวลาต่อผู้ใช้ กลไกที่จะเรียกเก็บเงินจากผู้ใช้สําหรับการซื้อทั้งหมดสามารถสื่อสารกับ GTAF ได้โดยใช้ตัวเลือก formOfPayment ในการตอบกลับ

การซื้อข้อมูล

API แพ็กเกจการซื้อจะกําหนดวิธีที่ GTAF ซื้อแพ็กเกจผ่าน DPA ได้ GTAF จะเริ่มทําธุรกรรมเพื่อซื้อแผนข้อมูลแผน 1 แผนต่อ DPA คําขอจะรวมถึงตัวระบุธุรกรรมที่ไม่ซ้ํากัน (transactionId) เพื่อติดตามคําขอและหลีกเลี่ยงการดําเนินการธุรกรรมที่ซ้ํากัน DPA ต้องตอบกลับด้วย ความสําเร็จ/ล้มเหลว

คําขอธุรกรรม

เมื่อ GTAF ได้รับคําขอจากไคลเอ็นต์ 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 SHALL จะสร้างการตอบกลับ 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 SHALL จะถือว่าแผนเปิดใช้งานแล้ว

ลงทะเบียน 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 และ CLIENT_ID เพียงประเภทเดียวที่รองรับคือ mobiledataplan เนื้อหาของคําขอคืออินสแตนซ์ของ RegisterCpidRequest และมีเวลาที่ใช้ CPID เพื่อส่งการแจ้งเตือนในรูปแบบต่อไปนี้ไม่ได้

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

API นี้เกี่ยวข้องเฉพาะสําหรับโอเปอเรเตอร์ที่ต้องการรองรับโมดูล แพ็กเกจอินเทอร์เน็ตมือถือใน Google Play Services เพื่อส่งการแจ้งเตือนให้ผู้ใช้อย่างเชื่อถือได้ 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 ความยินยอม DPA จะต้องเก็บสถานะความยินยอมล่าสุดไว้ให้ผู้ใช้แต่ละราย โปรดอ่านการเลือก CPID เพื่อดูคําแนะนําเกี่ยวกับวิธีใช้ข้อมูลสถานะความยินยอม

ในกรณีที่สําเร็จ DPA จะต้องส่งคืน HTTP 200 OK พร้อมด้วยเนื้อหาการตอบกลับที่ว่างเปล่า โปรดดูกรณีข้อผิดพลาดสําหรับการตอบกลับที่คาดหวังในกรณีที่เกิดข้อผิดพลาด