البدء

سيساعدك هذا الدليل على إضافة Noxtica إلى تطبيق الويب الخاص بك في بضع دقائق.

المتطلبات الأساسية

حساب Noxtica (اطلب الوصول عبر التواصل)
مفتاح موقعك (يُوفَّر بعد إعداد الحساب)

التكامل السريع

بمجرد إعداد حسابك والحصول على مفتاح موقعك، أضف جامعنا إلى ملف HTML — هذا كل التثبيت.

الجمع التلقائي (موصى به)

أبسط طريقة للبدء هي السماح لـ Noxtica بالعمل من تلقاء نفسها، باستخدام وضع التشغيل مرة واحدة:

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

سيقوم هذا بـ:

تقييم الزائر في زيارته الأولى
إعادة استخدام تلك النتيجة للزيارات المتكررة ضمن نافذة التخزين المؤقت (الافتراضي: 7 أيام)
تسجيل الزيارات العائدة بهدوء دون إعادة التقييم الكامل
التنسيق عبر علامات التبويب المفتوحة حتى يُقيَّم الزائر مرة واحدة فقط

النتائج متاحة عبر:

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

الجمع اليدوي

لمزيد من التحكم، استخدم 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>

الجمع الذكي مع `checkOnce()`

للبصمة الأخف، استخدم checkOnce() — فهي تحترم فترة الجمع التي تضبطها على الخادم، حتى لا يُعاد تقييم الزوار أكثر مما يلزم:

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

الأداء وأثره على الموقع

صُمم الجامع لأقل أثر ممكن على تحميل الصفحة والتأخير المرئي للمستخدم:

المقياس	القيمة
حجم السكربت الأولي	حوالي 167 KB مُصغَّر، حوالي 55 KB brotli
وقت الجمع (وسيط، أول زيارة)	أقل من 50ms على حاسوب حديث / أقل من 120ms على هواتف متوسطة
وقت الحصول على استجابة مع درجة	أقل من 150ms وسيط (حافة الجامع ← حافة API)
الزيارة من التخزين المؤقت	أقل من 10ms (لا عمل للبصمة؛ مجرد منارة)
حجب الخيط الرئيسي	لا شيء — يعمل الجمع في أجزاء غير متزامنة

كيف نُبقيه خفيفاً:

خاصية async — يُحمَّل الجامع في الخلفية ولا يُؤخر صفحتك في الظهور أو التفاعل أبداً.
وضع التشغيل مرة واحدة (data-auto-check-once) — بعد التقييم الأول، تُرسل الزيارات المتكررة ضمن نافذة التخزين المؤقت إشارة زيارة صغيرة فقط (حوالي 150 بايت).
التنسيق بين علامات التبويب — تتحد علامات التبويب المفتوحة المتعددة في تقييم واحد.
مُخزَّن بعد التحميل الأول — يُخزَّن KHAN VM المقاوم للعبث بواسطة المتصفح، فيُحمَّل فوراً في الزيارات اللاحقة.
معالجة في الخلفية حيثما أُتيح، حتى يبقى العمل خارج الخيط الرئيسي وصفحتك مستجيبة.

إذا لاحظت تباطؤاً بعد إضافة SDK، التقط ملفاً للأداء بـ await client.collectAndSubmit({ telemetry: true }) — تتضمن result.telemetry المُعادة تفصيلاً زمنياً.

بيئة Sandbox مقابل الإنتاج

ستمتلك مفتاحي موقع: واحد للتطوير والتجهيز، وآخر للإنتاج. كل منهما يعمل بسياساته الخاصة وبياناته منفصلة تماماً.

الجانب	Sandbox (`pk_sand_*`)	الإنتاج (`pk_prod_*`)
بادئة مفتاح الموقع	`pk_sand_`	`pk_prod_`
قائمة المصادر المسموحة	localhost + مصادر التجهيز الخاصة بك	صارمة — مصادرك المسجَّلة فقط
حد معدل الطلبات	سخي (حوالي 1000/دقيقة/IP)	حدود الخطة مُفعَّلة
سياسة تقييم الخطر	متساهلة — حد أدنى من حجب البوتات	سياسات الإنتاج مُطبَّقة
احتجاز البيانات	7 أيام	حسب إعداد المستأجر (الافتراضي 90 يوماً)
احتجاز سجل التدقيق	7 أيام	حسب إعداد المستأجر (الافتراضي 90 يوماً)
MFA للخطوات المتصاعدة	اختياري	مطلوب للعمليات التدميرية

غيّر مفتاح الموقع دائماً حسب البيئة. لا تستخدم مفتاح pk_sand_* في حركة مرور الإنتاج — لن تظهر بيانات Sandbox في لوحاتك الإنتاجية وتقييم الخطر سيكون متساهلاً جداً. وعلى العكس، استخدام مفتاح pk_prod_* في التطوير يستنزف ميزانية حد معدل الطلبات في الإنتاج.

نمط شائع:

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

التوافق مع مديري الوسوم

يعمل الجامع داخل Google Tag Manager وAdobe Launch وTealium وSegment، لكن مع تحفظات:

موصى به (مُفضَّل): أضف السكربت مباشرةً في ملف HTML، قبل </body> أو في <head> بخاصية async. البدء بأبكر وقت ممكن يمنح الجامع أفضل انطلاقة، فيكون جاهزاً حين يتفاعل الزائر.

مديرو الوسوم — يعمل، مع تحفظات:

✅ معظم مديري الوسوم الحديثة (GTM Custom HTML وAdobe Launch Custom Code وSegment Custom Source) يُحمّلون الجامع بنجاح.
⚠️ بوابات الموافقة التي تحجب السكربتات حتى يقبل الزائر ستؤخر التقييم الأول — عادةً لا يعمل شيء حتى تُرفَع لافتة الموافقة. هذا السلوك الصحيح؛ اعلم فحسب أنه قد يُحرّف مقاييس «وقت القرار».
⚠️ بعض مديري الوسوم القديمة تُسقط خصائص data-* المخصصة. إذا لم يصل data-site-key إلى وسم السكربت، لن يبدأ auto-init. اضبطه يدوياً في الشيفرة بدلاً من ذلك:
```
NoxticaCollector.createClient({ siteKey: 'pk_prod_...' }).checkOnce();
```
❌ بعض حاويات الوسوم المعزولة بشدة (نادرة) تمنع بيئة التشغيل المقاومة للعبث من البدء. يستمر SDK في العمل بصيغة جمع أخف ويُسجّل تحذيراً في وحدة التحكم.

إذا كان عليك التكامل عبر مدير وسوم، اضبطه ليُطلق وسم Noxtica على All Pages — Window Loaded (أو ما يعادله) بدلاً من DOM Ready — هذا يضمن أن حالة الموافقة نهائية قبل أن يعمل أي شيء.

سياسة أمان المحتوى

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

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

إذا أغفلت السياسة رمز 'wasm-unsafe-eval'، يحجب المتصفح بيئة التشغيل المقاومة للعبث وسترى تحذيراً ذا صلة في وحدة التحكم. تستمر Noxtica في العمل — تتراجع إلى صيغة جمع أخف — لكن بحماية أضعف من العبث. إضافة الرمز أعلاه يستعيد التجربة الكاملة.

مفاتيح المواقع

مفتاح موقعك (pk_...) معرّف عام يُصادق الطلبات من نطاقك. كل نطاق تضيفه في Backoffice يحصل على مفتاح موقع فريد.

ملاحظات مهمة:

مفاتيح المواقع عامة ويمكن تضمينها بأمان في ملف HTML الخاص بك
يرتبط كل مفتاح موقع بمصدر محدد (مثلاً https://example.com)
سيرفض الـ API الطلبات التي لا يطابق فيها المصدر النطاق المسجّل للمفتاح

خيارات الإعداد

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

أوضاع الجمع

الوضع	الإشارات	الأنسب لـ
`minimal`	مجموعة أساسية صغيرة من الإشارات	أسرع جمع، أصغر بصمة
`standard`	مجموعة واسعة من الإشارات	المواقع التي تُفضّل مجموعة أخف من الإشارات
`max`	المجموعة الكاملة من الإشارات	أقصى دقة (الافتراضي)

صيغة الاستجابة

بعد الجمع والإرسال، تستلم:

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

مستويات الخطر

الدرجة	المستوى	المعنى
0-19	`minimal`	خطر منخفض جداً، يُرجَّح أنه شرعي
20-39	`low`	خطر منخفض، شذوذات طفيفة
40-59	`medium`	خطر متوسط، بعض الإشارات
60-79	`high`	خطر مرتفع، يُرجَّح وجود أتمتة
80-100	`critical`	خطر مرتفع جداً، بوت مؤكَّد

المصادقة

يُصادق الـ SDK كل زيارة ببيانات اعتماد قصيرة العمر تتجدد تلقائياً مرتبطة بمفتاح موقعك. يطلبها ويُجددها ويُرفقها بكل إرسال نيابة عنك.

لا تحتاج إلى إدارة أي من هذا — يتولى الـ SDK ذلك تلقائياً.

عملية الإعداد

اطلب الوصول: تواصل معنا لطلب عرض تجريبي أو البدء
إعداد الحساب: ننشئ حساب المستأجر الخاص بك في المنصة
أضف النطاقات: سجّل الدخول إلى Backoffice، اذهب إلى Domains، وأضف مصادرك
انسخ مفتاح الموقع: كل نطاق يحصل على مفتاح موقع فريد
التكامل: أضف السكربت مع مفتاح موقعك إلى صفحاتك
المتابعة: شاهد البصمات والتحليلات في لوحة Backoffice

إدارة نطاقات متعددة

تدعم Noxtica نطاقات متعددة لكل حساب:

الإنتاج: https://www.yoursite.com
التجهيز: https://staging.yoursite.com
الجوال: https://m.yoursite.com

لكل نطاق مفتاح موقع خاص. يمكنك:

تفعيل/تعطيل النطاقات دون إعادة توليد المفاتيح
تدوير مفاتيح المواقع إذا تعرّضت للاختراق
عرض التحليلات مُصفَّاةً حسب النطاق

إصدار الـ SDK

إصدار الـ SDK الحالي: 3.3.0 (Schema: 2026-05-24)

المستجدات في 3.3.0

إشارات سلوكية خفيفة (دائماً مفعَّلة) — مؤشرات توقيت بسيطة كمدة الجلسة وسرعة التفاعل الأول للزائر. لا بيانات بيومترية، ولا موافقة من المستخدم مطلوبة.
القياسات البيومترية السلوكية (اختياري، تتطلب تفعيلاً) — حين تُفعّلها من Backoffice ← Settings ← Behavioral Biometrics، تنظر Noxtica أيضاً في إيقاع حركة الماوس وتوقيت النقر والتمرير. هذا يُعدّ بيانات بيومترية بموجب أشد قواعد الخصوصية صرامة، لذا تتطلب موافقة صريحة من المستخدم. راجع القياسات البيومترية السلوكية أدناه.
فحص تناسق Apple Pay — يتحقق من أن الجهاز الذي يدّعي أنه iPhone يتصرف فعلاً كـ iPhone، مما يكشف حيلة تزوير شائعة.
مطابقة بصمة الشبكة — يتعرف على أنماط الاتصال المميزة لأدوات الأتمتة الشائعة، حتى تبرز حركة مرور السكربتات والبوتات حتى حين يبدو المتصفح مقنعاً.
سمعة الـ IP — يُعلّم الزوار القادمين من شبكات ذات سمعة سيئة، مع خيار ربط مصدر استخبارات تهديدات خاص بك.

القياسات البيومترية السلوكية (اختياري، تتطلب تفعيلاً)

يستطيع Noxtica أيضاً دراسة إيقاع حركة الماوس والنقر والتمرير للشخص. إنها ميزة تتطلب تفعيلاً صريحاً، معطّلة بالافتراضي.

لماذا تتطلب تفعيلاً؟ هذا النوع من البيانات السلوكية يُعدّ بيانات شخصية حساسة بموجب أشد قواعد الخصوصية صرامة، لذا يتطلب جمعه موافقة صريحة من مستخدمك النهائي. نجعله يتطلب تفعيلاً حتى تبقى في السيطرة على متى وكيف يُستخدم.

للتفعيل:

سجّل الدخول إلى Backoffice ← Settings ← Behavioral Biometrics
راجع إشعار الامتثال مع فريق الخصوصية أو القانوني
حدّث سياسة الخصوصية ولافتة الموافقة للإفصاح عن هذا الجمع
شغّل الميزة

بعد التفعيل، يُدرج Noxtica تلقائياً هذه الإشارات السلوكية في التقييمات المستقبلية، وتعرض لوحتك درجة السلوك الناتجة لكل نطاق.

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

جرّب العرض التجريبي المباشر لرؤية البصمة عملياً
اقرأ دليل تكامل الخادم الخلفي للاستعلامات من جانب الخادم
ادخل إلى لوحة التحكم لاستكشاف البيانات المجموعة

البدء

المتطلبات الأساسية

التكامل السريع

الجمع التلقائي (موصى به)

الجمع اليدوي

الجمع الذكي مع checkOnce()

الأداء وأثره على الموقع

بيئة Sandbox مقابل الإنتاج

التوافق مع مديري الوسوم

سياسة أمان المحتوى

مفاتيح المواقع

خيارات الإعداد

أوضاع الجمع

صيغة الاستجابة

مستويات الخطر

المصادقة

عملية الإعداد

إدارة نطاقات متعددة

إصدار الـ SDK

المستجدات في 3.3.0

القياسات البيومترية السلوكية (اختياري، تتطلب تفعيلاً)

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

الجمع الذكي مع `checkOnce()`