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

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

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

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

• إحصاءات Google‏ 4
• "إحصاءات Google": Universal Analytics
• طلب HTTP

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

الأهداف

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

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

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

علامة Baz Analytics

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

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

المَعلمة	مثال	الوصف
id	BA-1234	معرف حسابك على Baz "إحصاءات".
en	نقرة	اسم الحدث.
l	https://www.google.com/search?q=sgtm	عنوان URL للصفحة التي وقع فيها الحدث.
u	2384294892	رقم تعريف المستخدم الذي ينفِّذ الإجراء. يستخدم لربط إجراءات متعددة مرة أخرى بمستخدم واحد.

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

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

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

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 API. هذه هي وظيفة العميل.
• باستثناء ملفات تعريف الارتباط المهمة، يجب ألا تحاول التفاعل مباشرةً مع الطلب أو الرد. هذه أيضًا مهمة العميل.

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

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