بيئة تشغيل المتصفح

يشرح هذا الدليل كيفية عمل Noxtica SDK داخل متصفحات زوارك — ما الذي يحدث أثناء التقييم، وكيف يُبقي التخزين المؤقت الأمور سريعة، وكيفية استكشاف المشكلات الشائعة.

كيف يعمل

عندما تضيف Noxtica SDK إلى صفحتك، يقوم بأربعة أشياء بهدوء:

1. المصادقة: يسجّل الدخول بمفتاح موقعك باستخدام بيانات الاعتماد التي يديرها عنك
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>

تستخدم سياسة أمان المحتوى (CSP)؟ ستحتاج إلى السماح لـ 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)

مدة الصلاحية الافتراضية للتخزين المؤقت 7 أيام. يمكن تعديل ذلك:

// 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 ملفات تعريف الارتباط. كل ما يحتاجه محفوظ في التخزين المحلي للمتصفح.

أثر الأداء

الزيارة الأولى

يعمل الجمع بشكل غير متزامن ولا يحجب عرض الصفحة.

الزيارات اللاحقة (إصابة التخزين المؤقت)

استكشاف الأخطاء

البصمة لم تُجمَع

1. افحص وحدة تحكم المتصفح بحثاً عن أخطاء
2. تحقق من أن مفتاح الموقع يطابق نطاقك تماماً (بما في ذلك https://)
3. تأكد من أن النطاق مفعَّل في Backoffice
4. فعّل وضع التصحيح لرؤية سجلات تفصيلية

”WebAssembly blocked by Content Security Policy”

إذا رأيت هذا التحذير في وحدة تحكم المتصفح، فسياسة أمان المحتوى في صفحتك تحجب بيئة التشغيل المقاومة للعبث (KHAN VM). يستمر الكشف في العمل بصيغة أخف، لكنك ستحصل على أقوى حماية بالسماح لها.

استخدم المقطع أدناه للسماح لـ Noxtica بالتحميل والتشغيل:

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

راجع البدء ← سياسة أمان المحتوى للمرجع الكامل.

معرفات جهاز مختلفة على نفس الجهاز

قد يحدث هذا حين:

• يمسح المتصفح بياناته المحفوظة
• يتغير ملف تعريف المتصفح
• يستخدم الزائر التصفح الخاص/المتخفي
• يمر المتصفح بتحديث كبير

هذا متوقع — يتكيف التعرف مع تغيرات الجهاز عبر الزمن.

الجمع يستغرق وقتاً طويلاً

1. افحص لوحة الشبكة للبحث عن استجابات API بطيئة
2. فكر في استخدام mode: 'minimal' لجمع أسرع
3. تأكد من تحميل الـ SDK بخاصية async

الأحداث لا تُطلَق

1. تأكد من أنك تستمع قبل تشغيل الـ SDK
2. تحقق من صحة خصائص auto-init
3. تأكد من عدم وجود أخطاء JavaScript تمنع التنفيذ

أفضل الممارسات

1. استخدم data-auto-check-once بدلاً من data-auto-collect لتقليل عمليات الجمع المتكررة

2. حمّل الـ SDK بشكل غير متزامن بخاصية async لتجنب حجب تحميل الصفحة

3. استمع إلى الأحداث بدلاً من استطلاع window.noxticaResult

4. لا تُعِد تعريف مدة الصلاحية دون حاجة — الفترة الافتراضية 7 أيام مُحسَّنة لمعظم حالات الاستخدام

5. تعامل مع الأخطاء برشاقة — فشل الجمع لا يجب أن يكسر صفحتك

الخطوات التالية

• البدء - دليل الإعداد الأولي
• تكامل الخادم الخلفي - استعلامات الأجهزة من جانب الخادم