partner_user_id & penautan 1:1

Apa itu

Id Anda sendiri untuk pengguna yang sedang memberi izin. Ia dikirim di URL authorize dan wajib — layar consent menolak permintaan tanpa itu.

Gunanya dua. Pertama, ia yang membuat grant bertahan melewati pemasangan ulang aplikasi. Kedua, ia dikembalikan apa adanya di webhook, sehingga grant.revoked bisa Anda petakan kembali ke pelanggan Anda tanpa perlu tahu siapa mereka di Tracive.

Dari mana asalnya

Anda tidak mengambilnya dari Tracive. Kami tidak menerbitkannya dan tidak punya endpoint untuk memintanya. Nilainya berasal dari tabel pengguna Anda sendiri, dan Anda sudah memilikinya sebelum alur OAuth dimulai — begitu pelanggan login ke aplikasi Anda, Anda sudah tahu siapa mereka.

Pelanggan login ke aplikasi Anda   → Anda tahu ini pelanggan #8842
Aplikasi Anda memanggil authorize  → kirim partner_user_id = "cust-8842-xyz"
Tracive menyimpannya apa adanya    → dipakai sebagai kunci tautan 1:1
Webhook grant.revoked datang       → membawa "cust-8842-xyz" kembali
Anda langsung tahu pelanggan mana  → tanpa tabel pemetaan tambahan

Ada dua tempat Anda mengisinya:

SDK Android	Parameter partnerUserId pada TraciveMode.OAuth(…)
Simulator consent	Field partner_user_id di halaman detail OAuth client

TraciveMode.OAuth(
  clientId = "trcvc_…",
  redirectUri = "…",
  scopes = listOf(TraciveScopes.SCAMMER_CHECK),
  partnerUserId = internalUserId,   // ← dari sistem Anda
  clientType = ClientType.PUBLIC,
)

Versi lama dokumentasi ini pernah menyarankan mengirim null bila integrasi Anda tidak punya akun pengguna. Itu keliru. SDK menolaknya di sisi klien sebelum menyentuh jaringan, jadi tidak ada redirect sama sekali: aplikasi Anda tidak menerima apa pun untuk ditangani dan tidak ada log server yang mencatat percobaannya. Bila integrasi Anda memang tidak punya akun pengguna, tetap buat id per-perangkat yang stabil dan simpan di server Anda.

Bukan user id Tracive

Keduanya adalah dua sisi dari satu tautan, bukan nilai yang sama. Grant-lah yang menghubungkan mereka.

uid Tracive	Milik kami. Identitas akun yang login di aplikasi Tracive. Tidak pernah meninggalkan sistem kami.
sub (PPID)	Yang Anda terima. Turunan dari uid, berbeda untuk setiap client, jadi dua partner tidak bisa saling mencocokkan penggunanya.
partner_user_id	Milik Anda. Yang Anda kirim. Tersimpan apa adanya dan dikembalikan di webhook.

Di dalam aplikasi Tracive, partner_user_id hanyalah nilai titipan: aplikasi menerimanya dari aplikasi Anda lewat deep link dan meneruskannya. Aplikasi Tracive tidak pernah membacanya sebagai identitas dirinya sendiri, dan pengguna Tracive yang sedang login bisa saja berbeda orang dari yang Anda kira.

Aturan satu-lawan-satu

Satu partner_user_id terikat ke satu akun Tracive, per client. Aturan ini ditegakkan saat consent, bukan saat penukaran token.

Dua arah supersede

· Akun Tracive berbeda, id Anda sama. Pelanggan Anda memberi izin memakai akun Tracive lain. Grant lama dicabut, dan Anda menerima grant.superseded.
· Akun Tracive sama, id Anda berbeda. Anda mengganti skema id pelanggan. Grant lama dicabut dan pemetaan lamanya dihapus, sehingga tidak ada tautan menggantung.

Keduanya terjadi di dalam satu transaksi bersama penerbitan code, jadi tidak ada momen di mana dua grant hidup untuk pasangan yang sama.

Memilih nilainya

Jangan memakai nomor telepon, email, atau nomor rekening. Nilai ini tersimpan apa adanya dan dikembalikan di webhook, jadi memakai data pribadi di sini berarti mengirimkannya ke kami tanpa alasan.

Sejak September 2026 aturan itu ditegakkan, bukan sekadar imbauan. Permintaan authorize ditolak bila nilainya:

mengandung @	Dianggap alamat email.
berbentuk nomor telepon	Diawali + (format E.164), atau nomor seluler Indonesia 08… / 628…. Spasi, tanda hubung, kurung dan titik diabaikan sebelum diperiksa.
lebih dari 200 karakter	Terlalu panjang untuk sebuah id.
kosong	Wajib diisi.

UUID lolos, begitu juga nomor pelanggan numerik (misalnya CIF) yang bukan berbentuk nomor telepon. Nomor rekening tidak bisa dibedakan dari nomor pelanggan hanya dari bentuknya, jadi tidak ditolak otomatis — tetapi tetap jangan dikirim.

· Pakai id internal yang buram dan stabil, misalnya UUID pelanggan Anda.
· Bila kunci utama Anda memang nomor rekening atau nomor telepon, jangan kirim itu. Buat pemetaan sendiri — satu UUID per pelanggan, disimpan di tabel Anda — lalu kirim UUID-nya.

Menjaganya stabil

Nilainya harus selalu sama untuk pelanggan yang sama, selamanya. Ini bagian yang paling sering terlewat.

Bila aplikasi Anda membangkitkan UUID baru setiap kali dipasang, setiap pemasangan ulang terlihat seperti pelanggan baru bagi kami — dan aturan supersede arah kedua akan mencabut grant lama setiap kali. Pelanggan Anda diminta memberi izin berulang-ulang, dan Anda menerima banjir grant.superseded tanpa sebab yang jelas.

Bangkitkan sekali, simpan di sisi server Anda terhadap akun pelanggan — bukan di penyimpanan lokal aplikasi. Justru itu yang membuat grant bertahan melewati pemasangan ulang.