API Berbagi Paket Data Seluler Google

Motivasi

Google Mobile Data Plan Sharing API memungkinkan operator mengirimkan informasi tentang paket data pengguna (diidentifikasi oleh kunci pengguna) ke GTAF. Di halaman ini, kami menguraikan mekanisme yang memungkinkan update ini dikirim ke GTAF dan dengan demikian ke aplikasi Google. Saat ini, API memungkinkan DPA mengirim status paket data ke GTAF untuk digunakan oleh klien Google.

Autentikasi

Semua permintaan Data Plan Sharing API ke GTAF harus diautentikasi menggunakan server OAuth2 Google Cloud. Permintaan harus diautentikasi sebagai akun layanan yang telah dimasukkan ke daftar yang diizinkan di ISP Portal untuk ASN yang diwakili oleh DPA. Lihat OAuth 2.0 Google Cloud untuk Akun Layanan untuk mengetahui dokumentasi tentang cara menggunakan OAuth dengan akun layanan Google Cloud.

Pembaruan Paket Data

Saat ini, Google Mobile Data Plan Sharing API memungkinkan operator membagikan info terbaru tentang paket data pengguna:

  • Status Paket Data: Merekam status paket data pengguna saat ini. Misalnya, jika pengguna kehabisan data, operator dapat mengirimkan update status paket data ke GTAF yang kemudian dapat digunakan oleh GTAF untuk mengirimkan notifikasi saldo rendah kepada pengguna.

Mengidentifikasi pengguna yang relevan

DPA memerlukan cara untuk menentukan data pengguna mana yang akan dikirim ke GTAF. GTAF berharap menerima info terbaru untuk pengguna berikut:

  1. CPID aktif: pengguna dengan CPID aktif. Hingga CPID yang telah dibuat oleh endpoint CPID valid, DPA HARUS mengirimkan pembaruan tentang paket data pengguna. Jika header Accept-Language ditetapkan pada saat pembuatan CPID, maka string yang dapat dibaca manusia dalam status paket data HARUS dalam bahasa tersebut.
  2. MSISDN terdaftar: untuk menayangkan aplikasi yang memiliki akses ke MSISDN, GTAF akan mendaftarkan MSISDN dengan DPA seperti yang dijelaskan di bagian pendaftaran MSISDN pada Data Plan Agent API. Setelah MSISDN terdaftar, DPA HARUS mengirimkan info terbaru tentang paket data pengguna hingga masa berlaku pendaftaran berakhir.

Deskripsi API

Membagikan Status Paket Data

Gambar 3. Interaksi GTAF-DPA saat DPA membagikan status paket data dengan GTAF.

Aplikasi dapat menerima informasi status paket data dengan dua cara:

  1. UE memanggil GTAF untuk mendapatkan informasi status paket data:
    1. DPA operator menggunakan Data Plan Sharing API untuk mengirimkan status paket data pengguna ke GTAF. GTAF menyimpan status paket dan kunci pengguna terkait.
    2. Aplikasi Google yang berjalan di UE meminta informasi status paket data menggunakan API internal Google. Aplikasi menyertakan kunci pengguna dalam permintaannya.
    3. Jika aplikasi dapat menggunakan status paket data yang di-cache, GTAF akan menggunakan kunci pengguna untuk mencari status paket data pengguna. Kemudian, GTAF akan menampilkan status ini ke UE.
  2. GTAF mengirimkan informasi status paket data ke UE:
    1. Jika relevan, status paket data yang diterima dari operator akan langsung dikirim ke UE.

Interaksi GTAF-DPA

DPA menggunakan POST HTTPS untuk membuat dan memperbarui entri status paket yang ada untuk pengguna yang akan digunakan oleh klien. Saat ini, GTAF mendukung mobiledataplan dan youtube sebagai ID klien yang valid. Berikut adalah contoh permintaan untuk operator dengan ASN 12345 dan kunci pengguna abcdef yang membagikan informasi paket dengan GTAF untuk klien youtube:

POST https://mobiledataplansharing.googleapis.com/v1/operators/12345/clients/youtube/users/abcdef/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"
    }]
  }],
  "planInfoPerClient": {
    "youtube": {
      "rateLimitedStreaming": {
        "maxMediaRateKbps": 569
      }
    }
  },
  "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"
}

Jika permintaan berhasil, GTAF akan menampilkan kode respons HTTP 200 dan entri planStatus yang dikirim dengan entri notifikasi jika ada notifikasi yang dikirim kepada pengguna. Jika GTAF mengidentifikasi masalah pada permintaan, GTAF akan menampilkan kode status HTTP dalam rentang 400-499. Jika GTAF tidak dapat menyelesaikan permintaan karena kesalahan GTAF, GTAF akan menampilkan kode HTTP dalam rentang 500-599. Permintaan yang menerima respons dalam rentang 500-599 dianggap dapat dicoba lagi dan permintaan yang menerima respons dalam rentang 400-499 umumnya tidak dapat dicoba lagi.

Pemberitahuan Status Paket untuk Klien Default

GTAF terus mendukung panggilan berikut yang status paketnya dikirim oleh operator tanpa menentukan klien yang dapat menggunakannya. Dalam kasus ini, kita mengasumsikan bahwa status paket ditujukan untuk klien mobiledataplan dan operator bermaksud mengirimkan notifikasi kepada pengguna. Isi permintaan sama untuk kasus penggunaan per klien dan kasus penggunaan klien default.

POST https://mobiledataplansharing.googleapis.com/v1/operators/12345/planStatuses?userKey=abcdef

Internasionalisasi

Untuk mendukung internasionalisasi, DPA harus mengetahui bahasa pilihan pengguna meskipun tanpa permintaan langsung dari GTAF. Untuk mengatasi masalah ini, permintaan ke endpoint CPID DAPAT menyertakan header Accept-Language. Jika header disertakan, string yang mudah dibaca manusia dalam update yang dikirim DPA menggunakan MDP API harus menggunakan setelan yang diberikan dalam permintaan CPID.