Runtime Pelayar

Panduan ini menerangkan cara SDK Noxtica berfungsi di dalam pelayar pelawat anda — apa yang berlaku semasa penilaian, cara caching memastikan keadaan pantas, dan cara menyelesaikan masalah biasa.

Cara Ia Berfungsi

Apabila anda menambah SDK Noxtica ke halaman anda, ia secara senyap melakukan empat perkara:

1. Sahkan: Log masuk dengan Site Key anda menggunakan kelayakan yang diuruskannya untuk anda
2. Kumpul: Membaca isyarat biasa yang pelayar sudah terdedah
3. Hantar: Menghantar isyarat itu kepada Noxtica untuk diberi skor
4. Cache: Menyimpan hasilnya secara tempatan supaya ia tidak mengulangi kerja pada setiap kunjungan

Semua ini berjalan di latar belakang dan tidak pernah menghalang halaman anda.

Aliran Pengumpulan

Automatik (Disyorkan)

Apabila menggunakan data-auto-check-once, SDK menggunakan pengumpulan pintar:

<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 membenarkan Noxtica memuatkan dan menjalankan masa jalannya yang tahan gangguan, KHAN VM. Jika tidak boleh, Noxtica terus berfungsi dengan bentuk pengumpulan yang lebih ringan dan perlindungan gangguan yang lebih lemah. Lihat Memulakan → Content Security Policy untuk coretan tepat.

Kunjungan pertama: Penilaian penuh dijalankan dan hasilnya dicache.

Kunjungan seterusnya (dalam tetingkap cache): Hasil yang dicache dikembalikan dan kunjungan ringan direkodkan. Tiada kerja berat dijalankan.

Selepas tetingkap cache tamat tempoh: Penilaian segar dijalankan.

Kawalan Manual

Untuk kawalan aturcara, gunakan kaedah 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');
}

Tingkah Laku Caching

SDK menyimpan setiap hasil dalam pelayar supaya ia tidak menilai semula pelawat yang sama pada setiap paparan halaman.

Kunci Cache

nox_fp_{your_site_key}

Apa yang Dicache

• ID Peranti
• Cap masa penyerahan terakhir
• Cap masa dilihat terakhir
• Skor dan tahap risiko sebelumnya

TTL (Jangka Masa Hidup)

TTL cache lalai ialah 7 hari. Ini boleh 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 Muat Semula

Untuk memintas cache dan mengumpul cap jari baharu:

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

Penyelarasan Merentas Tab

Apabila pelawat membuka beberapa tab tapak anda serentak, SDK memastikan mereka hanya dinilai sekali:

• Hanya satu tab yang melakukan kerja sebenar
• Tab lain menunggu dan berkongsi hasil itu

Ini berlaku secara automatik — tiada konfigurasi diperlukan.

Acara

SDK menghantar acara yang boleh anda dengar:

noxtica:collected

Dilepaskan selepas pengumpulan berjaya atau apabila hasil yang dicache dikembalikan:

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

Dilepaskan khusus apabila hasil yang dicache dikembalikan:

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

noxtica:error

Dilepaskan apabila pengumpulan gagal:

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

Pemboleh Ubah Global

Selepas pengumpulan, hasil boleh didapati 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);

Pengendalian Ralat

Ralat Biasa

Mengendalikan Ralat 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
	}
}

Mod Pengumpulan

SDK menyokong tiga mod pengumpulan:

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

Mod Terlindung (KHAN VM)

Bahagian tersukar dalam melawan bot ialah bahawa apa sahaja yang berjalan dalam pelayar, pada dasarnya, kelihatan dan boleh disunting. Penyerang yang gigih boleh membaca kod halaman, mengetahui apa yang sedang diukur, dan secara senyap menghantar balik jawapan palsu.

KHAN VM meningkatkan kos itu. Daripada membiarkan pengumpulan terdedah secara terbuka sebagai kod yang boleh dibaca di halaman, Noxtica menjalankan bahagian sensitif di dalam masa jalan yang tertutup dan berpasir. Logik yang memutuskan apa yang hendak diukur tidak tersedia secara jelas untuk penyerang mengkaji dan menulis semula, dan hasil yang dihasilkan ditutup sebelum meninggalkan pelayar — jadi jauh lebih sukar untuk diganggu atau dimainkan semula.

Apa yang KHAN VM bantu:

• Hasil tahan gangguan — penilaian ditutup di dalam kotak pasir sebelum dihantar, jadi skrip lain di halaman tidak boleh mengubah atau memainkan semulanya secara senyap.
• Lebih sukar untuk kejuruteraan terbalik — logik pengumpulan kekal tersembunyi di dalam masa jalan dan bukannya boleh dibaca dalam alat pembangun pelayar.
• Perlindungan ulang tayang — setiap hasil adalah satu kali guna dan disahkan, jadi respons yang ditangkap tidak boleh digunakan semula begitu sahaja untuk meniru pelawat bersih.

Had yang jujur — apa yang tidak dilakukannya:

• Ia adalah ciri rintangan gangguan, bukan penyulitan hujung ke hujung.
• Jika halaman anda sendiri dikompromi (contohnya, oleh kelemahan skrip silang tapak), penyerang di halaman itu boleh melihat isyarat pelayar mentah yang sama yang Noxtica lihat. KHAN VM melindungi pemprosesan dan hasilnya, bukan halaman di sekelilingnya.

KHAN VM dihidupkan dari sisi pelayan dan tidak memerlukan perubahan pada integrasi anda. Jika tidak boleh dimulakan — contohnya, kerana content-security-policy menyekatnya — Noxtica beralih kepada bentuk pengumpulan yang lebih ringan supaya pengesanan terus berfungsi, hanya dengan perlindungan gangguan yang lebih lemah.

Sokongan Pelayar

SDK menyokong pelayar moden:

Pelayar yang lebih lama mungkin mempunyai ketepatan isyarat yang berkurang tetapi akan tetap berfungsi.

Mod Debug

Aktifkan log debug untuk menyelesaikan 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>;

Mod debug mencatat:

• Kemajuan pengumpulan
• Kitar hidup token
• Cache hit dan miss
• Sebarang ralat yang ditemui

Nota: Mod debug adalah senyap secara lalai dalam pengeluaran. Tiada output konsol dipaparkan melainkan diaktifkan secara eksplisit.

Pertimbangan Storan

Storan Pelayar

SDK menggunakan storan tempatan pelayar untuk men-cache hasil. Jika tidak tersedia (contohnya, dalam pelayaran peribadi atau storan dinyahaktifkan):

• Pengesanan masih berfungsi
• Setiap muat halaman menjalankan penilaian segar
• Penyelarasan merentas tab mungkin berkurang

Tiada Kuki

SDK tidak menggunakan kuki. Semua yang diperlukannya disimpan dalam storan tempatan pelayar.

Kesan Prestasi

Kunjungan Pertama

Pengumpulan berjalan secara tak segerak dan tidak menghalang pemaparan halaman.

Kunjungan Seterusnya (Cache Hit)

Penyelesaian Masalah

Cap Jari Tidak Dikumpul

1. Semak konsol pelayar untuk ralat
2. Sahkan Site Key sepadan tepat dengan domain anda (termasuk https://)
3. Pastikan domain diaktifkan dalam Backoffice
4. Aktifkan mod debug untuk melihat log terperinci

”WebAssembly blocked by Content Security Policy”

Jika anda melihat amaran ini dalam konsol pelayar, content-security-policy halaman anda sedang menyekat masa jalan tahan gangguan (KHAN VM). Pengesanan terus berfungsi dalam mod yang lebih ringan, tetapi anda akan mendapat perlindungan terkuat dengan membenarkannya.

Gunakan coretan di bawah untuk membenarkan Noxtica memuatkan dan berjalan:

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

Lihat Memulakan → Content Security Policy untuk rujukan penuh.

ID Peranti Berbeza pada Peranti Yang Sama

Ini boleh berlaku apabila:

• Data storan pelayar dibersihkan
• Profil pelayar berubah
• Pelawat menggunakan mod persendirian/inkognito
• Pelayar menjalani kemas kini besar

Ini adalah tingkah laku yang dijangkakan — pengenalan menyesuaikan diri apabila peranti berubah dari masa ke masa.

Pengumpulan Mengambil Masa Terlalu Lama

1. Semak tab rangkaian untuk respons API yang perlahan
2. Pertimbangkan menggunakan mode: 'minimal' untuk pengumpulan lebih pantas
3. Pastikan SDK dimuatkan dengan atribut async

Acara Tidak Dilepaskan

1. Pastikan anda mendengar sebelum SDK dijalankan
2. Semak bahawa atribut auto-init betul
3. Sahkan tiada ralat JavaScript yang menghalang pelaksanaan

Amalan Terbaik

1. Gunakan data-auto-check-once dan bukannya data-auto-collect untuk meminimumkan pengumpulan berulang

2. Muatkan SDK secara tak segerak dengan atribut async untuk mengelak halangan muat halaman

3. Dengar acara dan bukannya mengundi window.noxticaResult

4. Jangan timpa TTL tanpa keperluan — selang lalai 7 hari dioptimumkan untuk kebanyakan kes penggunaan

5. Tangani ralat dengan baik — kegagalan pengumpulan tidak sepatutnya merosakkan halaman anda

Langkah Seterusnya

• Memulakan - Panduan persediaan awal
• Integrasi Backend - Carian peranti sisi pelayan