إضافة تحليلات تُقدِّم الخصوصية أولاً إلى موقع Astro

تُبدِّل انتقالات العرض في Astro محتوى الصفحة في مكانه دون إعادة تحميل كاملة للمتصفح — مما يعني أن أي نص تحليلات يعتمد على DOMContentLoaded أو load لن يعمل إلا مرة واحدة، عند الزيارة الأولى. وكل تنقل لاحق من جانب العميل يكون غير مرئي. هذا ليس خطأ تكوين منك؛ بل هو نتيجة جوهرية لكيفية عمل ClientRouter.

توجد مشكلة التتبع الصامت نفسها في SvelteKit 2 وRemix، لكن الحل في كل إطار عمل مختلف. في Astro، الجواب هو حدث دورة حياة astro:page-load.

لماذا يفشل وسم النص المعتاد

عندما يكون <ClientRouter /> نشطاً (يتم اشتراكه عبر astro:transitions في Astro 4، ومُفعَّل افتراضياً في Astro 5)، لا تُفرَّغ الصفحة عند التنقلات. يجلب Astro الصفحة التالية في الخلفية، ويُبدِّل DOM، ويُحدِّث الـ URL — كل ذلك دون تدمير سياق JavaScript الحالي.

يُعامَل نص المُتتبِّع المُحمَّل عبر وسم <script> بسيط على أنه نص وحدة مُحزَّم بواسطة خط أنابيب بناء Astro. تُنفَّذ نصوص الوحدات المُحزَّمة مرة واحدة بالضبط لكل جلسة صفحة. يُهيَّأ المُتتبِّع، ويُطلِق مشاهدة صفحة لصفحة الوصول، ثم لا يعمل ثانية بينما يتنقل المستخدم.

لإطلاق حدث في كل تنقل، يجب توصيل منطق التهيئة بدورة حياة التنقل في Astro. الخطاف الصحيح هو astro:page-load، الذي يُطلَق بعد أن تصبح الصفحة الجديدة مرئية وتُحمَّل جميع النصوص الحاجبة — في كل من التحميل الأولي وكل انتقال لاحق.

التكامل الصحيح

أضف نص المُتتبِّع مرة واحدة في تخطيط الجذر لديك (src/layouts/Layout.astro أو ما يعادله)، ثم اربط مُستمِعاً لـ astro:page-load:

---
// Layout.astro
---
<html lang="en">
  <head>
    <!-- your head content -->
  </head>
  <body>
    <slot />

    <script
      is:inline
      src="https://api.monoid.website/tracker.min.js"
      data-site-id="YOUR_SITE_ID"
      async
    ></script>
  </body>
</html>

تُخبر تعليمة is:inline مُحزِّم Astro بترك هذا النص كما هو تماماً. بدونها، سيُعالج Astro النص كوحدة، ويُزيل التكرار، ويُثبِّط إعادة التنفيذ. مع is:inline، يُصدَر وسم النص حرفياً في مخرجات HTML لكل صفحة.

للمواقع التي لا تستخدم انتقالات العرض، هذا كل ما تحتاجه. يُطلَق المُتتبِّع مرة واحدة عند التحميل وانتهيت.

التعامل مع تنقل انتقالات العرض

إذا كان موقعك يستخدم <ClientRouter />، فلا حاجة لأي تكوين إضافي — لكن يجدر التدقيق في السبب، لأن التفسير الشائع خاطئ.

المُتتبِّع لا يستمع إلى astro:page-load ولا إلى أي حدث آخر من أحداث دورة حياة Astro. إنه يُرقِّع history.pushState عند تحميله. ومُوجِّه Astro يُحدِّث عنوان URL عبر استدعاء History API نفسه، فتعمل الدالة المُرقَّعة عند كل انتقال وترسل مشاهدة صفحة. يقع الخطاف أسفل طبقة أحداث Astro بدلاً من الاستماع إليها.

للتحقق، افتح علامة تبويب الشبكة في DevTools وفلتر حسب collect. تنقَّل بين صفحتين. ينبغي أن ترى طلب POST واحداً لكل تنقل، بما في ذلك التحميل الأول.

تحذير جدير بالمعرفة: يغطي الخطاف pushState وليس popstate. فالضغط على زر الرجوع أو التقدم في المتصفح يُغيِّر المسار دون استدعاء pushState، ولذلك لا يُنتِج حالياً مشاهدة صفحة جديدة.

لا يُتيح المُتتبِّع أي دالة يدوية لتسجيل مشاهدة صفحة. الكائن العام يقبل الأحداث المخصصة فقط:

<script>
  // أحداث مخصصة فقط — لا وجود لاستدعاء trackPageview().
  // يجب أن يطابق الاسم [a-z0-9_][a-z0-9_-]{0,63}.
  window.monoid('event', 'signup_started');
</script>

فصل البيئات

عادةً ما تحتوي مشاريع Astro على بيئات تطوير محلي، ومعاينة، وإنتاج. استخدم متغير بيئة لحمل site_id ومنع التتبع في التطوير:

---
const siteId = import.meta.env.PUBLIC_MONOID_SITE_ID
---

{siteId && (
  <script
    is:inline
    src="https://api.monoid.website/tracker.min.js"
    data-site-id={siteId}
    async
  ></script>
)}

عيِّن PUBLIC_MONOID_SITE_ID في .env للإنتاج واتركه غير مُعيَّن محلياً. يكشف Astro المتغيرات المسبوقة بـ PUBLIC_ للعميل؛ أما المتغيرات الخاصة بالخادم فقط (دون البادئة) فلا تظهر في الكود المُنفَّذ في المتصفح.

ما لا تحتاجه

لا لافتة موافقة على الكوكيز. لا تكامل CMP. تحسب نقطة نهاية التجميع تجزئة زائر يومية من عنوان IP وUser-Agent وسر من جهة الخادم والتاريخ الحالي:

visitor_hash = SHA-256(IP + UA + SALT_SECRET + YYYY-MM-DD)

تُعاد تهيئة التجزئة كل 24 ساعة. لا يُخزَّن شيء على جهاز الزائر. تُستنبط عائلة المتصفح العامة ونوع الجهاز من جهة الخادم من User-Agent الخاص بالطلب لأغراض إعداد التقارير الإجمالية — أما سلاسل User-Agent الكاملة وإصدارات المتصفح والمُعرِّفات الدائمة فلا تُخزَّن أبداً.

مواقع Astro غالباً ما تكون ثابتة كلياً أو مُقدَّمة من الحافة بأقل قدر من JavaScript. إضافة نص تحليلات أقل من 2 كيلوبايت دون كوكيز ودون اشتراط موافقة تتناسب طبيعياً مع تلك الفلسفة. لا توجد حزمة npm لصيانتها، ولا SDK لتحديثه، ولا أساس قانوني بموجب GDPR لتوثيقه من أجل معالجة التحليلات.

المصادر

• انتقالات العرض - وثائق Astro
• مرجع توجيهات القوالب - وثائق Astro
• متغيرات البيئة - وثائق Astro
• SubtleCrypto: طريقة digest() - MDN