تغطي هذه الصفحة المشكلات الشائعة التي تُصادَف أثناء تكامل TRACIO وحلولها. إن TRACIO خدمة سحابية مُدارة، لذا فإن معظم المشكلات تحدث من جانب العميل (حظر النص البرمجي، وملفات تعريف الارتباط، وميزات الخصوصية في المتصفح) وليست ناتجة عن البنية التحتية.
يفشل تحميل النص البرمجي للوكيل أو طلب التعريف، أو تُظهر وحدة تحكم المتصفح خطأ CORS تجاه edge.tracio.ai.
1. الأصل (Origin) غير مُدرَج في قائمة السماح لمفتاحك
يمكن تقييد كل مفتاح عام بمجموعة من الأصول المسموح بها. إذا لم يكن أصل موقعك مُدرَجًا في قائمة السماح، فإن الحافة (edge) ترفض الطلب (403). أضِف أصلك ضمن Request Filtering في لوحة التحكم، أو تأكد من أن المفتاح الذي تستخدمه ليس مقيَّدًا بأصل موقع آخر.
2. مانع الإعلانات أو CSP يحظر الطلب
يمكن لإضافات الخصوصية (uBlock Origin وAdBlock) أو سياسة Content-Security-Policy الصارمة أن تحظر النص البرمجي للوكيل أو طلبه الشبكي. يعرض SDK ذلك على شكل خطأ blocked (انظر معالجة الأخطاء). ولجعل الحظر أصعب، قدِّم الوكيل من نطاق فرعي تابع للطرف الأول باستخدام الخيارين scriptUrl / endpoint.
3. نقطة نهاية / منطقة خاطئة
تأكد من أنك تشير إلى نقطة النهاية الصحيحة. عند ضبط region، يتصل SDK بـ edge.us.tracio.ai أو edge.eu.tracio.ai؛ وإذا لم تُضبَط، فإنه يستخدم edge.tracio.ai.
درجات الثقة أقل باستمرار من 0.90 للزوار العائدين.
1. عدم استمرارية ملف تعريف الارتباط
قد لا يُضبَط ملف تعريف الارتباط _vid_t بشكل صحيح. تحقق من ذلك في المتصفح:
// In browser consoledocument.cookie.split(";").filter((c) => c.includes("_vid_t"))إذا كان ملف تعريف الارتباط مفقودًا، فراجع قسم عدم استمرارية ملف تعريف الارتباط أدناه.
2. مساحة عمل جديدة
تحتوي مساحة العمل الجديدة تمامًا على قاعدة بيانات زوار فارغة، لذا يظهر جميع الزوار على أنهم "جدد" بثقة تبلغ نحو 0.90. بعد 24–48 ساعة، يُتعرَّف على الزوار العائدين بثقة أعلى.
3. التصفح المتخفي/الخاص
في وضع التصفح المتخفي، تُمسَح ملفات تعريف الارتباط وlocalStorage عند انتهاء الجلسة. يلجأ TRACIO عندئذٍ إلى المطابقة القائمة على الإشارات فقط، والتي تكون ثقتها أقل (عادةً 0.85–0.95).
4. المتصفحات ذات آليات مكافحة البصمة العدوانية
تعمل Brave وFirefox (الوضع الصارم) وSafari (ITP) على تعديل بعض إشارات المتصفح أو حظرها. وهذا يقلل مجموعة الإشارات المتاحة للمطابقة. يكتشف TRACIO هذه المتصفحات ويضبط الثقة وفقًا لذلك.
افحص التعريف في لوحة التحكم (Visitors / Events)، أو تفاعَل مع تسليم
webhook، الذي يحمل identification.confidence
وidentification.incognito وحُكم bot لكل حدث.
يُوسَم زوار بشريون شرعيون على أنهم روبوتات.
1. إضافات المتصفح تعدِّل خصائص navigator
تعدِّل بعض إضافات الخصوصية navigator.userAgent أو navigator.platform أو خصائص أخرى. وهذا قد يُطلِق كاشف العبث لكنه لا ينبغي أن يُطلِق كشف الروبوتات بمفرده.
تحقق من الحقل bot.type لتحديد الكاشف الذي انطلق:
| bot.type | السبب الشائع للإيجابية الكاذبة | الحل |
|---|---|---|
webdriver | أداة اختبار المتصفح تركت navigator.webdriver = true | ينبغي للمستخدم تعطيل وضع الاختبار |
headless | VNC/سطح مكتب بعيد مع عرض GPU برمجي | تحقق مما إذا كان SwiftShader/llvmpipe هو مُصيِّر GPU |
unknown | شذوذ في طول Eval ناتج عن إضافة متصفح | راجع الإضافة |
rateBot | تحديث تلقائي للصفحة أو استقصاء عدواني | قلِّل معدل تكرار الطلبات |
2. البيئات المؤسسية ذات العرض البرمجي
كثيرًا ما تستخدم بيئات Citrix وVDI وخوادم الأطراف الطرفية عرض GPU برمجيًا (SwiftShader وllvmpipe)، وهو مؤشر على العمل بلا واجهة (headless). إذا كان مستخدموك يعملون في هذه البيئات، فطبِّق سياسة أكثر تساهلًا عندما يُظهر الـ webhook نوع روبوت headless:
// `event` is the webhook delivery body (/docs/webhooks)if (event.bot.result === "bot" && event.bot.type === "headless") { // Software-GPU (SwiftShader/llvmpipe) VDI users can trip the headless // detector — consider applying a softer policy for these.}3. الاختبار التلقائي في بيئة الإنتاج
إذا كان فريق ضمان الجودة لديك يشغِّل اختبارات Selenium/Playwright على بيئة الإنتاج، فسيُكتشَف ذلك بشكل صحيح على أنه روبوتات. استخدم مفتاحًا منفصلًا لحركة مرور الاختبار.
يختفي ملف تعريف الارتباط _vid_t بين الزيارات، مما يجعل كل زيارة تظهر على أنها زائر "جديد".
1. موقع بدون HTTPS
يستخدم ملف تعريف الارتباط _vid_t علامة Secure ولا يُضبَط إلا عبر HTTPS. تأكد من أن موقعك يستخدم HTTPS.
2. التحميل عبر المواقع (Cross-site)
يضبط TRACIO SameSite=Lax على ملف تعريف الارتباط. إذا حُمِّل الوكيل في سياق صارم عبر المواقع، فقد يُحظَر ملف تعريف الارتباط. إن تقديم الوكيل من نطاق فرعي تابع للطرف الأول (عبر scriptUrl / endpoint) يبقيه ضمن الموقع نفسه (same-site).
3. Safari ITP
يمكن لـ Intelligent Tracking Prevention (ITP) في Safari أن يحدَّ من عمر ملفات تعريف الارتباط المضبوطة من جانب العميل. يُصدِر TRACIO أيضًا _vid_t من جانب الخادم عبر ترويسة Set-Cookie ويعكس الـ UID إلى localStorage، بحيث تبقى الهوية محفوظة حتى عندما يُقيَّد عمر ملف تعريف الارتباط.
4. المتصفح يمسح ملفات تعريف الارتباط
تمسح بعض المتصفحات (Brave وFirefox Focus) ملفات تعريف الارتباط عند انتهاء الجلسة. سيظهر المستخدمون ذوو إعدادات الخصوصية العدوانية دائمًا على أنهم زوار جدد.
يستغرق tracio.getResult() أكثر من 500 مللي ثانية للإرجاع.
1. شبكة بطيئة إلى الحافة
تحقق من زمن الذهاب والإياب إلى الحافة الإقليمية الخاصة بك:
curl -o /dev/null -s -w "DNS: %{time_namelookup}s\nConnect: %{time_connect}s\nTLS: %{time_appconnect}s\nTotal: %{time_total}s\n" https://edge.tracio.ai/health2. جمع الإشارات يستغرق وقتًا طويلًا جدًا
لبعض الإشارات مهل زمنية. على الأجهزة البطيئة، قد يستغرق الجمع أكثر من 200 مللي ثانية. أكثر الإشارات احتمالًا لإضافة زمن وصول هي بصمة الصوت (AudioContext المعلَّق على iOS)، ومسبار WebRTC/TURN، وكشف الخطوط، وتوقيت DRM. وهذه محدودة بمهل زمنية ولا تحظر أبدًا إلى ما لا نهاية.
تُرجِع بعض الإشارات حالة غير ناجحة (على سبيل المثال "not available" أو "timeout").
أخطاء الإشارات متوقَّعة وتُعالَج بسلاسة — يضبط النظام الثقة بناءً على الإشارات المتاحة. أمثلة شائعة: Canvas محظور بواسطة CSP، وانتهاء مهلة AudioContext على iOS، وWebGPU غير مدعوم على معظم المتصفحات، وClient Hints غير متاحة خارج Chromium. لا يلزم اتخاذ أي إجراء ما لم تفشل الإشارات الحرجة (Canvas وWebGL والصوت) باستمرار لدى عدد كبير من الزوار.
إذا واجهت مشكلة غير مغطاة هنا:
debug: truerequestId لتعريف متأثر