مقتطف التتبع عبارة عن برنامج نصي صغير غير متزامن — حجمه بضعة كيلوبايت ويُقدَّم عبر مسار تابع للطرف الأول مخزّن مؤقتاً على الحافة — يحدّد المؤسسة التي تقف وراء كل جلسة. عند تثبيته بشكل صحيح، لن تلاحظ وجوده أبداً. أما إذا ثُبّت بشكل خاطئ، فستقضي أسبوعاً في استكشاف سبب غياب الشركات التي جرى التعرّف إليها، قبل أن تكتشف أن أداة التحميل كانت داخل جزء لا يُحمَّل إلا عند الحاجة. يساعدك هذا الدليل على تجنّب ذلك الأسبوع.
ثلاثة مبادئ قبل أن تلصق أي شيء
- مكان أداة التحميل هو وسم head العام للموقع. ليس في التذييل، ولا في قالب صفحة محددة، ولا في مكوّن لا يظهر إلا على صفحات التسويق. بل داخل head وعلى كل صفحة.
- أداة التحميل غير متزامنة افتراضياً. لا تضف تعديلاً على defer أو async يغيّر توقيت تنفيذها؛ فالسمات المرفقة هي التي اختبرناها.
- ثبّتها مرة واحدة بالضبط. وجود نسختين من أداة التحميل في الصفحة نفسها لا يضاعف بياناتك، بل يضاعف الطلبات ويُربك عملية استكشاف الأخطاء وإصلاحها.
WordPress
أنظف طريقة للتثبيت على WordPress هي تجنّب تعديل القالب. استخدم إضافة لإدراج البرامج النصية في الترويسة — ستفي أي إضافة معروفة بالغرض — والصق أداة التحميل في حقل "scripts in head"، ثم احفظ وامسح أي ذاكرة تخزين مؤقت للصفحات. وإذا لم ترغب في استخدام إضافة، فأضف ملف mu-plugin صغيراً يرتبط بخطاف wp_head بأولوية 5، كي تظهر أداة التحميل قبل وسوم التحليلات. لا تلصقها داخل محتوى صفحة أو مقالة، لأن WordPress سيزيل وسم البرنامج النصي أثناء التنقية.
هناك فحص خاص بـWordPress: إذا كنت تستخدم تخزيناً مؤقتاً للصفحة بالكامل، مثل LiteSpeed أو WP Rocket أو W3 Total Cache، فامسح ذاكرة التخزين المؤقت بعد التثبيت. لن تتضمن صفحات HTML المخزّنة مؤقتاً قبل التثبيت أداة التحميل.
Shopify
يضع Shopify ملف HTML الخاص بالقالب في theme.liquid. من لوحة إدارة Shopify، افتح Online Store → Themes → Actions → Edit code → theme.liquid، ثم الصق أداة التحميل مباشرة قبل وسم الإغلاق </head>. احفظ التغييرات. هذا كل شيء — لا حاجة إلى تطبيق أو برنامج نصي لصفحة الدفع، إذ إن صفحة الدفع خارج نطاق التعرّف على مستوى الشركات على أي حال.
أنشئ نسخة من القالب أولاً
قبل تعديل theme.liquid، استخدم Actions → Duplicate. إذا حدث أي خطأ، يمكنك الرجوع بنقرة واحدة. إنها عادة لا تستغرق سوى خمس ثوانٍ، وقد أفادت كل فريق Shopify اقتُرحت عليه.
Webflow
انتقل إلى Webflow → Site Settings → Custom Code → Head Code. الصق أداة التحميل، ثم احفظ وانشر الموقع. يُطبَّق الكود الموجود في head على جميع الصفحات، وهذا بالضبط ما تريده. لا تلصق أداة التحميل في عنصر تضمين على مستوى صفحة واحدة، وإلا فلن تتعقب سوى تلك الصفحة.
Google Tag Manager
يعمل GTM، لكن مع ملاحظتين. أولاً، استخدم وسم Custom HTML واضبط المشغّل على "All Pages" لكي تعمل أداة التحميل عند كل مشاهدة للصفحة. ثانياً، امنح الوسم أولوية عالية بما يكفي ليعمل قبل وسوم التحليلات الأخرى التي قد تبطئ الحمولة الأولية. غالباً ما يضع مستخدمو GTM أربعة أو خمسة وسوم في head؛ وأداة التحميل صغيرة، لكن ترتيب تشغيل الوسوم مهم إذا كنت تريد التعرّف إلى الشركة منذ الطلب الأول.
تنبيه بشأن وضع الموافقة: إذا كنت تشغّل GTM خلف لافتة موافقة لا تطلق وسوم التحليلات إلا بعد موافقة الزائر، فلا تضع التعرّف على مستوى الشركات خلف البوابة نفسها؛ فهو لا يستخدم ملفات تعريف الارتباط ولا يخزّن بيانات على جهاز الزائر، ولذلك لا يتطلب مستوى الموافقة نفسه. اضبط الوسم ليعمل فوراً إلى جانب الوسوم الضرورية للغاية.
HTML عادي / حِزم تقنية مخصصة
بالنسبة إلى موقع مطوّر يدوياً أو إطار عمل لم نذكره، الصق أداة التحميل داخل عنصر <head> في القالب الأساسي، أي الملف الذي يظهر في كل صفحة. ثم أعد البناء والنشر. وفي مولدات المواقع الثابتة، يجب وضع أداة التحميل في ملف التخطيط العام للموقع (في Next.js، تكون <Script> داخل التخطيط على مستوى التطبيق مع strategy="afterInteractive"؛ وفي Astro، تكون في مكوّن <BaseHead>؛ وفي 11ty، تكون في الجزء الخاص بالقالب الأساسي). إذا أضفتها كبرنامج نصي على مستوى مكوّن، فلن ترسل البيانات إلا الصفحات التي تتضمن ذلك المكوّن.
تطبيقات الصفحة الواحدة — الملاحظة الوحيدة المهمة
في تطبيق SPA، تلتقط أداة التحميل مشاهدة الصفحة الأولية عند تحميل الصفحة لأول مرة. أما عمليات التنقل اللاحقة من جهة العميل، فلا تُعد مشاهدات تلقائية للصفحة من منظور المتصفح. تستمع أداة التحميل لدينا إلى History API افتراضياً، ولذلك تُسجَّل عمليات الرجوع والتقدم والتنقل المستندة إلى pushState كمشاهدات جديدة للصفحة من دون أي كود إضافي منك. إذا كان تطبيق SPA لديك يستخدم موجّهاً غير قياسي يتجاوز History API — وهو أمر نادر، لكنه يحدث — فاستدعِ دالة مشاهدة الصفحة الصغيرة والموثقة عند تغيّر المسار؛ وهي ثلاثة أسطر مشار إليها في الوثائق.
تحقّق من التثبيت خلال دقيقتين
التحقق ليس اختيارياً. نفّذه قبل إغلاق علامة التبويب التي ثبّتت منها أداة التحميل؛ فاكتشاف تثبيت معطّل بعد خمس دقائق من اللصق أمر يسهل إصلاحه، بخلاف اكتشافه بعد خمسة أيام.
- افتح موقعك في نافذة خاصة أو للتصفح المتخفي، حتى لا تربكك الأصول المخزّنة مؤقتاً.
- افتح DevTools → علامة تبويب Network، ثم رشّح النتائج باستخدام "l5e" أو مسار أداة التحميل.
- أعد تحميل الصفحة. يفترض أن ترى طلباً واحداً لأداة التحميل، يليه طلب تعريف صغير. يجب أن تكون حالة كليهما 200. كما ينبغي أن تتضمن ترويسات استجابة أداة التحميل توجيه cache-control يحتوي على s-maxage وstale-while-revalidate.
- انتقل إلى صفحة ثانية. ينبغي أن ترى إطلاق طلب تعريف إضافي واحد من دون إعادة تنزيل أداة التحميل، إذ ستكون حالته 304.
- ارجع إلى لوحة معلومات lead.box، وافتح تدفق الزوار المباشر، وتأكد من ظهور زيارتك التجريبية. إذا ظهرت، فقد اكتمل التثبيت.
الأخطاء الشائعة — الجدول الذي ينبغي فحصه أولاً
| العَرَض | السبب المحتمل | الحل |
|---|---|---|
| لا توجد أي زيارات مباشرة | أداة التحميل غير موجودة في head أو موجودة في القالب الخطأ | انقل أداة التحميل إلى قالب head العام للموقع |
| الزيارات المباشرة تأتي من قسم واحد فقط | أداة التحميل داخل عنصر تضمين على مستوى الصفحة وليست عامة | انقلها إلى head العام / ترويسة القالب |
| تُحمَّل الأداة لكن لا يُرسل طلب التعريف | لافتة الموافقة تحظر البرامج النصية التابعة لأطراف ثالثة بشكل مفرط | اضبط اللافتة للسماح بما هو ضروري للغاية؛ أداة التحميل لا تحتاج إلى موافقة |
| طلبا تعريف لكل مشاهدة صفحة | أداة التحميل مثبّتة مرتين (القالب + الإضافة/الوسم) | أزل إحداهما |
| بطء العرض الأول بعد التثبيت | وُضعت أداة التحميل قبل CSS الحرج | تأكد من وجود سمة async، وضعها بعد التحميل المسبق لـCSS الحرج |
| لا يسجّل تطبيق SPA سوى الصفحة الأولى | الموجّه المخصص يتجاوز History API | استدعِ دالة pageview() الموثقة عند تغيّر المسار |
| تُعرض صفحة HTML قديمة بلا أداة التحميل | لم تُمسح ذاكرة التخزين المؤقت للصفحة بالكامل بعد التثبيت | امسح ذاكرة التخزين المؤقت وتحقق في وضع التصفح المتخفي |
ملاحظة حول الأداء — أداة تحميل مخزّنة على الحافة
تُقدَّم أداة التحميل من مسار تابع للطرف الأول يمر عبر وكيل إلى ذاكرة التخزين المؤقت الطرفية لدينا، مع s-maxage=300 وstale-while-revalidate. عملياً، يعني ذلك جلب أداة التحميل مرة واحدة كل خمس دقائق لكل نقطة حضور طرفية، ثم تقديمها من ذاكرة التخزين المؤقت إلى كل زائر لاحق. حجمها بالبايت وتأثيرها في الحجب صغيران بما يكفي لعدم توصيتنا بإضافة منطق تحميل آخر فوقها.
متى تطلب المساعدة
إذا نفّذت خطوات التحقق وما زال هناك خلل، فنحن نفضّل أن تتواصل معنا بعد عشر دقائق بدلاً من الانتظار عشرة أيام. جهّز ثلاثة أشياء: عنوان URL للموقع، ولقطة شاشة لعلامة تبويب Network في DevTools بعد ترشيحها وفق مسار أداة التحميل، واسم المنصة التي ثبّت الأداة عليها. تكفي هذه المعلومات لتشخيص معظم مشكلات التثبيت من أول رد.
Published by
lead.box Team
More articles
شاهد lead.box على حركة زياراتك أنت
ابدأ مجانًا — بلا بطاقة دفع وبلا اتصال إلزامي. أو احجز عرضًا توضيحيًا من 20 دقيقة.