API Agen Paket Data

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.

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:

  1. Mekanisme untuk mengkueri status paket data pengguna.
  2. Mekanisme kueri DPA untuk penawaran paket data bagi pengguna.
  3. Mekanisme untuk melakukan perubahan pada paket data pengguna (misalnya, membeli paket baru).
  4. Mekanisme untuk memverifikasi apakah pengguna memenuhi syarat untuk membeli paket data tertentu.
  5. Mekanisme GTAF untuk mendaftarkan MSISDN dengan DPA.
  6. Mekanisme GTAF untuk memverifikasi apakah DPA dalam kondisi sehat.

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.

Membuat Kueri Status Paket Data

Interaksi GTAF-DPA

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.

  1. Klien meminta status paket data dan/atau informasi lainnya dengan memanggil API Google pribadi. Klien menyertakan kunci pengguna dalam permintaan ke GTAF.
  2. 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.
  3. 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.

Status Rencana

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 Google dan operator, DPA dapat menyesuaikan respons terhadap GTAF. Format respons adalah objek JSON yang mewakili 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
      }
    }
  }
}

Permintaan SHALL menyertakan header Accept-Language yang menunjukkan bahasa yang harus digunakan untuk string yang dapat dibaca manusia (misalnya, deskripsi rencana).

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 Google dan operator, 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.

Isi respons memuat instance 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"
      }
    ],
    "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 10 paket jika aplikasi yang membuat kueri penawaran adalah UI Paket Data Seluler yang menjadi bagian dari Layanan Google Play. Hal ini untuk memastikan pengalaman pengguna yang baik bagi pengguna Layanan Google Play.

String di offerInfo dimaksudkan untuk memungkinkan pengguna membaca selengkapnya tentang penawaran, dan juga menyertakan cara untuk memilih tidak ikut menerima penawaran lainnya dari dalam aplikasi. Alasan untuk memiliki kolom ini adalah karena beberapa operator tidak memerlukan izin pengguna akhir untuk mengizinkan pembelian dalam aplikasi, tetapi memerlukan mekanisme bagi pengguna untuk memilih tidak ikut. Perlu diingat bahwa operator HARUS memiliki mekanisme untuk memenuhi permintaan pembelian untuk penawaran apa pun yang diperpanjang kepada pengguna. Mekanisme yang akan dikenakan kepada pengguna untuk setiap pembelian dapat dikomunikasikan dengan GTAF menggunakan opsi formOfPayment dalam respons.

Permintaan SHALL menyertakan header Accept-Language yang menunjukkan bahasa yang harus digunakan untuk string yang dapat dibaca manusia (misalnya, deskripsi rencana).

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 akan menampilkan penyebab error yang umum jika terjadi error. Selain itu, kode error berikut mewakili hasil transaksi yang gagal:

  • DPA menampilkan kode error 400 BAD REQUEST yang menunjukkan kepada GTAF bahwa ID paket yang dibeli tidak valid.
  • DPA menampilkan kode error 402 PEMBAYARAN YANG DIPERLUKAN yang menunjukkan kepada GTAF bahwa pengguna tidak memiliki saldo yang cukup untuk menyelesaikan pembelian.
  • DPA menampilkan kode error Konflik 409 yang menunjukkan kepada GTAF bahwa paket yang akan dibeli tidak kompatibel dengan campuran produk pengguna saat ini. Misalnya, jika kebijakan paket data operator tidak mengizinkan penggabungan paket pascabayar dan prabayar, upaya untuk membeli paket prabayar untuk pengguna pascabayar akan menyebabkan error 409 CONFLICT.
  • DPA menampilkan kode error 403 FORBIDDEN yang menunjukkan ke GTAF bahwa transaksi saat ini merupakan duplikat dari transaksi yang diterbitkan sebelumnya. DPA HARUS menampilkan penyebab error berikut sebagai respons:
    • Jika transaksi sebelumnya gagal, penyebab error menunjukkan alasan kegagalan.
    • Jika transaksi sebelumnya berhasil, DUPLICATE_TRANSACTION.
    • Jika transaksi sebelumnya masih dalam antrean, REQUEST_QUEUED.

DPA SHALL akan menghasilkan respons 200-OK hanya untuk transaksi yang berhasil dijalankan atau transaksi dalam antrean. 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.

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.

Persyaratan

GTAF MUNGKIN mengeluarkan permintaan kelayakan berikut untuk memeriksa apakah pengguna memenuhi syarat untuk membeli paket.

GET DPA/{userKey}/Eligibility/{planId}?key_type={CPID,MSISDN}

Perhatikan bahwa planId adalah ID unik untuk paket yang dapat digunakan untuk membeli paket atas nama pengguna (Lihat Pembelian Data). Jika planId tidak ditentukan, DPA HARUS menampilkan semua paket yang dapat dibeli oleh pengguna tersebut.

DPA akan menampilkan penyebab error yang umum jika terjadi error. Selain itu, DPA SHALL akan menampilkan error dalam kasus error berikut:

  • DPA menampilkan kode error 400 BAD REQUEST yang menunjukkan kepada GTAF bahwa planId tidak valid.
  • DPA menampilkan kode error Konflik 409 yang menunjukkan bahwa planId tidak kompatibel dengan paket data pengguna.

Jika tidak, DPA SHALL akan menampilkan respons 200-OK. Format eligibilityResponse yang berhasil adalah:

{
  "eligiblePlans":
  [
   {
    "planId": string,   // Plan identifier. Can be used to
                        // refer to the plan during
                        // offers, etc. (req.)
   }
  ]
}

Jika permintaan tersebut menyertakan planId, respons hanya menyertakan paket tersebut. Jika tidak, daftar tersebut mencakup semua paket yang dapat dibeli oleh pengguna. Jika planId kosong dan DPA tidak mendukung pemberian daftar paket yang memenuhi syarat, DPA harus menampilkan error 400 BAD REQUEST.

Endpoint pendaftaran MSISDN

Untuk menayangkan aplikasi yang memiliki akses ke MSISDN, GTAF akan mendaftarkan MSISDN dengan DPA. GTAF mendaftarkan MSISDN hanya jika ada aplikasi yang disalurkan oleh Google Mobile Data Plan Sharing API, di mana DPA mengirimkan informasi ke GTAF menggunakan Google API. Untuk mendaftarkan MSISDN, GTAF akan membuat permintaan POST ke DPA:

POST_DPA_URL/daftar

Isi permintaan akan berupa instance EnrollmentRequest.

{
  "msisdn": "<msisdn_string>"
}

Jika pendaftaran MSISDN berhasil, DPA HARUS menampilkan respons 200 Oke termasuk EnrollmentResponse. Format JSON adalah:

{
  // msisdn that was registered.
  "msisdn": "<msisdn_string>",
  // time after which DPA will not send updates to GTAF.
  "expirationTime": string
}

Kemudian, DPA HARUS mengirim pembaruan tentang paket data pengguna ke GTAF hingga expirationTime berlalu.

Jika terjadi error, ErrorResponse harus ditampilkan:

{
    "error": "<error message>",
    "cause": enum(ErrorCause)
}

Daftar lengkap kemungkinan penyebab nilai dan kode status HTTP untuk berbagai kondisi error tersedia di sini. Secara khusus, jika permintaan pendaftaran MSISDN diterima untuk pengguna yang berkeliaran atau yang memilih untuk tidak membagikan informasi paket data kepada Google, DPA HARUS menampilkan kode status HTTP 403.

Monitoring API

Beberapa kasus penggunaan memerlukan GTAF untuk memantau DPA dan mendeteksi kegagalan DPA. Untuk kasus penggunaan tersebut, kami telah menentukan API pemantauan.

Definisi API

Monitoring API harus tersedia melalui permintaan HTTP GET di URL berikut:

DPA_URL/dpaStatus

Jika DPA dan semua backend-nya beroperasi dengan benar, DPA harus merespons kueri ini dengan kode status HTTP 200 dan isi respons yang memiliki instance DpaStatus.

{
    "status": enum(DpaStatusEnum),
    "message": "<optional human-readable status description>"
}

Jika DPA atau backend-nya tidak beroperasi dengan benar, DPA harus merespons dengan kode status HTTP 500 dan isi respons yang memiliki instance DpaStatus.

Perilaku DPA

Saat kegagalan terdeteksi, DPA harus menampilkan status "UNAVAILABLE" untuk semua kueri dpaStatus. Selain itu, aplikasi harus berhenti mengirim informasi paket data dengan periode cache yang panjang. Aplikasi dapat berhenti mengirim respons dengan periode cache yang panjang menggunakan salah satu dari dua cara berikut:

  1. Mulai tetapkan waktu berakhirnya cache yang singkat.
  2. Berhenti mengirim informasi paket data sepenuhnya.

Perilaku GTAF

GTAF akan melakukan polling pada dpaStatus secara berkala. Jika mendeteksi kegagalan DPA (berdasarkan respons "UNAVAILABLE"), DPA akan dihapus dari cache-nya untuk operator.

Kasus Error

Jika terjadi error, DPA diharapkan menampilkan kode status HTTP yang sesuai dengan salah satu kode berikut:

  • Saat ini pengguna sedang roaming dan kueri DPA dinonaktifkan untuk pengguna ini. DPA menampilkan error 403.
  • DPA menampilkan kode error 404 NOT_FOUND yang menunjukkan kepada GTAF bahwa kunci pengguna tidak valid (yaitu, kunci pengguna yang tidak ada).
  • DPA menampilkan kode error 410 GONE yang menunjukkan ke GTAF bahwa klien harus mendapatkan kunci pengguna baru jika key_type = CPID dan CPID sudah tidak berlaku.
  • DPA menampilkan kode error 501 NOT_IMPLEMENTED yang menunjukkan bahwa kode ini tidak mendukung panggilan ini.
  • Layanan tidak tersedia untuk sementara. DPA menampilkan 503 LAYANAN TIDAK TERSEDIA dengan header Coba Lagi Setelah menunjukkan kapan permintaan baru dapat dicoba.
  • DPA menampilkan kode error ERROR SERVER 500 INTERNAL untuk semua error yang tidak ditentukan lainnya.
  • DPA menampilkan error 429 TOO_MANY_REQUEST dengan header Retry-After yang menunjukkan bahwa GTAF membuat terlalu banyak permintaan ke DPA.
  • DPA menampilkan error Konflik 409 yang menunjukkan bahwa permintaan tidak dapat diselesaikan karena bertentangan dengan status DPA saat ini.

Dalam semua kasus error, isi respons HTTP HARUS menyertakan objek JSON dengan informasi selengkapnya tentang error tersebut. Isi respons error HARUS berisi instance ErrorResponse.

{
  "error": string,
  "cause": enum(ErrorCause)
}

Nilai cause yang saat ini ditetapkan tercantum sebagai bagian dari referensi ErrorCause API.

Jika tidak, DPA akan menampilkan nilai 200 OK. Perhatikan bahwa nilai cause ini digunakan untuk semua respons.

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.