Menetapkan CPID

GTAF menggunakan kunci pengguna untuk mengidentifikasi pelanggan saat berkomunikasi dengan DPA. Aplikasi yang memiliki akses ke MSISDN pengguna dapat menggunakannya sebagai user_key. Di sisi lain, aplikasi yang tidak memiliki akses ke MSISDN, perlu membuat ID paket operator (CPID) tanpa menemukan MSISDN pengguna. Berikut ini, kami menjelaskan mekanisme yang membuat CPID.

Alur Panggilan CPID

Gambar 2: Alur panggilan untuk membuat CPID.

  1. Aplikasi Google di UE menggunakan API internal Google untuk mengambil URL endpoint CPID dari GTAF. Operator diidentifikasi menggunakan alamat IP publik klien dan MCC+MNC kartu SIM aktif. Dalam kasus MVNO, Google akan menggunakan SPN dan GID1 untuk menentukan MVNO
  2. Klien mengirimkan permintaan HTTP GET ke endpoint CPID. Operator DAPAT mendukung pengiriman permintaan melalui HTTPS.
  3. Operator DAPAT menggunakan fungsi Deep Packet Inspection untuk mengidentifikasi permintaan dan menyuntikkan nomor telepon pengguna ke permintaan sebagai header HTTP.
  4. Endpoint CPID menerima permintaan, membuat CPID, dan menampilkan CPID ke UE dengan time to live (TTL) yang menunjukkan durasi UE dapat menggunakan CPID ini.

Operator JUGA DAPAT menggunakan alamat IP, bukan nama domain di URL endpoint CPID jika lebih disukai. Alamat IP MUNGKIN berada di ruang alamat pribadi, tetapi harus dapat dijangkau oleh klien Google di dalam jaringan operator.

Operator HARUS memberikan informasi berikut kepada Google sebagai bagian dari proses aktivasi:

  1. CPID_URL yang akan dihubungi aplikasi untuk mendapatkan CPID. Satu CPID_URL wajib ada, tetapi operator dapat memberikan beberapa URL untuk meningkatkan ketersediaan.
  2. Daftar awalan IP yang dimiliki operator serta Kode Negara Seluler (MCC) dan Kode Jaringan Seluler (MNC) yang ingin dipetakan ke CPID_URL yang diberikan. Jika operator menggunakan SPN atau GID1 untuk membedakan MVNO di jaringannya, operator HARUS memberikan informasi ini juga. Google akan menggunakan informasi ini untuk mencocokkan klien dengan endpoint CPID yang sesuai, seperti yang ditunjukkan pada Langkah 1 Gambar 2.

Format permintaannya adalah: GET CPID_URL Untuk alasan lama, endpoint CPID harus dapat mendukung permintaan seperti berikut:

GET CPID_URL?app={app_id}

Endpoint CPID dapat mengabaikan parameter URL {app_id} saat membuat CPID. Namun, API HARUS dapat menangani permintaan yang berisi parameter.

Permintaan ke endpoint CPID DAPAT menyertakan header Accept-Language. Jika header disertakan, string yang dapat dibaca manusia dalam update yang dikirim DPA menggunakan Mobile Data Plan Sharing API HARUS menggunakan setelan yang diberikan dalam permintaan CPID.

Setiap kali klien mengeluarkan permintaan GET CPID_URL, klien HARUS menerima CPID baru. Jika pembuatan CPID berhasil, endpoint CPID HARUS menampilkan respons 200 OK. Isi respons HARUS berisi instance CPIDResponse.

{
    "cpid": "<CPID_string>",
    "ttlSeconds": 2592000
}

CPID yang ditampilkan HARUS valid selama ttlSeconds detik meskipun pelanggan telah meminta CPID lain setelahnya. Google merekomendasikan penggunaan nilai TTL 30 hari, tetapi tidak kurang dari 14 hari untuk pengalaman pengguna terbaik. GTAF akan mengenkode CPID per RFC2396 dalam panggilan berikutnya ke DPA.

Pembuatan CPID

Cara yang DISARANKAN agar endpoint CPID membuat CPID adalah:

CPID_string = Base64(AES(MSISDN + TimeStamp + language, secret))

Endpoint CPID menggabungkan MSISDN, bahasa yang dikirim oleh klien di header Accept-Language, dan stempel waktu resolusi tinggi, lalu mengenkripsinya melalui AES menggunakan secretkunci. Stempel waktu HARUS sesuai dengan waktu berakhirnya CPID. Output terenkripsi dienkode Base64. Selain itu, saat CPID digunakan dalam URL, CPID HARUS dienkode URL untuk menangani karakter khusus (/+=) yang digunakan dalam Base64. Khususnya saat GTAF memanggil DPA atau saat DPA memanggil Mobile Data Plan Sharing API, CPID HARUS dienkode URL.

Bergantung pada situasi operator tertentu, penerapan endpoint CPID mungkin tidak mudah. Tantangan khusus yang sering dihadapi adalah mendapatkan akses ke MSISDN di endpoint CPID. Dengan senang hati kami membagikan pelajaran yang didapat saat mengaktifkan operator. Hubungi kami jika Anda menghadapi masalah.

Penyimpanan CPID

CPID yang dibuat menggunakan mekanisme yang dijelaskan di atas tidak harus disimpan ke dalam database. Informasi yang relevan untuk menangani panggilan ke DPA dapat diperoleh dari CPID.

  1. Saat DPA menerima panggilan dari GTAF untuk status atau penawaran paket, MSISDN dapat diperoleh dengan mendekripsi CPID dan mengekstrak MSISDN.
  2. Waktu habis masa berlaku CPID dapat diperoleh dengan mendekripsi CPID, lalu mengekstrak stempel waktu habis masa berlaku.

Persyaratan Ketersediaan dan Kapasitas

Jika klien tidak dapat mengambil CPID, mereka tidak dapat mengakses informasi apa pun dari Mobile Data Plan API. Oleh karena itu, operator HARUS mengambil tindakan yang diperlukan untuk memastikan ketersediaan endpoint CPID. Tindakan tersebut mencakup memiliki beberapa instance fungsi DPI dan endpoint CPID serta memiliki redundansi fisik, situs, dan jaringan untuk kedua fungsi tersebut, serta memastikan kapasitas dan resource sistem memadai. Selain itu, endpoint CPID serta fungsi DPI yang menyisipkan header harus memiliki kapasitas yang memadai untuk menangani beban semua klien Google yang meminta CPID. Endpoint CPID dapat menggunakan nilai yang lebih besar di kolom ttlSeconds untuk mengurangi frekuensi pembuatan CPID.

Kasus Error

Jika terjadi error, endpoint CPID HARUS menampilkan error HTTP dengan isi respons yang HARUS berisi instance ErrorResponse. Pesan error yang baik akan menyertakan informasi yang dapat membantu men-debug penyebab error. Misalnya, jika CPID telah habis masa berlakunya, menyertakan pembuatan CPID dan waktu habis masa berlakunya akan membantu kami mengonfirmasi bahwa endpoint CPID berfungsi seperti yang dirancang.

{
    "errorMessage": "<error message>",
    "cause": "USER_ROAMING"
}

Endpoint CPID HARUS menampilkan hal berikut, bergantung pada skenarionya:

  1. Jika permintaan CPID diterima untuk pengguna yang tidak termasuk dalam jaringan operator (misalnya, pengguna yang termasuk dalam operator lain tetapi melakukan roaming di jaringan yang disediakan oleh endpoint CPID ini) atau yang belum memilih untuk membagikan informasi paket datanya kepada Google, endpoint CPID HARUS menampilkan kode status HTTP 403 dengan USER_ROAMING, USER_OPT_OUT, atau INELIGIBLE_FOR_SERVICE sebagai penyebabnya.
  2. Jika permintaan CPID diterima dengan nomor telepon yang tidak valid, endpoint CPID HARUS menampilkan HTTP 400 dengan penyebab error INVALID_NUMBER.
  3. Jika permintaan ke endpoint CPID salah bentuk dengan cara lain, endpoint CPID HARUS menampilkan HTTP 400 dengan ERROR_CAUSE_UNSPECIFIED sebagai penyebabnya.
  4. Untuk penyebab error lainnya, kode error HTTP yang kompatibel dapat diterima. Secara khusus, HTTP 500 adalah penyebab error yang sesuai untuk setiap kegagalan internal di endpoint CPID.