دفع الأحداث المخصصة إلى Google Tag Manager و Analytics

[Discourse]

استمرارًا للنقاش من دمج Google Tag Manager مع Google Analytics:

إرسال الأحداث المخصصة إلى Google Tag Manager و Analytics

يشرح هذا الدليل كيفية تكوين موقع Discourse الخاص بك لإرسال أحداث مخصصة إلى Google Tag Manager (GTM) و Google Analytics، مما يسمح لك بتتبع تفاعلات المستخدم المحددة.

مستوى المستخدم المطلوب: مسؤول (Administrator)

المتطلبات الأساسية

قبل تطبيق الأحداث المخصصة، تأكد من أن لديك:

1. تكوين Google Tag Manager على موقع Discourse الخاص بك باتباع دليل إعداد Google Tag Manager لـ Analytics
2. إضافة معرّف حاوية GTM الخاص بك إلى إعداد gtm container id لموقعك
3. تحديث إعداد content security policy script src لموقعك للسماح لبرامج Google النصية (scripts)

إضافة أحداث مخصصة

إنشاء مكون سمة (Theme Component)

1. انتقل إلى مسؤول (Admin) > تخصيص (Customize) > مكونات (Components)
2. انقر على “جديد” (New) واختر “إنشاء مكون جديد” (Create new component)
3. أعطِ المكون الخاص بك اسمًا
4. حدد علامة التبويب JS وأضف الكود الخاص بك. على سبيل المثال، يأخذ الكود أدناه مشغلات appEvent ويدفع الأحداث التالية إلى dataLayer:

• post:liked
• post:created
• topic:created

import { apiInitializer } from "discourse/lib/api";

export default apiInitializer((api) => {
  window.dataLayer = window.dataLayer || [];

  // تتبع الإعجابات على المشاركات
  api.onAppEvent("page:like-toggled", (post, likeAction) => {
    let topic = post.topic;
    if (post && topic && likeAction && likeAction.acted) {
      window.dataLayer.push({
        'event': 'postLiked',
        'postId': post.id
      });
    }
  });

  // تتبع المشاركات الجديدة
  api.onAppEvent("post:created", post => {
    if (post) {
      window.dataLayer.push({
        'event': 'postCreated',
        'postId': post.id
      });
    }
  });

  // تتبع المواضيع الجديدة
  api.onAppEvent("topic:created", (post, composerModel) => {
    if (post) {
      window.dataLayer.push({
        'event': 'topicCreated',
        'topicCategory': composerModel.get("category.name"),
        'topicId': post.topic_id
      });
    }
  });
});

5. احفظ المكون
6. أضف المكون إلى جميع السمات النشطة على موقعك

الأحداث المتاحة

جميع أحداث التشغيل المتاحة مدرجة هنا: مرجع مشغلات AppEvents

تكوين GTM

إنشاء مشغل (Trigger)

1. انتقل إلى https://tagmanager.google.com/
2. حدد “المشغلات” (Triggers) من القائمة الجانبية
3. انقر على “جديد” (New)
4. قم بتسمية المشغل الخاص بك
5. حدد “حدث مخصص” (Custom Event) كنوع المشغل
6. أدخل اسم الحدث (على سبيل المثال postCreated)
7. اضبط المشغل ليتم إطلاقه على “جميع الأحداث المخصصة” (All Custom Events)

إنشاء متغير طبقة البيانات (Data Layer Variable)

1. حدد “المتغيرات” (Variables) من القائمة الجانبية لـ GTM
2. انقر على “جديد” (New) في قسم متغيرات المستخدم المحددة (User-Defined Variables)
3. قم بتسمية المتغير الخاص بك
4. حدد “متغير طبقة البيانات” (Data Layer Variable) كنوع المتغير
5. أدخل اسم متغير طبقة البيانات (على سبيل المثال postCreated)
6. اضبط إصدار طبقة البيانات (Data Layer Version) على “الإصدار 2” (Version 2)

إنشاء علامة Google لتتبع الأحداث

اعتبارًا من عام 2024، يتمثل النهج الموصى به في استخدام قالب “علامة Google” (Google Tag) الجديد بدلاً من نوع العلامة الأقدم “Google Analytics: GA4 Event”. توفر علامة Google تكاملاً أفضل مع GA4 وتتضمن دعمًا مضمنًا لـ Consent Mode v2.

1. حدد “العلامات” (Tags) من القائمة الجانبية لـ GTM
2. انقر على “جديد” (New)
3. قم بتسمية علامتك (على سبيل المثال “GT - Post Created”)
4. ضمن إعداد العلامة (Tag Configuration):
   • حدد “علامة Google” (Google Tag)
   • اختر إعداد تكوين GA4 الخاص بك (أو أنشئ واحدًا جديدًا إذا كانت هذه هي علامتك الأولى)
   • بالنسبة لـ “اسم الحدث” (Event Name)، أدخل اسمًا وصفيًا يتبع اصطلاحات تسمية GA4 (على سبيل المثال post_created)
   • ضمن “إعدادات التكوين” (Configuration settings)، انقر على “إضافة صف” (Add Row) لتضمين متغيرات طبقة البيانات الخاصة بك:
     • معامل التكوين (Configuration Parameter): (على سبيل المثال postId)
     • القيمة (Value): متغير طبقة البيانات الخاص بك (على سبيل المثال {{postCreated}})
5. ضمن “التشغيل” (Triggering):
   • حدد مشغل الحدث المخصص الذي أنشأته مسبقًا

إذا كنت تستخدم حاليًا علامات “Google Analytics: GA4 Event”، فستستمر في العمل، ولكن يجب أن تستخدم التنفيذ الجديد قالب “علامة Google” لتوافق أفضل في المستقبل وميزات إضافية.

متطلبات تسمية الأحداث

لدى GA متطلبات محددة لأسماء الأحداث:

• استخدم snake_case (أحرف صغيرة مع شرطات سفلية)
• الحد الأقصى للطول 40 حرفًا
• يمكن أن تحتوي فقط على أحرف أبجدية رقمية وشرطات سفلية

اختبار علامة Google الخاصة بك

1. انقر على زر “معاينة” (Preview) في GTM
2. انتقل إلى موقع Discourse الخاص بك
3. قم بإجراء الإجراء الذي تريد تتبعه (على سبيل المثال إنشاء مشاركة)
4. في وضع معاينة GTM:
   • تحقق من ظهور الحدث المخصص الخاص بك في اللوحة اليسرى
   • تأكد من إطلاق علامة Google الخاصة بك بشكل صحيح
   • تأكد من تمرير جميع المعاملات (parameters) كما هو متوقع
5. في Google Analytics:
   • انتقل إلى التكوين (Configure) > الأحداث (Events)
   • يجب أن يظهر الحدث المخصص الخاص بك في القائمة بعد تشغيله
   • ملاحظة: قد يستغرق الأمر ما يصل إلى 24 ساعة حتى تظهر الأحداث الجديدة في تقارير GA4

يمكنك استخدام عرض تصحيح أخطاء GA4 (GA4 DebugView) لعرض بيانات الأحداث في الوقت الفعلي أثناء الاختبار.

استكشاف الأخطاء وإصلاحها

إذا لم تظهر الأحداث في GTM:

1. تحقق من تعيين معرّف حاوية GTM الخاص بك بشكل صحيح في Discourse
2. تأكد من إضافة مكون السمة الخاص بك إلى جميع السمات النشطة
3. أضف عبارات console.log للتحقق من إطلاق الأحداث:

api.onAppEvent("post:created", post => {
  console.log("post:created event triggered");
  if (post) {
    window.dataLayer.push({
      'event': 'postCreated',
      'postId': post.id
    });
  }
});

4. استخدم إضافة متصفح Chrome عارض طبقة البيانات البسيط (Simple Data Layer Viewer) لمراقبة طبقة البيانات
5. إذا رأيت أخطاء في سياسة أمان المحتوى (CSP)، يرجى الرجوع إلى المتطلبات الأساسية المشار إليها أعلاه، ومراجعة Mitigate XSS Attacks with Content Security Policy للحصول على خطوات إضافية.

إذا كان لديك إعداد الموقع ga universal tracking code مهيأ، فقم بإفراغه حيث سيتولى GTM مهمة برنامج نصي التتبع.