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 pembaruan 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 status paket kepada pengguna.
Deskripsi API
Gambar 3. Interaksi GTAF-DPA saat DPA membagikan status paket data dengan GTAF.
Aplikasi dapat menerima informasi status paket data yang dibagikan dengan GTAF melalui salah satu dari dua cara:
- UE memanggil GTAF untuk mendapatkan informasi status paket data:
- DPA operator menggunakan Data Plan Sharing API untuk mengirimkan status paket data pengguna ke GTAF. GTAF menyimpan status paket dan kunci pengguna terkait hingga waktu habis masa berlaku yang ditentukan oleh operator.
- Aplikasi Google yang berjalan di UE meminta informasi status paket data menggunakan API internal Google. Aplikasi menyertakan kunci pengguna dalam permintaannya.
- 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 aplikasi.
- GTAF mengirimkan informasi status paket data ke UE:
- Jika relevan, status paket data yang diterima dari operator akan langsung dikirim ke UE. Secara khusus, status paket yang didorong digunakan untuk memperbarui cache modul Paket Data Seluler di perangkat di Layanan Google Play.
Membagikan Status Paket Data
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
Isi permintaan adalah instance 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. Kasus Error menjelaskan respons error dari GTAF secara mendetail.
Pemberitahuan Status Paket untuk Klien Default
GTAF mendukung panggilan berikut saat status paket dikirim oleh operator tanpa menentukan klien yang dapat menggunakannya. Dalam hal ini, kita mengasumsikan bahwa status paket ditujukan untuk klien mobiledataplan dan operator bermaksud mengirimkan notifikasi kepada pengguna. Isi permintaan adalah instance PlanStatus
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, bergantung pada akses klien ke preferensi bahasa pengguna. Jika header disertakan, string yang dapat dibaca manusia dalam update yang dikirim DPA menggunakan MDP API harus menggunakan setelan yang diberikan dalam permintaan CPID.
DPA DAPAT memperbarui preferensi bahasa pengguna saat menerima permintaan dari GTAF dengan header Accept-Language dan menggunakan preferensi pengguna yang diperbarui untuk menentukan kode bahasa dalam permintaan mendatang ke GTAF.
DPA HARUS menentukan bahasa yang digunakan untuk string yang terlihat oleh pengguna menggunakan languageCode. GTAF menggunakan ini untuk membuat judul dan isi notifikasi yang ditampilkan kepada pengguna.