API Berbagi Paket Data Seluler Google

Motivasi

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

Autentikasi

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

Update Paket Data

Saat ini Google Mobile Data Plan Sharing API memungkinkan operator untuk berbagi update tentang paket data pengguna:

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

Mengidentifikasi pengguna yang relevan

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

  1. CPID aktif: pengguna dengan CPID aktif. Hingga CPID yang telah dihasilkan oleh endpoint CPID valid, DPA HARUS mengirim pembaruan tentang paket data pengguna. Jika header Accept-Language ditetapkan pada saat pembuatan CPID, 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 msis pada Data Agent Agen Paket. Setelah MSISDN didaftarkan, DPA HARUS mengirim pembaruan tentang paket data pengguna hingga pendaftaran berakhir.

Deskripsi API

Berbagi Status Paket Data

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

Aplikasi dapat menerima informasi status paket data dengan dua cara:

  1. UE memanggil GTAF untuk informasi status paket data:
    1. DPA operator menggunakan Data Plan Sharing API untuk menerapkan status paket data pengguna ke GTAF. GTAF menyimpan status paket dan kunci pengguna terkaitnya.
    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. GTAF kemudian menampilkan status ini ke UE.
  2. GTAF mengirim informasi status paket data ke UE:
    1. Jika relevan, status paket data yang diterima dari operator akan didorong langsung ke UE.

Interaksi GTAF-DPA

DPA menggunakan HTTPS POST untuk membuat dan memperbarui entri status paket yang ada agar pengguna dapat digunakan oleh klien. Saat ini GTAF mendukung mobiledataplan dan youtube sebagai ID klien yang valid. Berikut adalah contoh permintaan untuk operator dengan informasi paket berbagi asn 12345 dan abcdef kunci pengguna 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 tersebut 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 terkait 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 ulang dan permintaan yang menerima respons dalam rentang 400-499 umumnya tidak dapat dicoba lagi.

Push Status Rencana untuk Klien Default

GTAF terus mendukung panggilan berikut ketika status paket didorong oleh operator tanpa menentukan klien yang dapat digunakan. Dalam hal ini, kami menganggap status paket tersebut ditujukan untuk klien mobiledataplan dan operator bermaksud untuk mengirimkan notifikasi kepada pengguna. Isi permintaan sama untuk kasus penggunaan per klien dan kasus penggunaan klien default.

POSTINGAN 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 dapat dibaca manusia dalam update yang dikirim DPA menggunakan MDP API harus menggunakan setelan yang disediakan dalam permintaan CPID.