Skip to main content

​
مشكلات SDK المتصفح

​
لا يظهر أي طلب شبكة إلى /ct

تحقق مما يلي بالترتيب:
  1. النص البرمجي في المكان الخطأ — فموضعه <head> وليس <body> ولا بعد </html>
  2. قيمة site_id مفقودة — تأكد أن scanova('init', 'YOUR_SITE_ID', ...) تحمل معرّف موقع حقيقيًا لا نصًا بديلًا
  3. سياسة أمان المحتوى (CSP) تحجب النص البرمجي — أضف https://cdn.scanova.io (script source) وhttps://t.scanova.io (connect source) إلى ترويسات CSP لديك
  4. إضافة في المتصفح تحجب الطلب — جرّب في نافذة تصفح متخفٍّ مع تعطيل كل الإضافات
  5. autoPageview: false وبلا استدعاء يدوي — إما أن تفعّل autoPageview وإما أن تضيف scanova('track', 'pageview')
  6. تحميل SDK مرتين — وجود تثبيت مباشر في HTML وتثبيت آخر عبر GTM في الصفحة نفسها يسبب مشكلات. احذف أحدهما.

​
403 Domain not allowed

مصدر طلبك غير مدرج في قائمة Allowed Domains الخاصة بموقع التتبع.
  1. انتقل إلى التحليلات ← تتبع التحويلات
  2. انقر على موقع التتبع لديك ← Edit
  3. أضف اسم المضيف كما يظهر تمامًا في شريط عنوان المتصفح (مثل yoursite.com أو www.yoursite.com)
  4. احفظ
يُعامل www.yoursite.com وyoursite.com كنطاقين مختلفين. فأضفهما معًا إن كنت تستخدم أيًا منهما.
تُقارن قائمة السماح بترويسة Origin في الطلب (أو Referer عند غيابها). ولهذا فإن محاكاة حدث متصفح عبر curl أو من الخادم تعيد 403 Domain not allowed for this site حتى لو كان النطاق مسموحًا به، لأن أيًا من الترويستين لا يُرسل. أضف -H "Origin: https://yoursite.com" عند محاكاة حدث متصفح يدويًا.

​
400 — طلب غير صالح

قيمة site_id غير صالحة أو فارغة، أو أن الموقع أُوقف من لوحة التحكم. تحقق مما يلي:
  • أنك تستخدم site_id الصحيحة لموقع التتبع هذا
  • أن الموقع نشط (يظهر مفعّلًا في لوحة التحكم)

​
الأحداث تظهر في أدوات المطور لكنها لا تظهر في لوحة التحكم

  • انتظر حتى 60 ثانية — فهناك تأخير بسيط في المعالجة
  • تأكد أنك تنظر إلى موقع التتبع الصحيح في لوحة التحكم
  • تحقق من أن site_id في حمولة طلب الشبكة تطابق الموقع الذي تعرضه

​
يُطلق حدثان في كل تحميل للصفحة

لديك autoPageview: true في خيارات init وكذلك استدعاء يدوي scanova('track', 'page_view', ...) في مكان ما من كودك. وهذا ينتج حدثين منفصلين. احذف أحدهما — راجع الأحداث المتتبعة تلقائيًا.

​
لا تصل أي أحداث من زيارة بعينها

إن لم يظهر أي طلب إلى /ct في زيارة ما، فالسبب الأرجح أن الزائر وصل دون مسح رمز QR — إذ لا يوجد معامل ?scnv= في الرابط. فـ SDK يتحقق من وجود scan_session_id قبل إرسال أي حدث، ويتخطاه بصمت عند غيابها. لا يقيس تتبع التحويلات من Scanova سوى الزيارات القادمة من مسح رمز QR. أما الزيارات المباشرة أو من محركات البحث فلا تنتج أحداثًا — وهذا مقصود. ولاختبار النسبة، افتح صفحتك مع معامل ?scnv= لمحاكاة عملية مسح:

​
مشكلات أحداث الخادم

​
401 — مفتاح API مفقود

الترويسة X-API-Key غير مضمّنة في الطلب. راجع المصادقة.

​
403 — مفتاح غير صالح أو موقع خاطئ

إما أن المفتاح غير صالح أو مُبطل، وإما أن site_id في حمولتك لا تطابق الموقع الذي أنشأ المفتاح. تحقق مما يلي:
  • انسخ المفتاح من جديد من لوحة التحكم (فالمفاتيح تظهر مرة واحدة — وإن فقدته فأنشئ غيره)
  • تأكد أن site_id في حمولتك هي معرّف الموقع نفسه الظاهر في قائمة مواقع تتبع التحويلات
  • تأكد أن المفتاح لم يُبطل

​
422 — خطأ في التحقق

يخبرك محتوى الرد بالحقل الذي أخفق بالضبط. والأسباب الشائعة:

​
الأحداث تصل لكنها لا تُنسب إلى رمز QR

تعذّر ربط scan_session_id التي أرسلتها بأي مسح في قاعدة بيانات Scanova. ويحدث ذلك عندما:
  • تكون scan_session_id مُختلقة أو غير صالحة
  • لا يكون الزائر قد مسح رمز QR فعلًا، بل وصل مباشرة
  • تكون جلسة المسح قد انتهت صلاحيتها
تأكد أنك تقرأ scan_session_id من المتصفح (عبر localStorage._scnv، وهو مفتاح تخزين داخلي في SDK) وأنك تمررها إلى خادمك على نحو صحيح. راجع إرسال أحداث الخادم for examples.

​
مشكلات النسبة

​
الأحداث تعرض null في qr_code_id

هذا سجل يتيم — إذ وصل الحدث قبل أن تنتشر بيانات جلسة المسح بالكامل في قاعدة بيانات Scanova. وتُنظَّف هذه السجلات تلقائيًا بعد 24 ساعة إن لم تصل بيانات الجلسة أبدًا، أو تُستكمل حال وصولها. وإن رأيت سجلات يتيمة كثيرة، فتحقق مما يلي:
  • أن scan_session_id في أحداثك تخص جلسة مسح حقيقية (لا معرّفًا تجريبيًا)
  • أن رموز QR لديك مرتبطة بموقع التتبع بشكل صحيح في لوحة التحكم

​
التحويلات تظهر عند رمز QR خاطئ

لا تُقرأ scan_session_id لديك على نحو صحيح — ربما تقرأ قيمة قديمة أو خاطئة من localStorage. تأكد أن واجهتك الأمامية تقرأ localStorage.getItem('_scnv') (وهو مفتاح التخزين الداخلي في SDK) وتستخرج .sid من قيمة JSON. راجع إرسال أحداث الخادم for the full pattern.

​
مشكلات الأداء

​
429 — تجاوز حد المعدل

أنت تبلغ حد المعدل:
  • أحداث المتصفح: 100 طلب في الدقيقة لكل عنوان IP
  • أحداث الخادم: 1000 طلب في الدقيقة لكل مفتاح API
في أحداث الخادم، انتقل إلى نقطة وصول الدفعات (POST /server-events/batch) لإرسال ما يصل إلى 100 حدث في الطلب الواحد، فينخفض معدل طلباتك بما يصل إلى مئة ضعف. أما في أحداث المتصفح فنادرًا ما يظهر 429 في الاستخدام المعتاد. وإن ظهر أثناء اختبار الحِمل، فباعد بين طلباتك.