طبقة البيانات

طبقة البيانات هي عنصر تستخدمه أداة Google Tag Manager ومقتطف gtag.js لتمرير المعلومات إلى العلامات. يمكن تمرير الأحداث أو المتغيّرات باستخدام طبقة البيانات، ويمكن إعداد عوامل التشغيل استنادًا إلى قيم المتغيّرات.

على سبيل المثال، إذا أطلقت علامة تجديد نشاط تسويقي عندما تكون قيمة purchase_total أكبر من 100 دولار أمريكي، أو استنادًا إلى أحداث معيّنة، مثل النقر على زر، يمكن ضبط طبقة البيانات لإتاحة هذه البيانات لعلاماتك. يتم تنظيم عنصر طبقة البيانات بتنسيق JSON. على سبيل المثال:

{
  event: "checkout_button",
  gtm: {
    uniqueEventId: 2,
    start: 1639524976560,
    scrollThreshold: 90,
    scrollUnits: "percent",
    scrollDirection: "vertical",
    triggers: "1_27"
  },
  value: "120"
}

تم تصميم علامات التتبُّع من Google للإشارة إلى المعلومات التي تتم إضافتها إلى طبقة البيانات بطريقة منظَّمة ويمكن توقّعها، بدلاً من تحليل المتغيّرات ومعلومات المعاملات وفئات الصفحات والإشارات الأخرى المنتشرة في صفحتك. سيساعد تنفيذ طبقة البيانات التي تم ملؤها بالمتغيرات والقيم المرتبطة بها في ضمان توفر البيانات ذات الصلة عندما تحتاجها علاماتك.

تثبيت

بالنسبة إلى عمليات تثبيت صفحات الويب في أداة Tag Manager، عليك إنشاء طبقة بيانات. يوضّح مثال الرمز البرمجي التالي مكان إنشاء طبقة البيانات، قبل تحميل أداة "إدارة العلامات من Google".

<script>
window.dataLayer = window.dataLayer || [];
</script>
<!-- Google Tag Manager -->
<script>(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start':
new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0],
j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src=
'https://www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f);
})(window,document,'script','dataLayer','GTM-XXXXXX');</script>
<!-- End Google Tag Manager -->

في عمليات التنفيذ العادية لملف gtag.js حيث تم نسخ العلامة من داخل المنتج وإضافتها إلى صفحة ويب، يتم توفير الرمز لإنشاء طبقة البيانات. في عمليات التنفيذ المخصّصة لعلامة التتبُّع من Google، أضِف رمز طبقة البيانات في بداية النص البرمجي، كما هو موضّح في مثال الرمز التالي:

<!-- Google tag -->
<script async src="https://www.googletagmanager.com/gtm.js?id=TAG_ID"></script>
<script>
  window.dataLayer = window.dataLayer || [];
  function gtag(){dataLayer.push(arguments);}
  gtag('js', new Date());
</script>

ملاحظة: يحدّد معرّف الحاوية في عنوان URL لمصدر المقتطف (مثل GTM- مقابل G- أو AW-) أذونات تنفيذ النص البرمجي وإمكاناته. لمزيد من التفاصيل، يُرجى الاطّلاع على أنواع الحاويات وبادئات أرقام التعريف.

كيفية معالجة معلومات طبقة البيانات

عند تحميل حاوية، ستبدأ "إدارة العلامات من Google" في معالجة جميع رسائل الدفع في طبقة البيانات المُدرَجة في قائمة الانتظار. يعالج Tag Manager الرسائل على أساس الوارد أولاً يُباع أولاً (FIFO): تتم معالجة كل رسالة على حدة، بالترتيب الذي تم استلامها به. إذا كانت الرسالة حدثًا، سيتم تنشيط أي علامات تتضمّن شروط مشغّلات تم استيفاؤها قبل انتقال "إدارة العلامات من Google" إلى الرسالة التالية.

إذا تم إجراء مكالمة gtag() أو dataLayer.push() بواسطة رمز على صفحة أو في نموذج مخصّص أو في علامة HTML مخصّصة، يتم وضع الرسالة المرتبطة في قائمة الانتظار ومعالجتها بعد تقييم جميع الرسائل الأخرى في انتظار المراجعة. وهذا يعني أنّه لا يمكن ضمان توفّر أيّ قيم معدَّلة لطبقة البيانات للحدث التالي. للتعامل مع هذه الحالات، عليك إضافة اسم حدث إلى رسالة عند إرسالها إلى طبقة البيانات، ثم الاستماع إلى اسم الحدث هذا باستخدام مشغّل حدث مخصّص.

ملاحظة مهمة: لا تستخدِم علامات HTML المخصّصة لنشر رمز مستند إلى gtag.js. بدلاً من ذلك، استخدِم نماذج العلامات الأصلية في أداة "إدارة العلامات من Google" لكلّ من إعلانات Google وإحصاءات Google وFloodlight.

ملاحظة مهمة: لا تستخدِم علامات HTML المخصّصة لضبط إعدادات الموافقة في أداة "إدارة العلامات من Google". بما أنّه يجب تطبيق إعدادات الموافقة قبل تنشيط العلامات ذات الصلة في حاوية Tag Manager، عليك تطبيق واجهات برمجة تطبيقات وضع الموافقة في Tag Manager لضبط السلوك التلقائي وسلوك التعديل. استخدِم واجهات برمجة تطبيقات وضع الموافقة في أداة Tag Manager للتأكّد من معالجة تعديلات الموافقة قبل أي عناصر مدرَجة بقائمة الانتظار في طبقة البيانات لكي تحصل جميع العلامات التي ينشِّطها الحدث نفسه على حالة الموافقة نفسها.

نقطة أساسية: يمكنك استخدام Google Tag Assistant لفحص حالة طبقة البيانات في أي نقطة في سلسلة من الأحداث.

استخدام طبقة بيانات مع معالِجات الأحداث

يستخدم العنصر dataLayer الأمر event لبدء إرسال الأحداث.

تستخدِم علامة تتبُّع من Google وTag Manager متغيّرًا خاصًا لطبقة البيانات يُسمّى event، ويستخدِمه متتبِّعو أحداث JavaScript لتنشيط العلامات عندما يتفاعل مستخدِم مع عناصر الموقع الإلكتروني. على سبيل المثال، قد تحتاج إلى تنشيط علامة تتبُّع الإحالات الناجحة عندما ينقر المستخدم على زر تأكيد الشراء. يمكن استدعاء الأحداث عندما يتفاعل المستخدم مع عناصر الموقع الإلكتروني، مثل الروابط والأزرار وأشرطة التمرير وما إلى ذلك.

يتم تنفيذ هذه الوظيفة من خلال استدعاء dataLayer.push() عند وقوع حدث. في ما يلي بنية إرسال حدث باستخدام dataLayer.push():

dataLayer.push({'event': 'event_name'});

حيث تكون السمة event_name عبارة عن سلسلة تصف الحدث، مثل 'login' أو 'purchase' أو 'search'.

استخدِم dataLayer.push() لإرسال بيانات الأحداث عند حدوث إجراء تريد قياسه. على سبيل المثال، لإرسال حدث عندما ينقر مستخدم على زر، يمكنك تعديل معالج onclick للزر لاستدعاء dataLayer.push():

<button onclick="dataLayer.push({'event': 'login'});">Button 1</button>

يمكنك إرسال متغيّرات طبقة البيانات إلى طبقة البيانات بشكل ديناميكي لتسجيل معلومات مثل القيم التي تم إدخالها أو اختيارها في نموذج، والبيانات الوصفية المرتبطة بفيديو يشغّله الزائر، ولون المنتج (على سبيل المثال، سيارة) الذي خصّصه الزائر، وعناوين URL المقصودة للروابط التي تم النقر عليها، وما إلى ذلك.

كما هو الحال مع الأحداث، يتم تنفيذ هذه الوظيفة من خلال استدعاء واجهة برمجة التطبيقات push() لإضافة متغيّرات طبقة البيانات أو استبدالها في طبقة البيانات. في ما يلي البنية الأساسية لضبط متغيّرات طبقة البيانات الديناميكية:

dataLayer.push({'variable_name': 'variable_value'});

حيث 'variable_name' هي سلسلة تشير إلى اسم متغيّر طبقة البيانات الذي سيتم ضبطه، و'variable_value' هي سلسلة تشير إلى قيمة متغيّر طبقة البيانات الذي سيتم ضبطه أو استبداله.

على سبيل المثال: لضبط متغيّر طبقة بيانات باستخدام لون مفضّل عندما يتفاعل أحد الزوّار مع أداة تخصيص منتج، يمكنك إرسال متغيّر طبقة البيانات الديناميكي التالي:

dataLayer.push({'color': 'red'});

إرسال واحد، متغيّرات متعددة

يمكنك إرسال متغيّرات وأحداث متعدّدة في آنٍ واحد:

dataLayer.push({
  'color': 'red',
  'conversionValue': 50,
  'event': 'customize'
});

ملاحظة مهمة: إذا أرسلت متغيّرًا يحمل الاسم نفسه لمتغيّر حالي إلى طبقة البيانات، سيتم استبدال القيمة الحالية بالقيمة الجديدة.

الاحتفاظ بمتغيّرات طبقة البيانات

للاحتفاظ بمتغيّرات طبقة البيانات بين صفحات الويب، يمكنك استدعاء dataLayer.push() بعد إنشاء مثيل لطبقة البيانات عند تحميل كل صفحة، وإرسال المتغيّرات إلى طبقة البيانات. إذا أردت أن تكون متغيّرات طبقة البيانات هذه متاحة لأداة Tag Manager عند تحميل الحاوية، أضِف طلب dataLayer.push() أعلى رمز حاوية أداة Tag Manager كما هو موضّح في المثال التالي:

<script>
window.dataLayer = window.dataLayer || [];

dataLayer.push({
  'event': 'Pageview',
  'pagePath': 'https://www.googleanalytics.dev/pancakes',
  'pageTitle': 'Pancake Event Signup',
  'visitorType': 'customer'
});
</script>
<!-- Google Tag Manager -->
<script>(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start':
new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0],
j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src=
'https://www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f);
})(window,document,'script','dataLayer','GTM-XXXXXX');</script>
<!-- End Google Tag Manager -->

سيستمر كل متغيّر تم الإعلان عنه ضمن عنصر طبقة البيانات فقط طالما بقي الزائر في الصفحة الحالية. يجب الإعلان عن متغيّرات طبقة البيانات ذات الصلة على مستوى الصفحات (مثل visitorType) في طبقة البيانات على كل صفحة من صفحات موقعك الإلكتروني. على الرغم من أنك لست بحاجة إلى وضع نفس مجموعة المتغيرات في طبقة البيانات في كل صفحة، يجب عليك استخدام اصطلاح تسمية متسق. بعبارة أخرى: إذا ضبطت فئة الصفحة على صفحة الاشتراك باستخدام متغيّر باسم pageCategory، يجب أن تستخدم صفحات المنتج والشراء المتغيّر pageCategory أيضًا.

تحديد المشاكل وحلّها

في ما يلي بعض النصائح لتحديد المشاكل في طبقة البيانات وحلّها:

عدم استبدال المتغيّر window.dataLayer: عند استخدام طبقة البيانات مباشرةً (على سبيل المثال، dataLayer = [{'item': 'value'}])، سيتم استبدال أي قيم حالية في dataLayer. يجب أن تنشئ عمليات تثبيت Tag Manager طبقة البيانات في أعلى الرمز المصدر قدر الإمكان، فوق مقتطف الحاوية، باستخدام window.dataLayer = window.dataLayer || [];. بعد الإعلان عن dataLayer، استخدِم dataLayer.push({'item': 'value'}) لإضافة قيم أخرى إليه، وإذا كانت هذه القيم يجب أن تكون متاحة لأداة "إدارة العلامات من Google" عند تحميل الصفحة، يجب أن يكون طلب dataLayer.push() أعلى رمز حاوية "إدارة العلامات من Google" أيضًا.

اسم العنصر dataLayer حسّاس لحالة الأحرف: إذا حاولت إرسال متغيّر أو حدث بدون استخدام حالة الأحرف المناسبة، لن تنجح عملية الإرسال.

datalayer.push({'pageTitle': 'Home'});    // Bad (datalayer in lowercase)
dataLayer.push({'pageTitle': 'Home'});    // Good (dataLayer in camel case)

يجب استدعاء dataLayer.push باستخدام كائنات JavaScript صالحة. يجب وضع جميع أسماء متغيّرات طبقة البيانات بين علامتَي اقتباس.

dataLayer.push({new-variable: 'value'});      // Bad - no quote marks
dataLayer.push({'new-variable': 'value'});    // Good - proper quote marks

الحفاظ على اتساق أسماء المتغيرات في جميع الصفحات: إذا كنت تستخدم أسماء متغيرات مختلفة للمفهوم نفسه في صفحات مختلفة، لن تتمكن علاماتك من الإطلاق بشكل متسق في جميع المواقع المقصودة.

مثال سيئ:

// Homepage:
dataLayer.push({'visitorType': 'low-value'});

// Checkout Page:
dataLayer.push({'visitor_type': 'high-value'});

جيد:

// Homepage:
dataLayer.push({'visitorType': 'low-value'});

// Checkout Page:
dataLayer.push({'visitorType': 'high-value'});

إعادة تسمية طبقة البيانات

الاسم التلقائي لعنصر طبقة البيانات الذي تبدأه علامة التتبُّع من Google أو أداة "إدارة العلامات من Google" هو dataLayer. إذا كنت تفضّل استخدام اسم مختلف لطبقة البيانات، يمكنك إجراء ذلك من خلال تعديل قيمة مَعلمة طبقة البيانات في علامة التتبُّع من Google أو مقتطف حاوية "إدارة العلامات من Google" بالاسم الذي تختاره.

Tag Manager

استبدِل قيمة مَعلمة طبقة البيانات (المميّزة أدناه) في مقتطف الحاوية بالاسم الذي تختاره.

ملاحظة مهمة: لا تستبدِل قيمة المَعلمة غير المميّزة.

<!-- Google Tag Manager -->
<script>(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start':
new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0],
j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src=
'https://www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f);
})(window,document,'script','myNewName','GTM-XXXXXX');</script>
<!-- End Google Tag Manager -->

gtag.js

أضِف مَعلمة طلب بحث باسم "l" إلى عنوان URL لضبط اسم طبقة البيانات الجديدة، على سبيل المثال، l=myNewName. عدِّل جميع تكرارات dataLayer في مقتطف علامة التتبُّع من Google إلى الاسم الجديد.

<!-- Google tag -->
<script async src="https://www.googletagmanager.com/gtm.js?id=TAG_ID&l=myNewName"></script>
<script>
  window.myNewName = window.myNewName || [];
  function gtag(){myNewName.push(arguments);}
  gtag('js', new Date());
</script>

بعد إعادة التسمية، يجب تعديل جميع الإشارات إلى طبقة البيانات (أي عند الإعلان عن طبقة البيانات أعلى المقتطف، أو عند دفع الأحداث أو متغيّرات طبقة البيانات الديناميكية إلى طبقة البيانات باستخدام الأمر .push()) لتعكس اسم طبقة البيانات المخصّصة:

<script>
  window.myNewName = window.myNewName || [];
  window.myNewName.push({'variable_name': 'variable_value'});
</script>

ملاحظة مهمة: استخدِم طبقة بيانات واحدة فقط لكل صفحة

يُسمح بعنصر dataLayer واحد فقط لكل صفحة. تعتمد أداة Google Tag Manager وgtag.js على مصفوفة JavaScript عالمية واحدة باسم window.dataLayer لتلقّي جميع الأحداث والمتغيّرات ووضعها في قائمة انتظار ومعالجتها بالترتيب الذي تتم إضافتها به. وتُرفق مقتطفات الحاوية أدوات الاستماع ومنطق المعالجة الخاص بها بهذه المصفوفة الفردية تحديدًا. يمكن أن تؤدي محاولة استخدام أكثر من مثيل واحد لطبقة البيانات، أو إعادة إعداد طبقة البيانات بشكل غير صحيح (على سبيل المثال، استبدالها بـ window.dataLayer = [] بعد تحميل GTM)، إلى مشاكل كبيرة:

• قد لا يتم تنشيط العلامات: لن تؤدي الأحداث والمتغيّرات التي يتم إرسالها إلى مثيل dataLayer لا تتم مراقبته بشكل نشط من خلال Google Tag Manager أو علامة التتبُّع من Google إلى تنشيط علاماتك.
• جمع البيانات بشكل غير متّسق: قد تدفع أجزاء مختلفة من صفحتك أو نصوص برمجية مختلفة البيانات إلى مصفوفات dataLayer منفصلة ومعزولة، ما يؤدي إلى وصول معلومات غير كاملة أو غير صحيحة إلى علامات التتبُّع لأغراض تسويقية وعلامات الإحصاءات.
• فقدان البيانات: قد يتم فقدان المعلومات المخصّصة للتتبّع إذا تم إرسالها إلى مثيل dataLayer غير صحيح.
• تحديات تصحيح الأخطاء: من الصعب تشخيص مشاكل وضع العلامات لأنّ تدفق بيانات التتبُّع لا يمكن توقّعه.

أفضل الممارسات: يجب دائمًا إنشاء مثيل لطبقة البيانات باستخدام window.dataLayer = window.dataLayer || []; مرة واحدة لكل صفحة، ويكون ذلك عادةً في أعلى الصفحة في <head> قبل مقتطف GTM أو gtag.js. استخدِم دائمًا dataLayer.push() لإضافة أحداث أو متغيّرات لاحقة. يجب عدم استبدال المتغيّر window.dataLayer أو إعادة تعيينه مطلقًا.

طرق طبقة البيانات المخصّصة

إذا دفعت دالة إلى طبقة البيانات، سيتم استدعاؤها مع ضبط this على نموذج بيانات مجرّد. يمكن لنموذج البيانات المجرّد هذا الحصول على القيم وضبطها في مخزن قيم المفاتيح، كما يوفّر طريقة لإعادة ضبط طبقة البيانات.

ملاحظة مهمة: لاستخدام طرق طبقة البيانات المخصّصة، يجب استخدام .push لإرسال البيانات إلى المتغيّر dataLayer مباشرةً. في حال استخدام gtag، سيتم تفسير الدالة على أنّها أمر غير صالح وسيتم تجاهلها.

محدّدة

تتيح لك الدالة set في نموذج البيانات المجرّد ضبط القيم التي تريد استردادها من خلال get.

window.dataLayer.push(function() {
  this.set('time', new Date());
});

الحصول على

تتيح لك الدالة get في نموذج البيانات المجرّد استرداد القيم التي تم ضبطها.

window.dataLayer.push(function() {
  const existingTime = this.get('time');
  if (existingTime !== null) {
    // Change behavior based on whether or not this value exists...
  } else {
    // ...
  }
});

إعادة ضبط

تتيح لك الدالة reset في نموذج البيانات المجرّد إعادة ضبط البيانات في طبقة البيانات. ويكون ذلك مفيدًا للغاية مع صفحة ستظل مفتوحة ويستمر حجم طبقة البيانات في النمو بمرور الوقت. لإعادة ضبط طبقة البيانات، استخدِم الرمز التالي:

window.dataLayer.push(function() {
  this.reset();
});