Pemecahan Masalah

Halaman ini membahas masalah umum yang muncul selama integrasi TRACIO beserta solusinya. TRACIO adalah layanan cloud terkelola, sehingga sebagian besar masalah bersifat client-side (skrip diblokir, cookie, fitur privasi browser) dan bukan masalah infrastruktur.

Permintaan yang Diblokir atau Ditolak CORS

Gejala

Skrip agen atau permintaan identifikasi gagal dimuat, atau konsol browser menampilkan error CORS terhadap edge.tracio.ai.

Penyebab dan Solusi

1. Origin tidak masuk allowlist untuk key Anda

Setiap public key dapat dikunci ke sekumpulan origin yang diizinkan. Jika origin situs Anda tidak ada dalam allowlist, edge akan menolak permintaan (403). Tambahkan origin Anda di bawah Request Filtering pada dashboard, atau pastikan key yang Anda gunakan tidak dikunci ke origin situs lain.

2. Ad blocker atau CSP memblokir permintaan

Ekstensi privasi (uBlock Origin, AdBlock) atau Content-Security-Policy yang ketat dapat memblokir skrip agen atau permintaan jaringannya. SDK menampilkan ini sebagai error blocked (lihat Penanganan Error). Untuk mempersulit pemblokiran, sajikan agen dari subdomain first-party menggunakan opsi scriptUrl / endpoint.

3. Endpoint / region salah

Pastikan Anda mengarah ke endpoint yang benar. Saat Anda menetapkan region, SDK berkomunikasi dengan edge.us.tracio.ai atau edge.eu.tracio.ai; jika tidak ditetapkan, ia menggunakan edge.tracio.ai.

Skor Confidence Rendah

Gejala

Skor confidence secara konsisten di bawah 0,90 untuk pengunjung yang kembali.

Kemungkinan Penyebab dan Solusi

1. Cookie tidak persisten

Cookie _vid_t mungkin tidak terpasang dengan benar. Periksa di browser:

// In browser console
document.cookie.split(";").filter((c) => c.includes("_vid_t"))

Jika cookie tidak ada, lihat bagian Cookie Tidak Persisten di bawah.

2. Workspace baru

Workspace yang benar-benar baru memiliki basis data pengunjung yang kosong, sehingga semua pengunjung tampak sebagai "baru" dengan confidence sekitar 0,90. Setelah 24-48 jam, pengunjung yang kembali dikenali dengan confidence yang lebih tinggi.

3. Mode incognito/penjelajahan privat

Dalam mode incognito, cookie dan localStorage dihapus saat sesi berakhir. TRACIO beralih ke pencocokan berbasis sinyal saja, yang memiliki confidence lebih rendah (biasanya 0,85-0,95).

4. Browser dengan anti-fingerprinting agresif

Brave, Firefox (mode ketat), dan Safari (ITP) mengubah atau memblokir sebagian sinyal browser. Hal ini mengurangi kumpulan sinyal yang tersedia untuk pencocokan. TRACIO mendeteksi browser ini dan menyesuaikan confidence sesuai kondisi.

Mendiagnosis Confidence Rendah

Periksa identifikasi di dashboard (Visitors / Events), atau bertindak berdasarkan pengiriman webhook, yang membawa identification.confidence, identification.incognito, dan verdict bot untuk setiap event.

False Positive Deteksi Bot

Gejala

Pengunjung manusia yang sah ditandai sebagai bot.

Kemungkinan Penyebab dan Solusi

1. Ekstensi browser yang mengubah properti navigator

Beberapa ekstensi privasi mengubah navigator.userAgent, navigator.platform, atau properti lainnya. Hal ini dapat memicu detektor tampering, tetapi seharusnya tidak memicu deteksi bot dengan sendirinya.

Periksa field bot.type untuk melihat kelas deteksi mana yang aktif (lihat Tipe bot untuk kosakata lengkapnya):

Pada paket Business dan Enterprise, array reasons di webhook menyebutkan kelas observasi di balik keputusan — ini cara tercepat untuk memahami sebuah false positive. Lihat Kode alasan.

2. Lingkungan korporat dengan rendering perangkat lunak

Lingkungan Citrix, VDI, dan terminal server merender tanpa GPU sungguhan, sehingga menyerupai runtime headless. Jika pengguna Anda beroperasi di lingkungan ini, terapkan kebijakan yang lebih lunak ketika webhook menunjukkan tipe bot headless:

// `event` is the webhook delivery body (/docs/webhooks)
if (event.bot?.result === "bot" && event.bot.type === "headless") {
  // VDI and remote-desktop users render without a real GPU and can trip the
  // headless classification — consider applying a softer policy for these.
}

3. Pengujian otomatis di produksi

Jika tim QA Anda menjalankan pengujian Selenium/Playwright terhadap produksi, pengujian tersebut akan terdeteksi dengan benar sebagai bot. Gunakan key terpisah untuk trafik pengujian.

Cookie Tidak Persisten

Gejala

Cookie _vid_t menghilang di antara kunjungan, sehingga setiap kunjungan tampak sebagai pengunjung "baru".

Kemungkinan Penyebab dan Solusi

1. Situs non-HTTPS

Cookie _vid_t menggunakan flag Secure dan hanya dipasang melalui HTTPS. Pastikan situs Anda menggunakan HTTPS.

2. Pemuatan lintas situs

TRACIO menetapkan SameSite=Lax pada cookie. Jika agen dimuat dalam konteks lintas situs yang ketat, cookie dapat diblokir. Menyajikan agen dari subdomain first-party (melalui scriptUrl / endpoint) menjaganya tetap same-site.

3. Safari ITP

Intelligent Tracking Prevention (ITP) pada Safari dapat membatasi masa hidup cookie yang ditetapkan klien. TRACIO juga menerbitkan _vid_t di sisi server melalui header Set-Cookie dan mencerminkan UID ke localStorage, sehingga identitas tetap bertahan bahkan saat cookie dibatasi.

4. Browser menghapus cookie

Beberapa browser (Brave, Firefox Focus) menghapus cookie saat sesi berakhir. Pengguna dengan pengaturan privasi agresif akan selalu tampak sebagai pengunjung baru.

Latensi Tinggi

Gejala

tracio.getResult() membutuhkan waktu yang terasa lebih lama untuk selesai dibandingkan pada perangkat dan jaringan uji Anda yang lain.

Kemungkinan Penyebab dan Solusi

1. Jaringan lambat ke edge

Periksa latensi round-trip ke edge regional Anda:

curl -o /dev/null -s -w "DNS: %{time_namelookup}s\nConnect: %{time_connect}s\nTLS: %{time_appconnect}s\nTotal: %{time_total}s\n" https://edge.tracio.ai/health

2. Pengumpulan memakan waktu terlalu lama

Pada perangkat berdaya rendah, pengumpulan memakan waktu lebih lama. Setiap pemeriksaan yang berpotensi lambat dibatasi oleh timeout-nya sendiri, jadi pengumpulan tidak pernah memblokir tanpa batas — pemeriksaan yang kehabisan waktu cukup dilaporkan sebagai tidak tersedia dan identifikasi berlanjut tanpanya.

Pengumpulan Tidak Lengkap

Gejala

Identifikasi selesai, tetapi confidence lebih rendah dari yang diharapkan pada browser atau kelas perangkat tertentu.

Penjelasan

Tidak setiap pemeriksaan bisa berjalan di setiap lingkungan: CSP yang ketat, batasan platform, dan fitur privasi browser membuat sebagian di antaranya tidak tersedia. Ini wajar dan ditangani dengan baik — confidence dihitung dari apa yang benar-benar terkumpul, itulah sebabnya browser yang diperketat secara sah teridentifikasi dengan confidence lebih rendah daripada browser standar.

Tidak ada tindakan yang diperlukan dari sisi Anda. Jika confidence konsisten rendah pada sebagian besar trafik Anda, hubungi support dengan menyertakan requestId — hal itu didiagnosis dari catatan sisi server, bukan dari browser.

Mendapatkan Bantuan

Jika Anda menemukan masalah yang tidak tercakup di sini:

1. Aktifkan diagnostik verbose dengan opsi SDK debug: true
2. Periksa event di dashboard (Visitors / Events)
3. Tinjau Penanganan Error untuk kode error SDK
4. Tinjau Webhooks untuk payload sisi server
5. Hubungi dukungan dengan requestId dari identifikasi yang terpengaruh