Adding Privacy-First Analytics to an Astro Site

تُبدِّل انتقالات العرض في 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 />، فإن خطاف history.pushState المدمج في المُتتبِّع يُطلَق بشكل صحيح بعد كل انتقال — يستمع المُتتبِّع لأحداث التنقل في Astro داخلياً. لا حاجة لأي تكوين إضافي.

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

إن كنت تحقن المُتتبِّع شرطياً وتحتاج إلى أن يُعيد التهيئة بعد كل مبادلة (على سبيل المثال، بعد تركيب جزيرة ديناميكية)، يمكنك تشغيل إعادة التنفيذ يدوياً:

<script data-astro-rerun>
  // This block re-executes after every View Transition.
  // Use sparingly — most tracker logic should not live here.
  if (window.__monoid) {
    window.__monoid.trackPageview();
  }
</script>

تُجبر سمة data-astro-rerun النصوص المضمَّنة على إعادة التنفيذ بعد كل انتقال. لاحظ أنها تستلزم is:inline، فلا تنطبق إلا على النصوص غير المُحزَّمة.

فصل البيئات

عادةً ما تحتوي مشاريع 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 لتوثيقه من أجل معالجة التحليلات.