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

แรงจูงใจ

ดังที่ได้กล่าวไว้ในภาพรวม DPA ต้องใช้การผสมผสานระหว่าง 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 ไม่รองรับภาษาที่ผู้ใช้ขอ 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

รูปที่ 4 ขั้นตอนการโทรเพื่อขอและรับข้อมูลแพ็กเกจอินเทอร์เน็ตของผู้ใช้

รูปที่ 4 แสดงโฟลว์การเรียกที่เชื่อมโยงกับไคลเอ็นต์ที่สอบถามเกี่ยวกับ สถานะแพ็กเกจอินเทอร์เน็ตของผู้ใช้และข้อมูลแพ็กเกจอินเทอร์เน็ตอื่นๆ ลำดับการโทรนี้ ใช้ร่วมกันสำหรับการเรียก API ที่ไคลเอ็นต์ทริกเกอร์ใน UE

1. ไคลเอ็นต์จะขอสถานะแพ็กเกจอินเทอร์เน็ตและ/หรือข้อมูลอื่นๆ โดยการเรียกใช้ Google API แบบส่วนตัว ไคลเอ็นต์จะรวมคีย์ผู้ใช้ในคำขอไปยัง GTAF
2. GTAF ใช้คีย์ผู้ใช้และตัวระบุไคลเอ็นต์เพื่อค้นหา DPA ของผู้ให้บริการ ตัวระบุไคลเอ็นต์ที่รองรับคือ mobiledataplan และ youtube เมื่อ DPA ได้รับการเรียกใช้ที่มีตัวระบุไคลเอ็นต์เหล่านี้ DPA จะต้อง ตอบกลับด้วยข้อมูลแพ็กเกจที่ไคลเอ็นต์ใช้ได้
3. GTAF จะส่งคืนข้อมูลที่ขอไปยังไคลเอ็นต์และแคชข้อมูลแผนโดย GTAF จนกว่าจะถึงเวลาหมดอายุที่ระบุโดย DPA

ขั้นตอนที่ 1 และ 3 ในรูปที่ 4 เป็น Google API ส่วนตัว จึงไม่มี คำอธิบายเพิ่มเติม ขั้นตอนที่ 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 OK พร้อมเนื้อหาการตอบกลับที่แสดงถึง 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 Services ทั้งนี้เพื่อให้ผู้ใช้บริการ Google Play ได้รับประสบการณ์การใช้งานที่ดี

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

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

การซื้อแพ็กเกจอินเทอร์เน็ต

API แผนการซื้อจะกำหนดวิธีที่ GTAF ซื้อแพ็กเกจผ่าน DPA GTAF เริ่มธุรกรรมเพื่อซื้อแพ็กเกจอินเทอร์เน็ต 1 แพ็กเกจให้กับ 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 จะถือว่าแพ็กเกจได้รับการเปิดใช้งานแล้ว

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

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