محیط اجرایی مرورگر

این راهنما توضیح می‌دهد SDK Noxtica چگونه درون مرورگر بازدیدکنندگان شما کار می‌کند — چه اتفاقی در طول یک ارزیابی می‌افتد، چگونه ذخیره موقت کارها را سریع نگه می‌دارد، و چطور مشکلات رایج را رفع اشکال کنید.

چگونه کار می‌کند

وقتی SDK Noxtica را به صفحه‌تان اضافه می‌کنید، چهار کار بی‌سروصدا انجام می‌دهد:

۱. احراز هویت: با Site Key شما با اعتبارنامه‌هایی که خودش مدیریت می‌کند وارد می‌شود ۲. جمع‌آوری: سیگنال‌های روزمره‌ای که مرورگر از پیش نمایش می‌دهد را می‌خواند ۳. ارسال: آن‌ها را برای امتیازدهی به Noxtica می‌فرستد ۴. ذخیره موقت: نتیجه را به‌صورت محلی ذخیره می‌کند تا در هر بازدید کار را از اول شروع نکند

همه این‌ها در پس‌زمینه اجرا می‌شود و هرگز صفحه شما را مسدود نمی‌کند.

جریان جمع‌آوری

خودکار (توصیه‌شده)

هنگام استفاده از 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>

از سیاست امنیت محتوا استفاده می‌کنید؟ باید به Noxtica اجازه دهید محیط اجرایی مقاوم در برابر دستکاری، یعنی KHAN VM، را بارگذاری و اجرا کند. اگر نتواند، Noxtica با یک فرم سبک‌تر از جمع‌آوری و حفاظت ضعیف‌تر در برابر دستکاری به کار ادامه می‌دهد. برای قطعه کد دقیق به شروع سریع ← سیاست امنیت محتوا مراجعه کنید.

اولین بازدید: یک ارزیابی کامل اجرا می‌شود و نتیجه ذخیره می‌شود.

بازدیدهای بعدی (در پنجره ذخیره موقت): نتیجه ذخیره‌شده برگردانده می‌شود و یک بازدید سبک ثبت می‌شود. کار سنگینی انجام نمی‌شود.

پس از انقضای پنجره ذخیره موقت: یک ارزیابی تازه اجرا می‌شود.

کنترل دستی

برای کنترل برنامه‌ای، از متد 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}

چه چیزی ذخیره می‌شود

• شناسه دستگاه
• زمان آخرین ارسال
• زمان آخرین مشاهده
• امتیاز و سطح ریسک قبلی

TTL (مدت اعتبار)

TTL پیش‌فرض ذخیره موقت ۷ روز است. این قابل تنظیم است:

// 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
});

بازنشانی اجباری

برای دور زدن ذخیره موقت و جمع‌آوری اثرانگشت تازه:

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);
});

متغیرهای سراسری

پس از جمع‌آوری، نتایج به‌صورت سراسری در دسترس هستند:

// 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);

مدیریت خطا

خطاهای رایج

مدیریت دستی خطاها

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

حالت‌های جمع‌آوری

SDK سه حالت جمع‌آوری را پشتیبانی می‌کند:

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

حالت محافظت‌شده (KHAN VM)

سخت‌ترین بخش مبارزه با ربات‌ها این است که هر چیزی که در مرورگر اجرا می‌شود، اصولاً قابل مشاهده و ویرایش است. یک مهاجم با انگیزه می‌تواند کد صفحه را بخواند، بفهمد چه چیزی اندازه‌گیری می‌شود، و بی‌سروصدا پاسخ‌های جعلی برگرداند.

KHAN VM هزینه این کار را بالا می‌برد. به جای اینکه جمع‌آوری را به‌صورت کد خوانا روی صفحه بگذارد، Noxtica بخش حساس را درون یک محیط اجرایی مهر و موم‌شده و سندباکس‌شده اجرا می‌کند. منطقی که تصمیم می‌گیرد چه چیزی اندازه بگیرد در دید آشکار برای مطالعه و بازنویسی قرار ندارد، و نتیجه‌ای که تولید می‌کند قبل از ترک مرورگر مهر و موم می‌شود — پس دستکاری یا پخش مجدد آن بسیار سخت‌تر است.

KHAN VM به چه کاری کمک می‌کند:

• نتایج مقاوم در برابر دستکاری — ارزیابی درون سندباکس مهر و موم می‌شود قبل از اینکه ارسال شود، پس اسکریپت‌های دیگر روی صفحه نمی‌توانند بی‌سروصدا آن را تغییر یا پخش مجدد کنند.
• سخت‌تر برای معکوس‌مهندسی — منطق جمع‌آوری درون محیط اجرایی پنهان می‌ماند، نه قابل‌خواندن در ابزارهای توسعه‌دهنده مرورگر.
• محافظت در برابر پخش مجدد — هر نتیجه یک‌بارمصرف و تأیید‌شده است، پس یک پاسخ ضبط‌شده نمی‌تواند برای جعل یک بازدیدکننده تمیز استفاده مجدد شود.

محدودیت‌های صادقانه — چه نمی‌کند:

• یک ویژگی مقاومت در برابر دستکاری است، نه رمزگذاری سرتاسری.
• اگر صفحه شما خودش در معرض خطر قرار گرفته (مثلاً از طریق یک آسیب‌پذیری اسکریپت بین‌سایتی)، مهاجم روی آن صفحه همان سیگنال‌های خام مرورگری را که Noxtica می‌بیند می‌تواند ببیند. KHAN VM پردازش و نتیجه را محافظت می‌کند، نه صفحه اطراف آن.

KHAN VM از سمت سرور روشن می‌شود و نیازی به تغییر در یکپارچه‌سازی شما ندارد. اگر نتواند شروع کند — مثلاً چون یک سیاست امنیت محتوا آن را مسدود می‌کند — Noxtica به یک فرم سبک‌تر از جمع‌آوری بازمی‌گردد تا تشخیص کار کند، فقط با حفاظت ضعیف‌تر در برابر دستکاری.

پشتیبانی مرورگر

SDK مرورگرهای مدرن را پشتیبانی می‌کند:

مرورگرهای قدیمی‌تر ممکن است دقت سیگنال کمتری داشته باشند اما همچنان کار می‌کنند.

حالت اشکال‌زدایی

برای رفع اشکال، لاگ‌گذاری اشکال‌زدایی را فعال کنید:

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

حالت اشکال‌زدایی این موارد را لاگ می‌کند:

• پیشرفت جمع‌آوری
• چرخه حیات توکن
• ضربه‌ها و خطاهای ذخیره موقت
• هر خطایی که مواجه می‌شود

توجه: حالت اشکال‌زدایی در محیط تولید به‌طور پیش‌فرض ساکت است. خروجی کنسولی نمایش داده نمی‌شود مگر به‌طور صریح فعال شود.

ملاحظات ذخیره‌سازی

ذخیره‌سازی مرورگر

SDK از ذخیره‌سازی محلی مرورگر برای ذخیره موقت نتایج استفاده می‌کند. اگر این در دسترس نباشد (مثلاً در مرور خصوصی یا با ذخیره‌سازی غیرفعال):

• تشخیص همچنان کار می‌کند
• هر بارگذاری صفحه یک ارزیابی تازه اجرا می‌کند
• هماهنگی چند تب ممکن است کاهش یابد

بدون کوکی

SDK از کوکی استفاده نمی‌کند. هر چیزی که نیاز دارد در ذخیره‌سازی محلی مرورگر نگه می‌دارد.

تأثیر بر عملکرد

اولین بازدید

جمع‌آوری به‌صورت ناهمزمان اجرا می‌شود و رندر صفحه را مسدود نمی‌کند.

بازدیدهای بعدی (ضربه ذخیره موقت)

رفع اشکال

اثرانگشت جمع‌آوری نمی‌شود

۱. خطاهای کنسول مرورگر را بررسی کنید ۲. تأیید کنید Site Key دقیقاً با دامنه شما مطابقت دارد (شامل https://) ۳. مطمئن شوید دامنه در بک‌آفیس فعال است ۴. حالت اشکال‌زدایی را برای مشاهده لاگ‌های دقیق فعال کنید

«WebAssembly توسط سیاست امنیت محتوا مسدود شد»

اگر این هشدار را در کنسول مرورگر می‌بینید، سیاست امنیت محتوای صفحه شما محیط اجرایی مقاوم در برابر دستکاری (KHAN VM) را مسدود می‌کند. تشخیص در حالت سبک‌تری کار می‌کند، اما با اجازه دادن به آن بهترین حفاظت را خواهید داشت.

از قطعه کد زیر برای اجازه بارگذاری و اجرای Noxtica استفاده کنید:

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

برای مرجع کامل به شروع سریع ← سیاست امنیت محتوا مراجعه کنید.

شناسه‌های دستگاه مختلف روی همان دستگاه

این می‌تواند اتفاق بیفتد وقتی:

• داده‌های ذخیره‌شده مرورگر پاک می‌شود
• پروفایل مرورگر تغییر می‌کند
• بازدیدکننده از حالت خصوصی/ناشناس استفاده می‌کند
• مرورگر به‌روزرسانی بزرگی می‌گیرد

این انتظار می‌رود — شناخت با تغییر دستگاه در طول زمان تطبیق پیدا می‌کند.

جمع‌آوری خیلی طول می‌کشد

۱. تب شبکه را برای پاسخ‌های کُند API بررسی کنید ۲. برای جمع‌آوری سریع‌تر استفاده از mode: 'minimal' را در نظر بگیرید ۳. مطمئن شوید SDK با ویژگی async بارگذاری می‌شود

رویدادها فعال نمی‌شوند

۱. مطمئن شوید قبل از اجرای SDK گوش می‌دهید ۲. بررسی کنید ویژگی‌های auto-init درست هستند ۳. بررسی کنید خطای JavaScript اجرا را مسدود نمی‌کند

بهترین شیوه‌ها

۱. از data-auto-check-once به جای data-auto-collect برای کمینه کردن جمع‌آوری‌های تکراری استفاده کنید

۲. SDK را به‌صورت ناهمزمان بارگذاری کنید با ویژگی async تا از مسدود کردن بارگذاری صفحه جلوگیری شود

۳. به رویدادها گوش دهید به جای نظرسنجی window.noxticaResult

۴. بدون دلیل TTL را تغییر ندهید — فاصله پیش‌فرض ۷ روزه برای بیشتر موارد استفاده بهینه است

۵. خطاها را با ملاحظه مدیریت کنید — شکست جمع‌آوری نباید صفحه شما را خراب کند

گام‌های بعدی

• شروع سریع — راهنمای راه‌اندازی اولیه
• یکپارچه‌سازی بک‌اند — جست‌وجوی دستگاه در سمت سرور