Motivasi
Seperti yang disebutkan dalam ringkasan, bergantung pada kasus penggunaan yang ingin didukung oleh operator, DPA harus menerapkan kombinasi Google Mobile Data Plan Sharing API dan Data Agent API. Dokumen ini menjelaskan Data Agent API yang akan digunakan Google untuk mengidentifikasi paket data seluler milik pengguna, mengambil informasi tentang paket tersebut, dan membeli paket data.
Autentikasi
Sebelum GTAF dapat menelepon, DPA harus mengautentikasi GTAF. Sebagai bagian dari proses aktivasi operator, kami akan memeriksa validitas sertifikat SSL DPA. Saat ini kami MEWAJIBKAN penggunaan OAuth2 untuk autentikasi bersama. Lihat Data Agent Agen Paket untuk mengetahui detail tentang cara GTAF mengautentikasi dirinya sendiri dengan DPA.
Internasionalisasi
Permintaan GTAF ke DPA menyertakan header Accept-Language yang menunjukkan bahasa yang harus digunakan oleh string yang dapat dibaca manusia (misalnya, deskripsi rencana). Selanjutnya, respons DPA (PlanStatus, PlanOffers) menyertakan kolom languageCode wajib yang nilainya adalah kode bahasa BCP-47 (misalnya, "id-ID") dari respons.
Jika tidak mendukung bahasa yang diminta pengguna, DPA dapat menggunakan bahasa default dan menggunakan kolom languageCode untuk menunjukkan pilihannya.
Deskripsi API
GTAF menggunakan kunci pengguna, yang mengidentifikasi pelanggan ke operator, saat membuat kueri DPA operator. Saat GTAF membuat kueri DPA atas nama aplikasi yang memiliki akses ke MSISDN, GTAF DAPAT menggunakan MSISDN. Pada tingkat tinggi, Data Plan Agent API yang diusulkan terdiri dari komponen berikut:
- Mekanisme untuk mengkueri status paket data pengguna.
- Mekanisme kueri DPA untuk penawaran paket data bagi pengguna.
- Mekanisme untuk melakukan perubahan pada paket data pengguna (misalnya, membeli paket baru).
- Mekanisme untuk membagikan CPID yang dapat digunakan untuk mengirim notifikasi kepada pengguna.
- Mekanisme untuk berbagi pilihan pengguna terkait apakah mereka akan mendaftar ke layanan kami atau tidak.
Bagian selanjutnya dari dokumen ini menguraikan setiap komponen API tersebut. Kecuali jika dinyatakan secara eksplisit, semua komunikasi HARUS terjadi melalui HTTPS (dengan sertifikat SSL DPA yang valid). Bergantung pada fitur sebenarnya yang didukung, operator mungkin akan memilih untuk menerapkan semua atau subset komponen API ini.
Interaksi GTAF-DPA
Gambar 4. Alur panggilan untuk meminta dan menerima informasi paket data pengguna.
Gambar 4 mengilustrasikan alur panggilan yang terkait dengan klien yang membuat kueri tentang status paket data pengguna dan informasi paket data lainnya. Alur panggilan ini dibagikan untuk panggilan API yang dipicu oleh klien di UE.
- Klien meminta status paket data dan/atau informasi lainnya dengan memanggil API Google pribadi. Klien menyertakan kunci pengguna dalam permintaan ke GTAF.
- GTAF menggunakan kunci pengguna dan ID klien untuk mengkueri DPA operator. ID klien yang didukung adalah mobiledataplan dan youtube. Saat menerima panggilan dengan salah satu ID klien ini, DPA harus merespons dengan informasi paket yang dapat digunakan oleh klien.
- GTAF menampilkan informasi yang diminta ke klien dan informasi paket di-cache oleh GTAF hingga waktu habis masa berlaku yang ditentukan oleh DPA.
Langkah 1 dan 3 pada Gambar 4 adalah Google API pribadi, sehingga tidak
dijelaskan lebih lanjut. Langkah 2 adalah API publik yang dijelaskan selanjutnya. DPA HARUS
menghormati header HTTP Cache-Control: no-cache saat menayangkan panggilan API ini
dari GTAF.
Membuat Kueri Status Paket Data
GTAF mengeluarkan permintaan HTTP berikut untuk mendapatkan status paket:
GET DPA_URL/{userKey}/planStatus?key_type={CPID,MSISDN}&client_id=CLIENT_ID
Klien yang digunakan GTAF untuk menghubungi DPA diidentifikasi menggunakan CLIENT_ID. Bergantung pada perjanjian antara klien dan operator Google, DPA dapat menyesuaikan respons terhadap GTAF. Jika berhasil, DPA HARUS menampilkan HTTP 200 OK dengan isi respons yang merepresentasikan PlanStatus. Lihat Kasus Error untuk respons yang diharapkan jika terjadi error.
{
"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
}
}
}
}
Untuk paket pascabayar, expirationTime HARUS merupakan tanggal pengulangan paket (yaitu,
saat saldo data diperbarui/dimuat ulang).
Setiap modul rencana dapat berisi beberapa Kategori Traffic Modul Rencana (PMTCs) untuk
memodelkan kasus saat modul rencana dibagikan di antara beberapa aplikasi (misalnya, 500 MB
untuk game dan musik). PMTC berikut telah ditentukan sebelumnya: GENERIC, VIDEO,
VIDEO_BROWSING, VIDEO_OFFLINE, MUSIC, GAMING, SOCIAL and MESSAGING. Operator mungkin akan menghubungi setiap tim Google untuk menyetujui kumpulan
kategori traffic dan semantiknya yang relevan untuk berbagai aplikasi
Google.
Membuat Kueri Penawaran Paket
GTAF mengeluarkan permintaan HTTP berikut untuk mendapatkan penawaran paket dari operator:
GET DPA_URL/{userKey}/planOffer?key_type={CPID,MSISDN}&client_id=CLIENT_ID&context={purchaseContext}
Klien yang digunakan GTAF untuk menghubungi DPA diidentifikasi menggunakan CLIENT_ID. Bergantung pada perjanjian antara klien dan operator Google, DPA dapat menyesuaikan respons terhadap GTAF. Parameter konteks opsional memberikan konteks aplikasi tempat permintaan dibuat. Biasanya ini adalah string yang diteruskan aplikasi ke operator melalui GTAF.
Jika berhasil, DPA HARUS menampilkan HTTP 200 OK dengan isi respons yang mewakili PlanOffer. Lihat Kasus Error untuk respons yang diharapkan jika terjadi error.
{
"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.
}
Urutan paket data dalam array offers DAPAT menentukan urutan paket data yang ditampilkan kepada pengguna. Selain itu, jika aplikasi hanya dapat menyajikan paket x karena UI atau batasan lainnya, dan respons berisi paket y > x hanya paket x pertama yang akan ditampilkan. GTAF hanya berbagi
hingga 50 paket jika aplikasi yang membuat kueri penawaran adalah modul Paket Data Seluler yang
merupakan bagian dari Layanan Google Play. Hal ini untuk memastikan pengalaman pengguna yang baik bagi
pengguna Layanan Google Play.
Penawaran upsell memiliki filterTags sebagai parameter opsional yang merupakan array tag yang dilampirkan ke setiap rencana. Semua filterTags ini harus cocok dengan tag yang merupakan objek di dalam Filter. Filter adalah objek level pertama yang berisi
tuple<tag, displaytext="">. Filter adalah daftar filter gabungan yang akan
dirender di UI. Pengguna dapat memfilter dengan mengklik DisplayText. Tag
yang sesuai dengan displayText digunakan untuk memfilter penawaran.</tag,>
Perlu diingat bahwa operator HARUS memiliki mekanisme untuk memenuhi permintaan pembelian penawaran yang diperluas kepada pengguna. Mekanisme yang mengharuskan pengguna ditagih untuk setiap pembelian dapat disampaikan melalui GTAF menggunakan opsi formOfPayment dalam respons.
Pembelian Data
API rencana pembelian menentukan cara GTAF dapat membeli rencana melalui DPA. GTAF memulai transaksi untuk membeli satu paket data ke DPA. Permintaan SHALL menyertakan ID transaksi unik (transactionId) untuk melacak permintaan dan menghindari eksekusi transaksi duplikat. DPA HARUS merespons dengan respons yang berhasil/gagal.
Permintaan Transaksi
Setelah menerima permintaan dari klien, GTAF akan mengirimkan permintaan POST ke DPA. URL permintaannya adalah:
POST DPA_URL/{userKey}/purchasePlan?key_type={CPID,MSISDN}&client_id=CLIENT_ID
dengan userKey sebagai CPID atau MSISDN. Isi permintaan adalah instance TransactionRequest yang mencakup kolom berikut:
{
"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.
}
Respons Transaksi
DPA SHALL akan menghasilkan respons 200-OK hanya untuk transaksi yang berhasil dijalankan atau transaksi dalam antrean. Lihat Kasus Error untuk respons yang diharapkan jika terjadi error. Untuk transaksi yang diantrekan, DPA hanya akan mengisi status transaksi dan mengosongkan kolom lain dalam respons. DPA HARUS memanggil GTAF kembali dengan respons setelah transaksi dalam antrean ditangani. Isi respons adalah instance TransactionResponse yang mencakup detail berikut:
{
"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.
}
}
Jika planActivationTime tidak ada, GTAF SHALL akan menganggap bahwa paket telah
diaktifkan.
Daftarkan CPID
Jika klien yang mendukung notifikasi mendapatkan CPID baru dari endpoint CPID, klien akan mendaftarkan CPID dengan GTAF jika persyaratan klien mengizinkan GTAF untuk melakukannya. Jika klien berhasil mendaftarkan CPID dengan GTAF, maka GTAF akan mendaftarkan CPID dengan DPA menggunakan panggilan API berikut:
POST DPA_URL/{userKey}/registerCpid?key_type={CPID,MSISDN}&client_id=CLIENT_ID
dengan userKey sebagai CPID dan satu-satunya CLIENT_ID yang didukung adalah
mobiledataplan. Isi permintaan adalah instance RegisterCpidRequest dan berisi waktu setelah CPID tidak dapat digunakan untuk mengirim notifikasi dan terlihat seperti:
{"staleTime": "2017-01-29T01:00:03.14159Z"}
API ini hanya relevan untuk operator yang ingin mendukung modul Paket Data Seluler di Layanan Google Play. Agar dapat mengirim notifikasi secara andal kepada pengguna, DPA MUNGKIN menyimpan CPID terbaru yang terdaftar untuk setiap pengguna. Lihat Memilih CPID untuk panduan tentang cara menggunakan CPID terdaftar untuk mengirim notifikasi.
DPA akan menghasilkan respons 200-OK jika DPA berhasil mengaitkan CPID dengan pengguna dan terus-menerus menyimpannya. Lihat Kasus Error untuk respons yang diharapkan jika terjadi error.
Izin
GTAF MUNGKIN mengeluarkan permintaan berikut untuk meneruskan preferensi izin pengguna ke operator.
POST DPA_URL/{userKey}/consent?key_type={CPID,MSISDN}&client_id=CLIENT_ID
dengan userKey sebagai CPID atau MSISDN. Isi permintaan adalah instance SetConsentStatusRequest. Jika
berhasil, isi respons harus kosong.
Setiap panggilan dari GTAF ke DPA mengikuti persyaratan layanan klien Google yang melakukan panggilan. Bergantung pada aplikasi yang ingin didukung DPA, operator dapat menentukan apakah DPA akan menerapkan API ini atau tidak. Jika DPA memilih untuk menerapkan API izin, DPA HARUS menyimpan status izin terbaru untuk setiap pengguna. Lihat Memilih CPID untuk mendapatkan panduan tentang cara menggunakan informasi status izin.
Jika berhasil, DPA HARUS menampilkan HTTP 200 OK dengan isi respons kosong. Lihat Kasus Error untuk respons yang diharapkan jika terjadi error.