كيفية إنشاء علامة خادم

في مقالة مقدّمة عن وضع العلامات من جهة الخادم، حصلت على نظرة عامة حول وضع العلامات من جهة الخادم في Tag Manager. تعرّفت على العملاء وما يفعلونه: يتلقّى العملاء بيانات الأحداث من أجهزة المستخدمين ويعدّلونها لاستخدامها من خلال بقية الحاوية. توضّح هذه المقالة كيفية معالجة هذه البيانات في العلامات من جهة الخادم.

في حاوية الخادم، تتلقّى العلامات بيانات الأحداث الواردة من عملائك، وتحوّلها، ثمّ تعيد إرسالها لجمعها وتحليلها. يمكن أن ترسل العلامات البيانات إلى أي مكان تريده. طالما أنّ الوجهة تقبل طلبات HTTP، يمكنها أيضًا قبول البيانات من حاوية خادم.

تحتوي حاويات الخادم على ثلاث علامات مدمَجة جاهزة للاستخدام بدون أي إعدادات مخصّصة:

• إحصاءات Google
• طلب HTTP

إذا كنت تريد إرسال البيانات إلى مكان آخر غير "إحصاءات Google"، أو إذا كنت بحاجة إلى ميزات أكثر من تلك التي توفّرها علامة "طلب HTTP"، عليك استخدام علامة مختلفة. يمكنك العثور على علامات إضافية في معرض نماذج المنتدى أو يمكنك كتابة علاماتك الخاصة. سيعلّمك هذا البرنامج التعليمي أساسيات كتابة علاماتك الخاصة لحاوية خادم.

الأهداف

• تعرَّف على واجهات برمجة التطبيقات التي يجب استخدامها لقراءة بيانات الأحداث وإرسال طلبات HTTP وضبط ملفات تعريف الارتباط في المتصفّح.
• تعرَّف على أفضل الممارسات لتصميم خيارات إعدادات علامة التتبّع.
• تعرَّف على الفرق بين البيانات التي يحدّدها المستخدم والبيانات التي يتم جمعها تلقائيًا، وأهمية هذا التمييز.
• تعرَّف على دور العلامة في حاوية الخادم. فهم ما يجب وما لا يجب أن تفعله العلامة
• تعرَّف على الحالات التي يجب فيها التفكير في إرسال نموذج علامات التتبُّع إلى معرض نماذج المنتدى.

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

• حاوية خادم تم نشرها
• الإلمام بأداة Tag Manager وحاويات الخادم ومفاهيمها الأساسية، مثل العملاء والعلامات والمشغّلات والمتغيرات
• معرفة أساسيات كتابة نماذج للعلامات والمتغيّرات

علامة Baz Analytics

في هذا البرنامج التعليمي، ستنشئ علامة ترسل بيانات القياس إلى خدمة تُعرف باسم Baz Analytics.

‫Baz Analytics هي خدمة إحصاءات بسيطة وافتراضية تستوعب البيانات من خلال طلبات HTTP GET إلى https://example.com/baz_analytics. ويتضمّن المَعلمات التالية:

إعداد العلامة

أول ما عليك فعله هو إنشاء نموذج علامات التتبُّع. انتقِل إلى قسم النماذج في حاويتك وانقر على جديد في قسم نماذج العلامات. أضِف اسمًا ووصفًا إلى علامتك.

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

1. الإعدادات الإجمالية: أضِف حقل إعدادات لكل مَعلمة. يجب أن يضبط المستخدم كل شيء بشكل صريح.
2. عدم الضبط: لا تتوفّر أي خيارات لضبط العلامة. يتم استخلاص جميع البيانات مباشرةً من الحدث.
3. بعض الإعدادات: تتضمّن حقولاً لبعض المَعلمات وليس لغيرها.

توفير حقول لكل مَعلمة يمنح المستخدم مرونة كبيرة وتحكّمًا كاملاً في إعدادات العلامة. ومع ذلك، يؤدي ذلك عادةً إلى تكرار الكثير من العمل. على وجه الخصوص، تكون بعض العناصر، مثل المَعلمة l في Baz Analytics التي تحتوي على عنوان URL الخاص بالصفحة، واضحة وعامة. إنّ إدخال جزء البيانات نفسه وغير المتغيّر في كل مرة يتم فيها ضبط العلامة هو أمر من الأفضل تركه للكمبيوتر.

ربما يكون الحلّ هو استخدام علامة لا تأخذ البيانات إلا من حدث معيّن. هذه هي أبسط علامة يمكن للمستخدم ضبطها، إذ لا يتطلّب الأمر منه اتّخاذ أي إجراء. من ناحية أخرى، هذا الخيار هو أيضًا الأكثر تقييدًا والأكثر عرضةً للمشاكل. لا يمكن للمستخدمين تغيير سلوك العلامة حتى إذا احتاجوا إلى ذلك. على سبيل المثال، قد يطلقون على حدث اسم purchase على موقعهم الإلكتروني وفي "إحصاءات Google"، ولكنّ Baz Analytics تطلق عليه اسم buy. أو ربما لا تتطابق الافتراضات التي تضعها العلامة بشأن بنية بيانات الأحداث الواردة مع الواقع. وفي أيٍّ من الحالتَين، يتعذّر على المستخدم إكمال العملية.

كما هو الحال مع العديد من الأمور، يكمن الحل في مكان ما بين النقيضين. من المنطقي دائمًا استخراج بعض البيانات من الحدث. يجب أن يضبط المستخدم البيانات الأخرى. كيف يمكن التمييز بينهما؟ للإجابة عن هذا السؤال، علينا إلقاء نظرة فاحصة على البيانات الواردة إلى الحاوية.

من أين تأتي البيانات؟

يمكن تقسيم البيانات الواردة إلى حاوية الخادم من علامة "إحصاءات Google" إلى فئتَين تقريبًا: البيانات التي يحدّدها المستخدم والبيانات التي يتم جمعها تلقائيًا.

البيانات المحدّدة من المستخدِم هي كل ما يُدخله المستخدِم في أمر event gtag.js. على سبيل المثال، طلب مثل هذا:

gtag('event', 'search', {
  search_term: 'beets',
});

سيؤدي ذلك إلى ظهور المَعلمات التالية في حاوية الخادم:

{
  event_name: 'search',
  search_term: 'beets',
}

يبدو ذلك بسيطًا، ولكن من منظور العلامة، يصعب جدًا التعامل معها. بما أنّ المستخدم هو من يُدخل هذه البيانات، يمكن أن تكون أي شيء. وكما هو موضّح أعلاه، قد يرسل المستخدم الأحداث والمَعلمات المقترَحة فقط، ولكن ليس هناك أي شرط يلزمه بذلك. وباستثناء الموقع الجغرافي (وليس القيمة!) للمَعلمة event_name، ليس هناك أي ضمانات بشأن شكل بيانات المستخدم أو بنيتها.

لحسن الحظ، البيانات التي يدخلها المستخدم ليست الشيء الوحيد الذي سيتلقّاه الحاوي. ستتلقّى أيضًا مجموعة من البيانات التي يتم جمعها تلقائيًا من خلال علامة "إحصاءات Google" في المتصفّح. ويشمل ذلك ما يلي:

• ip_override
• language
• page_location
• page_referrer
• page_title
• screen_resolution
• user_agent

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

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

يمنحنا هذا التصنيف أداة مفيدة يمكن استخدامها عند تحديد البيانات التي يجب أن يضبطها المستخدِم والبيانات التي يجب تحديدها في العلامة. يمكن قراءة البيانات التي يتم جمعها تلقائيًا بأمان مباشرةً من الحدث. ويجب أن يضبط المستخدم كل ما عدا ذلك.

مع أخذ ذلك في الاعتبار، ألقِ نظرة أخرى على مَعلمات علامة Baz Analytics.

• رقم تعريف القياس، id: بما أنّه لا يتم جمعه تلقائيًا، فهو مثال واضح على قيمة يجب أن يدخلها المستخدم عند ضبط العلامة.
• اسم الحدث، en: كما ذكرنا أعلاه، يمكن دائمًا استخراج اسم الحدث مباشرةً من المَعلمة event_name. ومع ذلك، بما أنّ قيمته يحدّدها المستخدم، من المستحسن توفير إمكانية إلغاء الاسم إذا لزم الأمر.
• عنوان URL للصفحة، l: يمكن الحصول على هذه القيمة من المَعلمة page_location، التي يتم جمعها تلقائيًا من خلال علامة متصفّح "إحصاءات Google" في كل حدث. لذلك، يجب ألا تطلب من المستخدم إدخال قيمة يدويًا.
• معرّف المستخدم، u: في علامة خادم Baz Analytics، لا يتم تحديد قيمة المَعلمة u من قِبل المستخدم، ولا يتم جمعها تلقائيًا من خلال العلامة على الصفحة. بدلاً من ذلك، يتم تخزينها في ملف تعريف ارتباط في المتصفّح كي يمكن التعرّف على المستخدمين عند زيارة الموقع الإلكتروني عدة مرات. كما سترى في عملية التنفيذ أدناه، إنّ علامة خادم Baz Analytics هي التي تستخدم واجهة برمجة التطبيقات setCookie لضبط ملف تعريف الارتباط. وهذا يعني أنّ علامة Baz Analytics هي العنصر الوحيد الذي يعرف مكان وكيفية تخزين ملف تعريف الارتباط. على غرار l، يجب جمع المَعلمة u تلقائيًا.

بعد الانتهاء من إعدادات العلامة، من المفترض أن تظهر على النحو التالي:

وضع العلامات

بعد الانتهاء من إعدادات العلامة، يمكنك الانتقال إلى تنفيذ سلوكها في JavaScript في وضع الحماية.

يجب أن تنفّذ العلامة أربعة إجراءات:

1. احصل على اسم الحدث من إعدادات العلامة.
2. احصل على عنوان URL للصفحة من السمة page_location الخاصة بالحدث.
3. احتساب معرّف المستخدم ستبحث العلامة عن رقم تعريف المستخدم في ملف تعريف ارتباط باسم _bauid. في حال عدم توفّر ملف تعريف الارتباط هذا، ستحسب العلامة قيمة جديدة وتخزّنها للطلبات اللاحقة.
4. إنشاء عنوان URL وإرسال طلب إلى خادم جمع البيانات في Baz Analytics

من المفيد أيضًا التفكير في كيفية ملاءمة العلامة للحاوية ككل. تؤدي مكوّنات الحاويات المختلفة أدوارًا مختلفة، لذا هناك أيضًا أشياء لا تفعلها العلامة أو لا يجب أن تفعلها. علامتك:

• يجب ألا يتم فحص الحدث لمعرفة ما إذا كان يجب تنفيذه. هذا هو الغرض من المشغّل.
• يجب عدم تشغيل الحاوية باستخدام واجهة برمجة التطبيقات runContainer. هذا هو عمل العميل.
• باستثناء ملفات تعريف الارتباط، يجب ألا تحاول التفاعل مباشرةً مع الطلب أو الرد. وهذه أيضًا مهمة العميل.

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

مع أخذ كل ما سبق في الاعتبار، إليك أدناه عملية تنفيذ مشروحة للعلامة في JavaScript المحصور في بيئة آمنة.

const encodeUriComponent = require('encodeUriComponent');
const generateRandom = require('generateRandom');
const getCookieValues = require('getCookieValues');
const getEventData = require('getEventData');
const logToConsole = require('logToConsole');
const makeString = require('makeString');
const sendHttpGet = require('sendHttpGet');
const setCookie = require('setCookie');

const USER_ID_COOKIE = '_bauid';
const MAX_USER_ID = 1000000000;

// The event name is taken from either the tag's configuration or from the
// event. Configuration data comes into the sandboxed code as a predefined
// variable called 'data'.
const eventName = data.eventName || getEventData('event_name');

// page_location is automatically collected by the Google Analytics tag.
// Therefore, it's safe to take it directly from event data rather than require
// the user to specify it. Use the getEventData API to retrieve a single data
// point from the event. There's also a getAllEventData API that returns the
// entire event.
const pageLocation = getEventData('page_location');
const userId = getUserId();

const url = 'https://www.example.com/baz_analytics?' +
    'id=' + encodeUriComponent(data.measurementId) +
    'en=' + encodeUriComponent(eventName) +
    (pageLocation ? 'l=' + encodeUriComponent(pageLocation) : '') +
    'u=' + userId;

// The sendHttpGet API takes a URL and returns a promise that resolves with the
// result once the request completes. You must call data.gtmOnSuccess() or
// data.gtmOnFailure() so that the container knows when the tag has finished
// executing.
sendHttpGet(url).then((result) => {
  if (result.statusCode >= 200 && result.statusCode < 300) {
    data.gtmOnSuccess();
  } else {
    data.gtmOnFailure();
  }
});

// The user ID is taken from a cookie, if present. If it's not present, a new ID
// is randomly generated and stored for later use.
//
// Generally speaking, tags should not interact directly with the request or
// response. This prevents different tags from conflicting with each other.
// Cookies, however, are an exception. Tags are the only container entities that
// know which cookies they need to read or write. Therefore, it's okay for tags
// to interact with them directly.
function getUserId() {
  const userId = getCookieValues(USER_ID_COOKIE)[0] || generateRandom(0, MAX_USER_ID);
  // The setCookie API adds a value to the 'cookie' header on the response.
  setCookie(USER_ID_COOKIE, makeString(userId), {
    'max-age': 3600 * 24 * 365 * 2,
    domain: 'auto',
    path: '/',
    httpOnly: true,
    secure: true,
  });

  return userId;
}

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

• قراءة قيم ملفات تعريف الارتباط: _bauid
• قراءة بيانات الأحداث: event_name وpage_location
• إرسال طلبات HTTP: https://www.example.com/*
• ضبط ملف تعريف ارتباط: _bauid

يجب أيضًا كتابة اختبارات لعلامتك. للمزيد من المعلومات حول اختبار النماذج، يمكنك الاطّلاع على قسم الاختبارات في دليل مطوّري النماذج.

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

إرسال علامتك إلى "معرض نماذج المنتدى"

بما أنّك بذلت جهدًا كبيرًا في إنشاء علامة جديدة واختبارها ونشرها، ليس هناك سبب يمنعك من مشاركتها مع الآخرين. إذا كنت تعتقد أنّ علامتك الجديدة ستكون مفيدة للمستخدمين الآخرين، يمكنك إرسالها إلى "معرض نماذج المنتدى".

الخاتمة

في هذا البرنامج التعليمي، تعرّفت على أساسيات كتابة علامة لحاوية خادم. لقد تعلّمت:

• واجهات برمجة التطبيقات التي يجب استخدامها لقراءة بيانات الأحداث وإرسال طلبات HTTP وضبط ملفات تعريف الارتباط على المتصفّح
• أفضل الممارسات لتصميم خيارات الإعدادات الخاصة بعلامة
• الفرق بين البيانات التي يحدّدها المستخدم والبيانات التي يتم جمعها تلقائيًا وأهمية هذا التمييز
• دور العلامة في الحاوية، أي ما يجب وما لا يجب أن تفعله
• وقت وكيفية إرسال نماذج العلامات إلى معرض نماذج المنتدى