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

طبقة البيانات هي عنصر تستخدمه أداة 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 للإشارة إلى المعلومات التي تتم إضافتها إلى طبقة البيانات بطريقة منظَّمة ويمكن توقُّعها، بدلاً من تحليل المتغيّرات ومعلومات المعاملات وفئات الصفحات والإشارات الأخرى المنتشرة في صفحتك. سيساعد تنفيذ طبقة البيانات التي تمت تعبئتها بالمتغيّرات والقيم المرتبطة بها في ضمان توفّر البيانات ذات الصلة عندما تحتاج إليها علاماتك.

تثبيت

بالنسبة إلى عمليات تثبيت صفحات الويب في أداة "إدارة العلامات من Google"، يجب إنشاء طبقة بيانات. يوضّح مثال الرمز التالي مكان إنشاء طبقة البيانات، أي قبل تحميل أداة "إدارة العلامات من 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 (gtag.js) -->
<script async src="https://www.googletagmanager.com/gtag/js?id=TAG_ID"></script>
<script>
  window.dataLayer = window.dataLayer || [];
  function gtag(){dataLayer.push(arguments);}
  gtag('js', new Date());

  gtag('config', 'TAG_ID');
</script>

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

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

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

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

ملاحظة مهمة: لا تستخدِم علامات HTML المخصّصة لضبط إعدادات الموافقة في "إدارة العلامات من Google". بما أنّه يجب تطبيق إعدادات الموافقة قبل إطلاق العلامات ذات الصلة في حاوية "إدارة العلامات من Google"، عليك استخدام واجهات برمجة التطبيقات لوضع الموافقة في "إدارة العلامات من Google" لإعداد السلوك التلقائي والتعديل. استخدِم واجهات برمجة تطبيقات وضع الموافقة في أداة 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" أو "Tag Manager" باستخدام الاسم الذي تختاره.

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

  gtag('config', 'TAG_ID');
</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();
});