Halaman ini diterjemahkan oleh Cloud Translation API.

API Agen Paket Data

Motivasi

Seperti yang disebutkan dalam ringkasan, bergantung pada kasus penggunaan yang ingin didukung operator, DPA harus menerapkan kombinasi Google Mobile Data Plan Sharing API dan Data Plan Agent API. Dokumen ini menjelaskan Data Plan Agent API yang akan digunakan Google untuk mengidentifikasi paket data seluler pengguna, mengambil informasi tentang paket ini, dan membeli paket data.

Autentikasi

Sebelum GTAF dapat melakukan panggilan, DPA harus mengautentikasi GTAF. Sebagai bagian dari proses aktivasi operator, kami akan memeriksa validitas sertifikat SSL DPA. Saat ini, kami MENGHARUSKAN penggunaan OAuth2 untuk autentikasi bersama. Lihat Autentikasi Agen Paket Data untuk mengetahui detail tentang cara GTAF mengautentikasi dirinya dengan DPA.

Internasionalisasi

Permintaan GTAF ke DPA mencakup header Accept-Language yang menunjukkan bahasa yang harus digunakan untuk string yang dapat dibaca manusia (misalnya, deskripsi paket). Selain itu, respons DPA (PlanStatus, PlanOffers) menyertakan kolom languageCode wajib yang nilainya adalah kode bahasa BCP-47 (misalnya, "en-US") respons.

Jika DPA 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 mengirimkan kueri ke DPA operator. Saat GTAF mengkueri DPA atas nama aplikasi yang memiliki akses ke MSISDN, GTAF MUNGKIN menggunakan MSISDN. Pada tingkat tinggi, Data Plan Agent API yang diusulkan terdiri dari komponen berikut:

Mekanisme untuk mengkueri status paket data pengguna.
Mekanisme untuk membuat kueri DPA terkait penawaran paket data untuk 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 membagikan pilihan pengguna tentang apakah akan mendaftar ke layanan kami.

Bagian lain dalam dokumen ini menguraikan setiap komponen API ini. Kecuali dinyatakan secara eksplisit, semua komunikasi HARUS dilakukan melalui HTTPS (dengan sertifikat SSL DPA yang valid). Bergantung pada fitur sebenarnya yang didukung, operator DAPAT memilih untuk menerapkan semua atau sebagian kecil 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 Google API 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 kepada 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 dan oleh karena itu tidak dijelaskan lebih lanjut. Langkah 2 adalah API publik yang dijelaskan di bawah. DPA HARUS mematuhi header HTTP Cache-Control: no-cache saat melayani 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 atas nama klien tersebut GTAF 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 mengetahui 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 berupa tanggal pengulangan paket (yaitu, saat saldo data diperbarui/dimuat ulang).

Setiap modul paket dapat berisi beberapa Kategori Traffic Modul Paket (PMTCs) untuk memodelkan kasus ketika modul paket 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 diharapkan menghubungi masing-masing tim Google untuk menyepakati serangkaian 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 atas nama klien tersebut GTAF 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 merepresentasikan PlanOffer. Lihat Kasus Error untuk mengetahui 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 ditampilkan kepada pengguna. Selain itu, jika aplikasi hanya dapat menampilkan paket x karena batasan UI atau lainnya dan respons hanya berisi paket y > x, hanya x paket pertama yang HARUS ditampilkan. GTAF hanya membagikan hingga 50 paket jika aplikasi yang meminta penawaran adalah modul Paket Data Seluler yang merupakan bagian dari Layanan Google Play. Hal ini dilakukan untuk memastikan pengalaman pengguna yang baik bagi pengguna Layanan Google Play.

Penawaran peningkatan penjualan memiliki filterTags sebagai parameter opsional yang merupakan array tag yang dilampirkan ke setiap paket. Semua filterTags ini harus cocok dengan tag yang merupakan objek di dalam Filter. Filter adalah objek tingkat pertama yang berisi tuple<tag, displaytext="">. Filter adalah daftar gabungan filter yang akan dirender di UI. Pengguna dapat memfilter dengan mengklik DisplayText. Tag yang sesuai dengan displayText digunakan untuk memfilter penawaran.</tag,>

Perhatikan bahwa operator HARUS memiliki mekanisme untuk memenuhi permintaan pembelian untuk penawaran apa pun yang diberikan kepada pengguna. Mekanisme yang digunakan untuk menagih pengguna atas pembelian apa pun dapat dikomunikasikan dengan GTAF menggunakan opsi formOfPayment dalam respons.

Pembelian Data

API paket pembelian menentukan cara GTAF dapat membeli paket melalui DPA. GTAF memulai transaksi untuk membeli satu paket data ke DPA. Permintaan HARUS menyertakan ID transaksi unik (transactionId) untuk melacak permintaan dan menghindari eksekusi transaksi duplikat. DPA HARUS merespons dengan respons berhasil/gagal.

Permintaan Transaksi

Setelah menerima permintaan dari klien, GTAF akan mengirimkan permintaan POST ke DPA. URL permintaan adalah:

POST DPA_URL/{userKey}/purchasePlan?key_type={CPID,MSISDN}&client_id=CLIENT_ID

dengan userKey adalah 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 HARUS menghasilkan respons 200-OK hanya untuk transaksi yang berhasil dieksekusi atau transaksi yang diantrekan. Lihat Kasus Error untuk respons yang diharapkan jika terjadi error. Jika transaksi dalam antrean, DPA hanya akan mengisi status transaksi dan mengosongkan kolom lain dalam respons. DPA HARUS memanggil kembali GTAF dengan respons setelah transaksi yang diantrekan 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 AKAN mengasumsikan bahwa paket telah diaktifkan.

Mendaftarkan CPID

Saat klien yang mendukung notifikasi mendapatkan CPID baru dari endpoint CPID, klien tersebut akan mendaftarkan CPID ke GTAF jika persyaratan klien mengizinkan GTAF melakukannya. Jika klien berhasil mendaftarkan CPID ke GTAF, GTAF akan mendaftarkan CPID ke DPA menggunakan panggilan API berikut:

POST DPA_URL/{userKey}/registerCpid?key_type={CPID,MSISDN}&client_id=CLIENT_ID

dengan userKey adalah 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. Untuk mengirim notifikasi secara andal kepada pengguna, DPA DAPAT menyimpan CPID terdaftar terbaru untuk setiap pengguna. Lihat Memilih CPID untuk mendapatkan panduan tentang cara menggunakan CPID terdaftar untuk mengirim notifikasi.

DPA akan menghasilkan respons 200-OK jika DPA berhasil mengaitkan CPID dengan pengguna dan menyimpannya secara persisten. Lihat Kasus Error untuk mengetahui respons yang diharapkan jika terjadi error.

GTAF DAPAT mengeluarkan permintaan berikut untuk meneruskan preferensi izin pengguna kepada operator.

POST DPA_URL/{userKey}/consent?key_type={CPID,MSISDN}&client_id=CLIENT_ID

dengan userKey adalah CPID atau MSISDN. Isi permintaan adalah instance SetConsentStatusRequest. Jika berhasil, isi respons akan kosong.

Setiap panggilan dari GTAF ke DPA mengikuti persyaratan layanan klien Google yang melakukan panggilan. Bergantung pada aplikasi yang ingin didukung DPA, operator yang akan memutuskan apakah DPA mengimplementasikan API ini. 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 mengetahui respons yang diharapkan jika terjadi error.

API Agen Paket Data Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.