Browser Runtime

คู่มือนี้อธิบายว่า SDK ของ Noxtica ทำงานอย่างไรภายในเบราว์เซอร์ของผู้เยี่ยมชม — สิ่งที่เกิดขึ้นระหว่างการประเมิน วิธีการทำงานของแคชที่ทำให้ทุกอย่างรวดเร็ว และวิธีแก้ปัญหาที่พบบ่อย

หลักการทำงาน

เมื่อคุณเพิ่ม SDK ของ Noxtica ลงในหน้าเว็บ มันจะทำสี่สิ่งอย่างเงียบๆ:

1. ยืนยันตัวตน: ลงชื่อเข้าใช้ด้วย Site Key ของคุณโดยใช้ข้อมูลรับรองที่มันจัดการให้คุณ
2. เก็บข้อมูล: อ่านสัญญาณทั่วไปที่เบราว์เซอร์เปิดเผยอยู่แล้ว
3. ส่ง: ส่งข้อมูลเหล่านั้นไปยัง Noxtica เพื่อให้คะแนน
4. แคช: เก็บผลลัพธ์ไว้ในเครื่องเพื่อไม่ต้องทำงานซ้ำในทุกครั้งที่เข้าชม

ทุกอย่างทำงานในพื้นหลังและไม่บล็อกหน้าเว็บของคุณเลย

ขั้นตอนการเก็บข้อมูล

อัตโนมัติ (แนะนำ)

เมื่อใช้ data-auto-check-once SDK จะใช้การเก็บข้อมูลอัจฉริยะ:

<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>

ใช้ content-security-policy อยู่ไหม? คุณต้องอนุญาตให้ Noxtica โหลดและรัน runtime ที่ต้านการแก้ไขของมัน ซึ่งก็คือ KHAN VM หากทำไม่ได้ Noxtica จะทำงานต่อไปด้วยการเก็บข้อมูลรูปแบบที่เบากว่าและการป้องกันการแก้ไขที่อ่อนลง ดู เริ่มต้นใช้งาน → Content Security Policy สำหรับโค้ดตัวอย่างที่แน่นอน

การเยี่ยมชมครั้งแรก: การประเมินเต็มรูปแบบจะทำงานและผลลัพธ์จะถูกแคชไว้

การเยี่ยมชมครั้งถัดไป (ภายในช่วงแคช): ผลลัพธ์ที่แคชไว้จะถูกส่งคืนและบันทึกการเยี่ยมชมแบบเบา ไม่มีการทำงานหนักซ้ำ

หลังจากช่วงแคชหมดอายุ: การประเมินใหม่จะทำงาน

การควบคุมด้วยตนเอง

สำหรับการควบคุมแบบโปรแกรม ใช้เมธอด 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');
}

พฤติกรรมของแคช

SDK จะแคชผลลัพธ์แต่ละครั้งในเบราว์เซอร์เพื่อไม่ต้องประเมินผู้เยี่ยมชมคนเดิมซ้ำในทุกหน้าที่เข้าชม

คีย์แคช

nox_fp_{your_site_key}

สิ่งที่ถูกแคช

• Device ID
• ไทม์สแตมป์การส่งครั้งล่าสุด
• ไทม์สแตมป์การเห็นครั้งล่าสุด
• คะแนนความเสี่ยงและระดับความเสี่ยงก่อนหน้า

TTL (Time-To-Live)

TTL ของแคชค่าเริ่มต้นคือ 7 วัน สามารถปรับได้:

// แทนที่ขณะเก็บข้อมูล
const result = await client.checkOnce({
	checkIntervalDays: 14, // 14 วันแทน 7
});

// หรือเป็นวินาที
const result = await client.checkOnce({
	ttlSeconds: 86400, // 1 วัน
});

บังคับรีเฟรช

เพื่อข้ามแคชและเก็บข้อมูลใหม่:

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

การประสานงานระหว่างแท็บ

เมื่อผู้เยี่ยมชมเปิดหลายแท็บของเว็บไซต์คุณพร้อมกัน SDK จะทำให้แน่ใจว่าพวกเขาถูกประเมินเพียงครั้งเดียว:

• มีเพียงแท็บเดียวที่ทำงานจริง
• แท็บอื่นๆ รอและแบ่งปันผลลัพธ์นั้น

สิ่งนี้เกิดขึ้นอัตโนมัติ — ไม่จำเป็นต้องตั้งค่า

อีเวนต์

SDK จะส่งอีเวนต์ที่คุณสามารถรับฟังได้:

noxtica:collected

ทำงานหลังจากเก็บข้อมูลสำเร็จหรือเมื่อส่งคืนผลลัพธ์ที่แคชไว้:

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

ทำงานเฉพาะเมื่อส่งคืนผลลัพธ์ที่แคชไว้:

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

noxtica:error

ทำงานเมื่อการเก็บข้อมูลล้มเหลว:

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

ตัวแปร Global

หลังจากเก็บข้อมูล ผลลัพธ์จะเข้าถึงได้แบบ global:

// หลังการเก็บข้อมูลเสร็จสมบูรณ์
console.log(window.noxticaResult);

// อินสแตนซ์ของ client (เมื่อใช้ auto-init)
console.log(window.noxticaClient);

// ข้อผิดพลาดล่าสุด (ถ้ามี)
console.log(window.noxticaLastError);

การจัดการข้อผิดพลาด

ข้อผิดพลาดที่พบบ่อย

การจัดการข้อผิดพลาดด้วยตนเอง

try {
	const result = await client.collectAndSubmit();
} catch (error) {
	if (error.message.includes('origin_mismatch')) {
		// ปัญหาการตั้งค่า site key
	} else if (error.message.includes('rate')) {
		// ถอยกลับและลองใหม่ในภายหลัง
	}
}

โหมดการเก็บข้อมูล

SDK รองรับโหมดการเก็บข้อมูลสามแบบ:

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

โหมดป้องกัน (KHAN VM)

สิ่งที่ยากที่สุดในการต่อสู้กับบอทคือทุกอย่างที่รันในเบราว์เซอร์นั้น โดยหลักการแล้วมองเห็นและแก้ไขได้ ผู้โจมตีที่มุ่งมั่นสามารถอ่านโค้ดบนหน้าเว็บ คิดออกว่ากำลังวัดอะไร และป้อนคำตอบปลอมกลับมาได้

KHAN VM เพิ่มต้นทุนของการทำเช่นนั้น แทนที่จะทิ้งการเก็บข้อมูลไว้เปิดเผยเป็นโค้ดที่อ่านได้บนหน้าเว็บ Noxtica รันส่วนที่ละเอียดอ่อนภายใน runtime ที่ปิดผนึกและแซนด์บ็อกซ์ไว้ Logic ที่ตัดสินใจว่าจะวัดอะไรไม่ได้นั่งอยู่ให้ผู้โจมตีศึกษาและเขียนทับ และผลลัพธ์ที่มันผลิตจะถูกปิดผนึกก่อนที่มันจะออกจากเบราว์เซอร์ — ทำให้แก้ไขหรือ replay ได้ยากขึ้นมาก

KHAN VM ช่วยในเรื่อง:

• ผลลัพธ์ที่ต้านการแก้ไข — การประเมินถูกปิดผนึกภายในแซนด์บ็อกซ์ก่อนส่ง ดังนั้น script อื่นบนหน้าเว็บไม่สามารถแก้ไขหรือ replay มันแบบเงียบๆ ได้
• วิศวกรรมกลับยากขึ้น — logic การเก็บข้อมูลซ่อนอยู่ภายใน runtime แทนที่จะอ่านได้ในเครื่องมือของนักพัฒนาของเบราว์เซอร์
• การป้องกัน Replay — ผลลัพธ์แต่ละชุดเป็นแบบครั้งเดียวและยืนยันแล้ว ดังนั้น response ที่ถูกจับไม่สามารถนำมาใช้ซ้ำเพื่อปลอมเป็นผู้เยี่ยมชมที่สะอาดได้

ขอบเขตที่ซื่อตรง — สิ่งที่มัน ไม่ ทำ:

• มันเป็นฟีเจอร์ต้านการแก้ไข ไม่ใช่การเข้ารหัสแบบ end-to-end
• หากหน้าเว็บของคุณเองถูกบุกรุก (เช่น จากช่องโหว่ cross-site scripting) ผู้โจมตีบนหน้าเว็บนั้นสามารถมองเห็นสัญญาณเบราว์เซอร์ดิบเดียวกับที่ Noxtica เห็นได้ KHAN VM ปกป้อง การประมวลผลและผลลัพธ์ ไม่ใช่หน้าเว็บรอบๆ มัน

KHAN VM เปิดใช้งานจากฝั่งเซิร์ฟเวอร์และไม่ต้องเปลี่ยนแปลงการผสานระบบของคุณ หากเริ่มต้นไม่ได้ — เช่น เพราะ content-security-policy บล็อกมัน — Noxtica จะ fallback ไปยังการเก็บข้อมูลรูปแบบที่เบากว่า การตรวจจับยังทำงานต่อ เพียงแต่การป้องกันการแก้ไขจะอ่อนลง

การรองรับเบราว์เซอร์

SDK รองรับเบราว์เซอร์สมัยใหม่:

เบราว์เซอร์รุ่นเก่ากว่าอาจมีความแม่นยำของสัญญาณลดลง แต่ยังคงทำงานได้

โหมดดีบัก

เปิดใช้งานการบันทึก debug เพื่อแก้ปัญหา:

// ก่อน SDK โหลด
globalThis.NOXTICA_DEBUG = true;

// หรือต่อ client
const client = NoxticaCollector.createClient({
	siteKey: 'pk_prod_...',
	debug: true,
});

// หรือผ่านคุณสมบัติของสคริปต์
<script src="..." data-debug></script>;

โหมดดีบักบันทึก:

• ความคืบหน้าของการเก็บข้อมูล
• วงจรชีวิตของ token
• การ hit และ miss ของแคช
• ข้อผิดพลาดที่พบ

หมายเหตุ: โหมดดีบักจะเงียบโดยค่าเริ่มต้นใน production ไม่มีเอาต์พุตในคอนโซลเว้นแต่จะเปิดใช้งานอย่างชัดเจน

ข้อพิจารณาเรื่องการจัดเก็บข้อมูล

การจัดเก็บในเบราว์เซอร์

SDK ใช้ local storage ของเบราว์เซอร์เพื่อแคชผลลัพธ์ หากไม่พร้อมใช้งาน (เช่น ในการท่องแบบส่วนตัวหรือปิดการจัดเก็บ):

• การตรวจจับยังทำงานต่อ
• ทุกหน้าที่โหลดจะรันการประเมินใหม่
• การประสานงานระหว่างแท็บอาจลดลง

ไม่มี Cookies

SDK ไม่ใช้ cookies ทุกอย่างที่จำเป็นเก็บไว้ใน local storage ของเบราว์เซอร์

ผลกระทบต่อประสิทธิภาพ

การเยี่ยมชมครั้งแรก

การเก็บข้อมูลทำงานแบบ asynchronous และไม่บล็อกการเรนเดอร์หน้า

การเยี่ยมชมครั้งถัดไป (Cache Hit)

การแก้ปัญหา

Fingerprint ไม่ถูกเก็บ

1. ตรวจสอบคอนโซลเบราว์เซอร์เพื่อหาข้อผิดพลาด
2. ตรวจสอบว่า Site Key ตรงกับโดเมนของคุณอย่างแม่นยำ (รวมถึง https://)
3. ตรวจสอบให้แน่ใจว่าโดเมนเปิดใช้งานใน Backoffice
4. เปิดโหมดดีบักเพื่อดูบันทึกโดยละเอียด

”WebAssembly blocked by Content Security Policy”

หากคุณเห็นคำเตือนนี้ในคอนโซลเบราว์เซอร์ content-security-policy ของหน้าเว็บคุณกำลังบล็อก runtime ที่ต้านการแก้ไข (KHAN VM) การตรวจจับยังทำงานในโหมดที่เบากว่า แต่คุณจะได้รับการป้องกันที่แข็งแกร่งที่สุดโดยการอนุญาตมัน

ใช้โค้ดด้านล่างเพื่ออนุญาตให้ Noxtica โหลดและรัน:

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

ดู เริ่มต้นใช้งาน → Content Security Policy สำหรับข้อมูลอ้างอิงฉบับเต็ม

Device ID แตกต่างกันบนอุปกรณ์เดียวกัน

อาจเกิดขึ้นเมื่อ:

• ข้อมูลที่จัดเก็บในเบราว์เซอร์ถูกล้าง
• โปรไฟล์เบราว์เซอร์เปลี่ยน
• ผู้เยี่ยมชมใช้โหมดส่วนตัว/ไม่ระบุตัวตน
• เบราว์เซอร์ผ่านการอัปเดตครั้งใหญ่

นี่เป็นพฤติกรรมที่คาดหวัง — การรับรู้ปรับตัวตามการเปลี่ยนแปลงของอุปกรณ์ไปตามเวลา

การเก็บข้อมูลใช้เวลานานเกินไป

1. ตรวจสอบแท็บ network เพื่อหา API response ที่ช้า
2. พิจารณาใช้ mode: 'minimal' เพื่อเก็บข้อมูลที่เร็วขึ้น
3. ตรวจสอบให้แน่ใจว่า SDK โหลดด้วยคุณสมบัติ async

อีเวนต์ไม่ทำงาน

1. ตรวจสอบว่าคุณกำลังรับฟังก่อนที่ SDK จะรัน
2. ตรวจสอบว่าคุณสมบัติ auto-init ถูกต้อง
3. ตรวจสอบว่าไม่มีข้อผิดพลาด JavaScript ที่บล็อกการทำงาน

แนวทางปฏิบัติที่ดี

1. ใช้ data-auto-check-once แทน data-auto-collect เพื่อลดการเก็บข้อมูลซ้ำซ้อน

2. โหลด SDK แบบ asynchronous ด้วยคุณสมบัติ async เพื่อหลีกเลี่ยงการบล็อกการโหลดหน้า

3. รับฟังอีเวนต์ แทนการสำรวจ window.noxticaResult

4. อย่าเขียนทับ TTL โดยไม่จำเป็น — ช่วงเวลาเริ่มต้น 7 วันได้รับการปรับให้เหมาะสมสำหรับกรณีใช้งานส่วนใหญ่

5. จัดการข้อผิดพลาดอย่างนุ่มนวล — ความล้มเหลวในการเก็บข้อมูลไม่ควรทำให้หน้าของคุณเสียหาย

ขั้นตอนถัดไป

• เริ่มต้นใช้งาน — คู่มือการตั้งค่าเริ่มต้น
• การผสานกับ Backend — การค้นหาอุปกรณ์ฝั่งเซิร์ฟเวอร์