Memulakan

Panduan ini akan membantu anda menambah Noxtica ke aplikasi web anda hanya dalam beberapa minit.

Prasyarat

• Akaun Noxtica (minta akses melalui hubungi)
• Site Key anda (disediakan selepas persediaan akaun)

Integrasi Pantas

Setelah akaun anda disediakan dan Site Key sudah ada, tambah pengumpul kami ke HTML anda — itulah keseluruhan pemasangannya.

Pengumpulan Automatik (Disyorkan)

Cara paling mudah untuk bermula adalah membiarkan Noxtica berjalan sendiri, menggunakan mod jalankan-sekali:

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

Ini akan:

• Menilai pelawat pada kunjungan pertama mereka
• Menggunakan semula hasil itu untuk kunjungan berulang dalam tetingkap cache (lalai: 7 hari)
• Merekodkan kunjungan balik secara senyap tanpa mengulangi penilaian penuh
• Menyelaraskan merentas tab terbuka supaya pelawat hanya dinilai sekali

Hasil boleh didapati melalui:

// Listen for results
document.addEventListener('noxtica:collected', function (e) {
	console.log('Fingerprint collected:', e.detail);
	console.log('Risk score:', e.detail.score);
	console.log('Risk level:', e.detail.risk_level);
});

// Or access directly after collection
console.log(window.noxticaResult);

Pengumpulan Manual

Untuk kawalan lebih, gunakan JavaScript API:

<script src="https://collect.noxtica.com/collector/noxtica.js"></script>
<script>
	// Create a client with your Site Key
	const client = NoxticaCollector.createClient({
		siteKey: 'pk_prod_your_site_key_here',
	});

	// Collect and submit in one call
	client.collectAndSubmit().then((result) => {
		console.log('Risk score:', result.score);
		console.log('Risk level:', result.risk_level);
		console.log('Flags:', result.flags);
	});
</script>

Pengumpulan Pintar dengan checkOnce()

Untuk jejak kaki paling ringan, gunakan checkOnce() — ia menghormati selang pengumpulan yang anda konfigurasikan di pelayan, supaya pelawat tidak dinilai lebih kerap dari yang perlu:

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

// Only collects if outside the check interval window (default: 7 days)
// Otherwise records a visit and returns cached result
const result = await client.checkOnce();

if (result.fromCache) {
	console.log('Using cached result, next collection in:', result.nextSubmitIn, 'days');
} else {
	console.log('Fresh collection submitted');
}
console.log('Risk level:', result.risk_level);

Prestasi & Kesan Terhadap Tapak

Pengumpul direka untuk mempunyai kesan minimum pada muat halaman dan latensi yang kelihatan oleh pengguna:

Cara kami menjaganya ringan:

• Atribut skrip async — pengumpul dimuatkan di latar belakang dan tidak pernah melambatkan halaman anda daripada kelihatan atau boleh berinteraksi.
• Mod jalankan-sekali (data-auto-check-once) — selepas penilaian pertama, kunjungan berulang dalam tetingkap cache hanya menghantar ping kunjungan yang sangat kecil (~150 bait).
• Penyelarasan merentas tab — berbilang tab terbuka diselesaikan kepada satu penilaian.
• Tercache selepas muat pertama — KHAN VM yang tahan gangguan dicache oleh pelayar, jadi ia dimuatkan serta-merta pada kunjungan berikutnya.
• Pemprosesan latar belakang di mana disokong, supaya kerja kekal di luar thread utama dan halaman anda kekal responsif.

Jika anda melihat kelambatan selepas menambah SDK, tangkap profil dengan await client.collectAndSubmit({ telemetry: true }) — result.telemetry yang dikembalikan mengandungi pecahan masa.

Kotak Pasir lwn. Pengeluaran

Anda akan mempunyai dua Site Key: satu untuk pembangunan dan pementasan, satu untuk pengeluaran. Setiap satu berjalan di bawah dasar tersendiri dan menyimpan data sepenuhnya berasingan.

Sentiasa tukar Site Key mengikut persekitaran. Jangan pernah gunakan kunci pk_sand_* dalam trafik pengeluaran — data kotak pasir tidak akan muncul dalam papan pemuka pengeluaran anda dan pemarkahan risiko akan terlalu permisif. Sebaliknya, menggunakan kunci pk_prod_* dalam pembangunan menghabiskan bajet had kadar pengeluaran.

Corak yang lazim:

<script>
	// Pick the key by hostname; fall back to sandbox in dev.
	const KEY = location.hostname === 'www.example.com' ? 'pk_prod_REPLACE_ME' : 'pk_sand_REPLACE_ME';
	const s = document.createElement('script');
	s.src = 'https://collect.noxtica.com/collector/noxtica.js';
	s.async = true;
	s.dataset.siteKey = KEY;
	s.dataset.autoInit = '';
	s.dataset.autoCheckOnce = '';
	document.head.appendChild(s);
</script>

Keserasian Pengurus Tag

Pengumpul berfungsi di dalam Google Tag Manager, Adobe Launch, Tealium, dan Segment, TETAPI dengan kaveat:

Disyorkan (lebih baik): tambah skrip terus ke HTML anda, sejurus sebelum </body> atau dalam <head> dengan async. Bermula seawal mungkin memberi pengumpul permulaan terbaik, supaya ia sedia pada masa pelawat berinteraksi.

Pengurus tag — berfungsi, dengan kaveat:

• ✅ Kebanyakan pengurus tag moden (GTM Custom HTML, Adobe Launch Custom Code, Segment Custom Source) berjaya memuatkan pengumpul.
• ⚠️ Pintu persetujuan yang menyekat skrip sehingga pelawat menerima akan melambatkan penilaian pertama — biasanya tiada yang berjalan sehingga sepanduk persetujuan ditutup. Ini adalah tingkah laku yang betul; hanya tahu ia boleh mempengaruhi metrik “masa-ke-keputusan” anda.
• ⚠️ Sesetengah pengurus tag lama menanggalkan atribut data-* tersuai. Jika data-site-key tidak mencapai tag skrip, auto-init tidak akan bermula. Sediakannya sendiri dalam kod:

  NoxticaCollector.createClient({ siteKey: 'pk_prod_...' }).checkOnce();

• ❌ Beberapa bekas tag yang sangat berbahaya (jarang) menghalang masa jalan tahan gangguan daripada bermula. SDK terus berfungsi dengan bentuk pengumpulan yang lebih ringan dan mencatat amaran konsol.

Jika anda mesti mengintegrasikan melalui pengurus tag, konfigurasikannya untuk menembakkan tag Noxtica pada All Pages — Window Loaded (atau setara) dan bukan DOM Ready — ini memastikan keadaan persetujuan sudah muktamad sebelum apa-apa berjalan.

Content Security Policy

Jika tapak anda menggunakan content-security-policy, anda perlu membenarkan Noxtica memuatkan, menjalankan masa jalannya yang tahan gangguan (KHAN VM), dan bercakap dengan API kami. Contoh di bawah merangkumi ketiga-tiganya:

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

Jika dasar tersebut tidak mempunyai token 'wasm-unsafe-eval', pelayar menyekat masa jalan tahan gangguan dan anda akan melihat amaran berkaitan dalam konsol. Noxtica terus berfungsi — ia beralih kepada bentuk pengumpulan yang lebih ringan — tetapi dengan perlindungan gangguan yang lebih lemah. Menambah token di atas memulihkan pengalaman penuh.

Site Keys

Site Key anda (pk_...) adalah pengecam awam yang mengesahkan permintaan dari domain anda. Setiap domain yang anda tambah dalam Backoffice mendapat Site Key yang unik.

Nota penting:

• Site Keys adalah awam dan boleh ditanam dengan selamat dalam HTML anda
• Setiap Site Key diikat kepada asal tertentu (cth., https://example.com)
• API akan menolak permintaan di mana asal tidak sepadan dengan domain berdaftar Site Key

Pilihan Konfigurasi

const client = NoxticaCollector.createClient({
	// Your Site Key (required)
	siteKey: 'pk_prod_your_site_key_here',

	// API endpoint (defaults to production)
	apiUrl: 'https://collect.noxtica.com',

	// Collection mode: 'max' (default), 'standard', or 'minimal'
	// Omit to use max mode (recommended)
	// mode: 'standard', // Uncomment to opt out of max-only signals
});

Mod Pengumpulan

Format Respons

Selepas mengumpul dan menghantar, anda menerima:

{
	"success": true,
	"fingerprintId": "abc123...",
	"score": 15,
	"risk_level": "minimal",
	"confidence": 0.5,
	"flags": [],
	"details": {
		"summary": "Detected 0 risk indicator(s)."
	}
}

Tahap Risiko

Pengesahan

SDK mengesahkan setiap kunjungan dengan kelayakan jangka pendek yang diputar secara automatik yang diikat kepada Site Key anda. Ia memintanya, menyegarkannya, dan melampirkannya pada setiap penyerahan untuk anda.

Anda tidak perlu mengurus mana-mana daripada ini — SDK mengendalikannya secara automatik.

Proses Onboarding

1. Minta akses: Hubungi kami untuk meminta demo atau bermula
2. Persediaan akaun: Kami cipta akaun tenant anda dalam platform
3. Tambah domain: Log masuk ke Backoffice, pergi ke Domains, dan tambah asal anda
4. Salin Site Key: Setiap domain mendapat Site Key yang unik
5. Integrasi: Tambah skrip dengan Site Key anda ke halaman anda
6. Pantau: Lihat cap jari dan analitik dalam papan pemuka Backoffice

Mengurus Pelbagai Domain

Noxtica menyokong berbilang domain setiap akaun:

• Pengeluaran: https://www.yoursite.com
• Pementasan: https://staging.yoursite.com
• Mudah Alih: https://m.yoursite.com

Setiap domain mempunyai Site Key tersendiri. Anda boleh:

• Mengaktifkan/menyahaktifkan domain tanpa menjana semula kunci
• Memutar Site Keys jika berlaku kompromi
• Melihat analitik yang ditapis mengikut domain

Versi SDK

Versi SDK semasa: 3.3.0 (Schema: 2026-05-24)

Apa yang baharu dalam 3.3.0

• Isyarat tingkah laku ringan (sentiasa aktif) — isyarat masa mudah seperti tempoh sesi dan kecepatan interaksi pertama pelawat. Tiada data biometrik, dan tiada persetujuan pengguna akhir diperlukan.
• Biometrik tingkah laku (ikut serta) — apabila anda mengaktifkannya dalam Backoffice → Settings → Behavioral Biometrics, Noxtica turut melihat irama pergerakan tetikus, masa klik, dan penatal. Ini dikira sebagai data biometrik di bawah peraturan privasi yang ketat, jadi persetujuan eksplisit pengguna akhir diperlukan. Lihat Biometrik Tingkah Laku di bawah.
• Semakan konsistensi Apple Pay — mengesahkan bahawa peranti yang mendakwa sebagai iPhone benar-benar berkelakuan seperti satu, menangkap helah penipuan yang lazim.
• Padanan cap jari rangkaian — mengenali corak sambungan ciri-ciri alat automasi biasa, supaya trafik dari skrip dan bot menonjol walaupun pelayar kelihatan meyakinkan.
• Reputasi IP — menandakan pelawat yang tiba dari rangkaian dengan reputasi buruk, dengan pilihan untuk menggunakan suapan perisikan ancaman pilihan anda sendiri.

Biometrik Tingkah Laku (Pilihan, Ikut Serta)

Noxtica juga boleh mengkaji irama cara seseorang menggerakkan tetikus, mengklik, dan menatal. Ia adalah ciri ikut serta, dimatikan secara lalai.

Mengapa ikut serta? Jenis data tingkah laku ini dikira sebagai data peribadi sensitif di bawah peraturan privasi yang ketat, jadi menangkapnya memerlukan persetujuan eksplisit daripada pengguna akhir anda. Kami menjadikannya ikut serta supaya anda kekal mengawal bila dan bagaimana ia digunakan.

Untuk mengaktifkan:

1. Log masuk ke Backoffice → Settings → Behavioral Biometrics
2. Semak notis pematuhan dengan pasukan privasi atau undang-undang anda
3. Kemas kini dasar privasi dan sepanduk persetujuan anda untuk mendedahkan pengambilan ini
4. Togol ciri tersebut aktif

Setelah diaktifkan, Noxtica secara automatik mengambil kira isyarat tingkah laku ini dalam penilaian masa hadapan, dan papan pemuka anda menunjukkan skor tingkah laku yang terhasil bagi setiap domain.

Langkah Seterusnya

• Cuba demo langsung untuk melihat fingerprinting dalam tindakan
• Baca panduan Integrasi Backend untuk carian sisi pelayan
• Akses papan pemuka untuk meneroka data yang dikumpul