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

طبقة البيانات هي عنصر تستخدمه "إدارة العلامات من Google" و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>

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

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

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

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

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

نقطة أساسية: يمكنك استخدام أداة 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'}) لإضافة قيم إضافية إليها، وإذا كان يجب أن تكون هذه القيم متاحة لأداة "إدارة العلامات" عند تحميل الصفحة، يجب أن يكون استدعاء dataLayer.push() هذا أعلى رمز حاوية "إدارة العلامات" أيضًا.

اسم عنصر 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 أو Tag Manager هو dataLayer. إذا كنت تفضّل استخدام اسم مختلف لطبقة البيانات، يمكنك إجراء ذلك من خلال تعديل قيمة مَعلمة طبقة البيانات في "علامة تتبُّع من 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>

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 -->

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

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

ملاحظة: لا يمكن استخدام سوى عنصر 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();
})