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 harus membuat ID paket operator (CPID) tanpa menemukan MSISDN pengguna. Selanjutnya, kami menjelaskan mekanisme yang membentuk CPID.

Alur Panggilan CPID

Gambar 2: Alur panggilan untuk menetapkan 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 yang aktif. Untuk MVNO, Google akan menggunakan SPN dan GID1 untuk menentukan MVNO
  2. Klien mengeluarkan permintaan HTTP GET ke endpoint CPID. Operator MUNGKIN mendukung pengiriman permintaan melalui HTTPS.
  3. Operator DAPAT menggunakan fungsi Deep Packet Inspection untuk mengidentifikasi permintaan dan memasukkan nomor telepon pengguna ke permintaan sebagai header HTTP.
  4. Endpoint CPID menerima permintaan, membuat CPID, dan menampilkan CPID ke UE dengan waktu aktif (TTL) yang menunjukkan berapa lama UE dapat menggunakan CPID ini.

Operator DAPAT juga 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 SHALL akan memberikan informasi berikut kepada Google sebagai bagian dari proses orientasi:

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

Format permintaannya adalah: GET CPID_URL Karena 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, fungsi ini HARUS dapat menangani permintaan yang berisi parameter.

Permintaan ke endpoint CPID MUNGKIN 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 disediakan 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 Oke. Isi respons HARUS berisi instance CPIDResponse.

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

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

Pembuatan CPID

Cara yang DIREKOMENDASIKAN untuk endpoint CPID guna membuat CPID adalah:

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

Endpoint CPID menggabungkan MSISDN, bahasa yang dikirim oleh klien dalam header Bahasa Terima, dan stempel waktu resolusi tinggi serta mengenkripsinya melalui AES menggunakan kunci secret. Stempel waktu SEHARUSNYA sesuai dengan waktu CPID berakhir. Output yang dienkripsi dienkode dengan Base64. Selain itu, saat digunakan oleh CPID di URL, CPID harus dienkode ke URL untuk menangani karakter khusus (/+=) yang digunakan di Base64. Khususnya saat GTAF memanggil DPA atau saat DPA memanggil API Berbagi Data Seluler, CPID HARUS dienkode ke URL.

Bergantung pada situasi operator tertentu, mungkin akan sulit untuk menerapkan endpoint CPID. Tantangan tertentu yang sering dihadapi adalah mendapatkan akses ke MSISDN di endpoint CPID. Dengan senang hati kami berbagi pelajaran dari operator orientasi yang telah dipelajari. Hubungi kami jika Anda menghadapi tantangan.

Penyimpanan CPID

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

  1. Saat DPA menerima panggilan dari GTAF untuk mengetahui 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 memberi stempel waktu masa berlaku.

Persyaratan Ketersediaan dan Kapasitas

Jika klien tidak dapat mengambil CPID, mereka tidak dapat mengakses informasi apa pun dari Mobile Data Plan API. Karena alasan ini, operator SHALL akan mengambil tindakan yang diperlukan untuk memastikan ketersediaan endpoint CPID. Langkah-langkah tersebut termasuk memiliki beberapa instance endpoint CPID dan fungsi DPI serta memiliki redundansi fisik, situs, dan jaringan untuk kedua fungsi, serta memastikan bahwa resource dan kapasitas sistem sudah memadai. Selain itu, endpoint CPID serta fungsi DPI yang memasukkan header harus memiliki kapasitas yang cukup untuk menangani pemuatan semua klien Google yang meminta CPID. Endpoint CPID dapat menggunakan nilai yang lebih besar di kolom ttlSeconds untuk mengurangi frekuensi menghasilkan 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 habis masa berlakunya, termasuk pembuatan dan waktu habis masa berlaku CPID, kami akan memastikan bahwa endpoint CPID berfungsi sebagaimana didesain.

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

Endpoint CPID HARUS menampilkan hal berikut bergantung pada skenarionya:

  1. Jika permintaan CPID diterima untuk pengguna yang bukan milik jaringan operator (misalnya, pengguna milik operator lain tetapi roaming di jaringan yang dilayani oleh endpoint CPID ini) atau belum memilih untuk berbagi informasi paket data dengan 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 format permintaan ke endpoint CPID salah 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. Khususnya, HTTP 500 adalah penyebab error yang cocok untuk kegagalan internal di endpoint CPID.