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

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

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

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

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

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

الأهداف

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

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

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

علامة 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 4" بشكل تقريبي إلى فئتَين: البيانات التي يحدّدها المستخدِم والبيانات المجمَّعة تلقائيًا.

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

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

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

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

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

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

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

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

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

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

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

• رقم تعريف القياس، id: بما أنّه لا يتم جمعه تلقائيًا، فهو مثال واضح على القيمة التي يجب أن يدخلها المستخدم عند ضبط العلامة.
• اسم الحدث، en: كما ذكرنا أعلاه، يمكن دائمًا الحصول على اسم الحدث مباشرةً من المَعلمة event_name. ومع ذلك، بما أنّ قيمته محددة من قِبل المستخدم، من الأفضل توفير إمكانية إلغاء الاسم إذا لزم الأمر.
• عنوان URL للصفحة، l: يمكن الحصول على هذه القيمة من المَعلمة page_location التي تجمعها تلقائيًا علامة متصفّح "إحصاءات Google‏ 4" عند كلّ حدث. لذلك، يجب عدم مطالبة المستخدم بإدخال قيمة يدويًا.
• رقم تعريف المستخدِم، 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 4 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 وضبط ملفات تعريف الارتباط على المتصفّح
• أفضل الممارسات لتصميم خيارات الضبط لعلامة معيّنة
• الفرق بين البيانات التي يحدّدها المستخدم والبيانات التي يتم جمعها تلقائيًا وسبب أهمية هذا التمييز
• دور العلامة في الحاوية، والإجراءات التي يجب أن تتّخذها والإجراءات التي يجب ألّا تتّخذها
• حالات إرسال نماذج العلامات وكيفية إرسالها إلى معرض نماذج المنتدى