Runtime Browser

Panduan ini menjelaskan cara Noxtica SDK bekerja di dalam browser pengunjung Anda — apa yang terjadi selama penilaian, bagaimana caching menjaga kecepatan, dan cara memecahkan masalah umum.

Cara Kerjanya

Saat Anda menambahkan Noxtica SDK ke halaman, ia diam-diam melakukan empat hal:

1. Autentikasi: Masuk dengan Site Key Anda menggunakan kredensial yang dikelolanya untuk Anda
2. Pengumpulan: Membaca sinyal sehari-hari yang sudah diekspos browser
3. Pengiriman: Mengirimnya ke Noxtica untuk dinilai
4. Cache: Menyimpan hasilnya secara lokal agar tidak mengulang pekerjaan di setiap kunjungan

Semua ini berjalan di latar belakang dan tidak pernah memblokir halaman Anda.

Alur Pengumpulan

Otomatis (Direkomendasikan)

Saat menggunakan data-auto-check-once, SDK menggunakan pengumpulan cerdas:

<script
	src="https://collect.noxtica.com/collector/noxtica.js"
	data-site-key="pk_prod_your_site_key"
	data-auto-init
	data-auto-check-once
	async
></script>

Menggunakan content-security-policy? Anda perlu mengizinkan Noxtica memuat dan menjalankan runtime tahan-gangguan-nya, yaitu KHAN VM. Jika tidak bisa, Noxtica tetap bekerja dengan mode pengumpulan yang lebih ringan dan perlindungan gangguan yang lebih lemah. Lihat Getting Started → Content Security Policy untuk snippet lengkapnya.

Kunjungan pertama: Penilaian lengkap dijalankan dan hasilnya disimpan dalam cache.

Kunjungan berikutnya (dalam jendela cache): Hasil dari cache dikembalikan dan kunjungan ringan dicatat. Tidak ada pekerjaan berat yang dijalankan.

Setelah jendela cache kedaluwarsa: Penilaian baru dijalankan.

Kontrol Manual

Untuk kontrol programatik, gunakan metode checkOnce():

const client = NoxticaCollector.createClient({
	siteKey: 'pk_prod_your_site_key',
});

const result = await client.checkOnce();

if (result.fromCache) {
	console.log('Using cached fingerprint');
	console.log('Next collection in:', result.nextSubmitIn, 'days');
} else {
	console.log('Fresh fingerprint collected');
}

Perilaku Caching

SDK menyimpan setiap hasil dalam cache browser agar tidak menilai ulang pengunjung yang sama di setiap tampilan halaman.

Cache Key

nox_fp_{your_site_key}

Yang Tersimpan dalam Cache

• Device ID
• Timestamp pengiriman terakhir
• Timestamp terakhir terlihat
• Skor dan level risiko sebelumnya

TTL (Time-To-Live)

TTL cache default adalah 7 hari. Ini bisa dikonfigurasi:

// Override at collection time
const result = await client.checkOnce({
	checkIntervalDays: 14, // 14 days instead of 7
});

// Or in seconds
const result = await client.checkOnce({
	ttlSeconds: 86400, // 1 day
});

Paksa Refresh

Untuk melewati cache dan mengumpulkan fingerprint baru:

const result = await client.checkOnce({
	forceRefresh: true,
});

Koordinasi Lintas Tab

Ketika pengunjung membuka beberapa tab situs Anda sekaligus, SDK memastikan mereka hanya dinilai satu kali:

• Hanya satu tab yang melakukan pekerjaan sesungguhnya
• Tab lainnya menunggu dan berbagi hasil tersebut

Ini terjadi secara otomatis — tidak perlu konfigurasi.

Event

SDK memancarkan event yang bisa Anda dengarkan:

noxtica:collected

Dipicu setelah pengumpulan berhasil atau saat mengembalikan hasil dari cache:

document.addEventListener('noxtica:collected', (e) => {
	console.log('Fingerprint ID:', e.detail.fingerprintId);
	console.log('Risk Level:', e.detail.risk_level);
	console.log('Score:', e.detail.score);
	console.log('From Cache:', e.detail.fromCache);
});

noxtica:cache-hit

Dipicu khusus ketika hasil dari cache dikembalikan:

document.addEventListener('noxtica:cache-hit', (e) => {
	console.log('Cache hit, days since submission:', e.detail.daysSinceSubmit);
});

noxtica:error

Dipicu ketika pengumpulan gagal:

document.addEventListener('noxtica:error', (e) => {
	console.log('Error source:', e.detail.source);
	console.log('Error message:', e.detail.message);
});

Variabel Global

Setelah pengumpulan, hasilnya tersedia secara global:

// After collection completes
console.log(window.noxticaResult);

// Client instance (when using auto-init)
console.log(window.noxticaClient);

// Last error (if any)
console.log(window.noxticaLastError);

Penanganan Error

Error Umum

Menangani Error Secara Manual

try {
	const result = await client.collectAndSubmit();
} catch (error) {
	if (error.message.includes('origin_mismatch')) {
		// Site key configuration issue
	} else if (error.message.includes('rate')) {
		// Back off and retry later
	}
}

Mode Pengumpulan

SDK mendukung tiga mode pengumpulan:

const client = NoxticaCollector.createClient({
	siteKey: 'pk_prod_...',
	mode: 'max', // or 'minimal', 'standard'
});

Mode Terlindungi (KHAN VM)

Bagian tersulit dari melawan bot adalah bahwa apa pun yang berjalan di browser pada prinsipnya bisa dilihat dan diedit. Penyerang yang gigih bisa membaca kode halaman, mencari tahu apa yang diukur, dan diam-diam memberikan jawaban palsu.

KHAN VM menaikkan biayanya. Alih-alih membiarkan pengumpulan terbuka sebagai kode yang bisa dibaca di halaman, Noxtica menjalankan bagian sensitifnya di dalam runtime yang disegel dan tersandbox. Logika yang menentukan apa yang diukur tidak terlihat jelas oleh penyerang untuk dipelajari dan ditulis ulang, dan hasil yang dihasilkannya disegel sebelum meninggalkan browser — sehingga jauh lebih sulit untuk dimanipulasi atau diputar ulang.

Apa yang dibantu KHAN VM:

• Hasil tahan gangguan — penilaian disegel di dalam sandbox sebelum dikirim, sehingga skrip lain di halaman tidak bisa mengubah atau memutar ulangnya diam-diam.
• Lebih sulit direkayasa balik — logika pengumpulan tetap tersembunyi di dalam runtime daripada bisa dibaca di developer tools browser.
• Perlindungan replay — setiap hasil bersifat sekali pakai dan diverifikasi, sehingga respons yang ditangkap tidak bisa begitu saja digunakan ulang untuk berpura-pura menjadi pengunjung bersih.

Batas yang jujur — apa yang tidak dilakukannya:

• Ini adalah fitur tahan gangguan, bukan enkripsi end-to-end.
• Jika halaman Anda sendiri dikompromikan (misalnya, karena kerentanan cross-site scripting), penyerang di halaman tersebut bisa melihat sinyal browser mentah yang sama yang dilihat Noxtica. KHAN VM melindungi pemrosesan dan hasilnya, bukan halaman di sekitarnya.

KHAN VM diaktifkan dari sisi server dan tidak memerlukan perubahan pada integrasi Anda. Jika tidak bisa dimulai — misalnya, karena content-security-policy memblokirnya — Noxtica mundur ke mode pengumpulan yang lebih ringan agar deteksi tetap bekerja, hanya dengan perlindungan gangguan yang lebih lemah.

Dukungan Browser

SDK mendukung browser modern:

Browser yang lebih lama mungkin memiliki akurasi sinyal yang berkurang tetapi tetap berfungsi.

Mode Debug

Aktifkan logging debug untuk memecahkan masalah:

// Before SDK loads
globalThis.NOXTICA_DEBUG = true;

// Or per-client
const client = NoxticaCollector.createClient({
	siteKey: 'pk_prod_...',
	debug: true,
});

// Or via script attribute
<script src="..." data-debug></script>;

Mode debug mencatat:

• Kemajuan pengumpulan
• Siklus hidup token
• Cache hit dan miss
• Setiap error yang ditemui

Catatan: Mode debug bersifat diam secara default di produksi. Tidak ada output konsol kecuali diaktifkan secara eksplisit.

Pertimbangan Penyimpanan

Penyimpanan Browser

SDK menggunakan penyimpanan lokal browser untuk menyimpan cache hasil. Jika tidak tersedia (misalnya, dalam mode penjelajahan pribadi atau dengan penyimpanan dinonaktifkan):

• Deteksi tetap bekerja
• Setiap pemuatan halaman menjalankan penilaian baru
• Koordinasi lintas tab mungkin berkurang

Tanpa Cookie

SDK tidak menggunakan cookie. Semua yang dibutuhkannya tersimpan di penyimpanan lokal browser.

Dampak Performa

Kunjungan Pertama

Pengumpulan berjalan secara asinkron dan tidak memblokir rendering halaman.

Kunjungan Berikutnya (Cache Hit)

Pemecahan Masalah

Fingerprint Tidak Terkumpul

1. Periksa konsol browser untuk error
2. Pastikan Site Key cocok persis dengan domain Anda (termasuk https://)
3. Pastikan domain diaktifkan di Backoffice
4. Aktifkan mode debug untuk melihat log terperinci

”WebAssembly blocked by Content Security Policy”

Jika Anda melihat peringatan ini di konsol browser, content-security-policy halaman Anda memblokir runtime tahan gangguan (KHAN VM). Deteksi tetap bekerja dalam mode yang lebih ringan, tapi Anda mendapatkan perlindungan terkuat dengan mengizinkannya.

Gunakan snippet berikut untuk mengizinkan Noxtica memuat dan berjalan:

Content-Security-Policy: script-src 'self' 'wasm-unsafe-eval' https://collect.noxtica.com; connect-src 'self' https://collect.noxtica.com

Lihat Getting Started → Content Security Policy untuk referensi lengkap.

Device ID Berbeda di Perangkat yang Sama

Ini bisa terjadi ketika:

• Data tersimpan browser dihapus
• Profil browser berubah
• Pengunjung menggunakan mode pribadi/incognito
• Browser mengalami pembaruan besar

Ini hal yang wajar — pengenalan beradaptasi seiring perangkat berubah dari waktu ke waktu.

Pengumpulan Terlalu Lama

1. Periksa tab jaringan untuk respons API yang lambat
2. Pertimbangkan menggunakan mode: 'minimal' untuk pengumpulan yang lebih cepat
3. Pastikan SDK dimuat dengan atribut async

Event Tidak Terpicu

1. Pastikan Anda mendengarkan sebelum SDK berjalan
2. Periksa bahwa atribut auto-init sudah benar
3. Pastikan tidak ada error JavaScript yang memblokir eksekusi

Praktik Terbaik

1. Gunakan data-auto-check-once daripada data-auto-collect untuk meminimalkan pengumpulan yang berulang

2. Muat SDK secara asinkron dengan atribut async agar tidak memblokir pemuatan halaman

3. Dengarkan event daripada melakukan polling pada window.noxticaResult

4. Jangan ubah TTL tanpa alasan — interval default 7 hari sudah dioptimalkan untuk sebagian besar kasus penggunaan

5. Tangani error dengan baik — kegagalan pengumpulan tidak boleh merusak halaman Anda

Langkah Berikutnya

• Getting Started - Panduan pengaturan awal
• Backend Integration - Pencarian perangkat di sisi server