איך יוצרים תג שרת

במבוא לתיוג בצד השרת קיבלנו סקירה כללית על תיוג בצד השרת ב-Tag Manager. למדתם מהם לקוחות ומה הם עושים: הלקוחות מקבלים נתוני אירועים מהמכשירים של המשתמשים שלכם, והם מתאימים אותם לשימוש בשאר הקונטיינר. המאמר הזה מסביר איך לעבד את הנתונים האלה בתגים בצד השרת.

בקונטיינר בשרת, התגים מקבלים נתוני אירועים נכנסים מהלקוחות, משנים אותם ושולחים אותם בחזרה לאיסוף ולניתוח. התגים יכולים לשלוח את הנתונים לכל מקום. כל עוד היעד מקבל בקשות HTTP, הוא יכול לקבל נתונים גם ממאגר תגים בצד השרת.

לקונטיינרים של שרת יש שלושה תגים מובנים, שמוכנים לשימוש ללא הגדרה מותאמת אישית:

• Google Analytics 4
• Google Analytics: Universal Analytics
• בקשת HTTP

אם אתם רוצים לשלוח נתונים למקום שאינו Google Analytics, או אם אתם זקוקים לתכונות נוספות מתג בקשת ה-HTTP, תצטרכו להשתמש בתג אחר. תוכלו למצוא תגים נוספים בגלריית תבניות הקהילה או לכתוב תגים משלכם. במדריך הזה תלמדו את העקרונות הבסיסיים של כתיבת תגים משלכם לקונטיינר בשרת.

מטרות

• מידע על ממשקי ה-API שבהם אפשר להשתמש כדי לקרוא נתוני אירועים, לשלוח בקשות HTTP ולהגדיר קובצי cookie בדפדפן.
• תוכלו ללמוד שיטות מומלצות לעיצוב אפשרויות ההגדרה של התג.
• להבין את ההבדל בין נתונים שהוגדרו על ידי משתמשים לבין נתונים שנאספים באופן אוטומטי, ולהסביר למה ההבחנה הזו חשובה.
• מידע על התפקיד של תג במאגר תגים בצד השרת. חשוב לדעת מה תג צריך ולא לעשות.
• מתי כדאי לשלוח תבנית תג לגלריית תבניות הקהילה.

דרישות מוקדמות

• מאגר תגים שנפרס בשרת
• היכרות עם Tag Manager, מאגרי תגים של שרתים והמושגים הבסיסיים שלהם, כמו לקוחות, תגים, טריגרים ומשתנים
• הכרת היסודות של כתיבת תבניות לתגים ולמשתנים

התג Baz Analytics

במדריך הזה תלמדו ליצור תג ששולח נתוני מדידה לשירות שנקרא Baz Analytics.

Baz Analytics הוא שירות פשוט והיפותטי לניתוח נתונים, שמטמיע נתונים באמצעות בקשות HTTP GET אל https://example.com/baz_analytics. הוא כולל את הפרמטרים הבאים:

פרמטר	דוגמה	תיאור
id	BA-1234	המזהה של חשבון Baz Analytics.
en	click	שם האירוע.
l	https://www.google.com/search?q=sgtm	כתובת האתר של הדף שבו התרחש האירוע.
u	2384294892	המזהה של המשתמש שמבצע את הפעולה. מקשר מספר פעולות למשתמש יחיד.

הגדרת תגים

הדבר הראשון שצריך לעשות הוא ליצור את תבנית התג. נכנסים לקטע Templates במאגר התגים ולוחצים על New (חדש) בקטע Tag templates (תבניות תגים). מוסיפים שם ותיאור לתג.

בשלב הבא עוברים לקטע Fields בכלי לעריכת התבניות כדי להוסיף את אפשרויות ההגדרה השונות של התג. השאלה הברורה הבאה היא: אילו אפשרויות אתם צריכים? יש שלוש שיטות לבנות את התג:

1. Total Configuration (התצורה הכוללת): הוספת שדה הגדרה לכל פרמטר. דרישה מהמשתמש להגדיר הכול במפורש.
2. No Configuration (אין הגדרה): אין לכם אפשרויות להגדרת התג. כל הנתונים נלקחים ישירות מהאירוע.
3. חלק מהתצורה: כוללים שדות לפרמטרים מסוימים ולא לאחרים.

הוספת שדות לכל פרמטר היא גמישה מאוד ומספקת למשתמש שליטה כוללת על הגדרת התג. אבל בפועל זה בדרך כלל גורם להרבה עבודה כפולה. באופן ספציפי, פרמטרים כמו הפרמטר Baz Analytics l, שמכיל את כתובת ה-URL של הדף, הם דו-משמעיים ואוניברסליים. האפשרות להזין את אותו נתון ולא משתנה בכל פעם שמגדירים את התג היא הפעולה הטובה ביותר במחשב.

אולי התשובה היא באמצעות תג שמקבל רק נתונים מאירוע. זה התג הכי פשוט שאפשר להגדיר למשתמש, כי הוא לא יכול לעשות שום דבר. מצד שני, הוא גם האפשרות המגבילה והשבירה ביותר. המשתמשים לא יכולים לשנות את התנהגות התג, גם אם הם צריכים לעשות זאת. לדוגמה, יכול להיות שהם קוראים לאירוע באתר וב-Google Analytics purchase, אבל מערכת Baz Analytics מכנה אותו בשם buy. לחלופין, יכול להיות שההנחות שהתג מניע על המבנה של נתוני האירועים הנכנסים לא תואמות למציאות. בכל מקרה, המשתמש תקוע.

כמו במקרים רבים, התשובה נמצאת בין שתי נקודות הקיצון. יש נתונים הגיוניים שתמיד כדאי לקחת מהאירוע. נתונים אחרים צריכים להיות מוגדרים על ידי המשתמש. איך אתם מחליטים איזה מהם לבחור? כדי לענות על השאלה הזו, עלינו לבחון מקרוב את הנתונים שנכנסים לקונטיינר.

מה מקור הנתונים

את הנתונים שנכנסים למאגר תגים בצד השרת מהתג של Google Analytics 4 אפשר לחלק באופן גס לשתי קטגוריות: נתונים בהגדרת המשתמש ונתונים שנאספים באופן אוטומטי.

הנתונים בהגדרת המשתמש הם כל מה שהמשתמש מוסיף לפקודה event של gtag.js. לדוגמה, פקודה כמו זו:

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

יוביל לפרמטרים הבאים במאגר התגים בצד השרת:

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

זה מספיק פשוט, אבל קשה מאוד לעבוד איתו מנקודת המבט של התג. מכיוון שהנתונים האלה מוזנים על ידי המשתמש, הם יכולים להיות כל דבר. אולי, כפי שמתואר למעלה, המשתמש שולח רק אירועים ופרמטרים מומלצים, אבל לא חייבים לעשות זאת. מלבד המיקום החשוב (אבל לא הערך!) של הפרמטר event_name, אין אחריות לגבי הצורה או המבנה של נתוני המשתמש.

למרבה המזל, הנתונים שהמשתמשים הזינו הם לא הדבר היחיד שהמאגר יקבל. הוא גם יקבל אוסף של נתונים שנאספים באופן אוטומטי על ידי תג Google Analytics 4 בדפדפן. בין המקורות שאינם מדווחים:

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

בנוסף, אם בקשת השרת מגיעה מדפדפן אינטרנט, יכול להיות שיהיו גם נתונים של קובצי cookie בדפדפן שזמינים דרך ה-API getCookieValue.

יחד הם יוצרים את הנתונים שנאספים באופן אוטומטי, שהזכרנו קודם. באופן כללי, הנתונים מורכבים מנתונים אוניברסליים שאינם חד-משמעיים מבחינה סמנטית. כשבקשה מגיעה מתג GA4 בדפדפן, הנתונים האלה תמיד יהיו זמינים ותמיד יהיו באותו פורמט. פרטים נוספים על הפרמטרים האלה זמינים בחומר העזר בנושא אירועים.

הסיווג הזה הוא כלי שימושי שאנחנו משתמשים בו כדי להחליט אילו נתונים המשתמש צריך להגדיר ואילו נתונים צריך לציין בתג. אפשר לקרוא את הנתונים שנאספים באופן אוטומטי ישירות מהאירוע. את כל האפשרויות האחרות צריך להגדיר המשתמש.

לכן, כדאי לבחון שוב את הפרמטרים של התג Baz Analytics.

• מזהה מדידה, id: מכיוון שהוא לא נאסף באופן אוטומטי, הוא זו דוגמה ברורה לערך שהמשתמש צריך להזין כשמגדירים את התג.
• שם האירוע, en: כפי שצוין למעלה, תמיד אפשר לקחת את שם האירוע ישירות מהפרמטר event_name. עם זאת, מכיוון שהערך שלו מוגדר על ידי המשתמש, כדאי להציע את האפשרות לשנות את השם במקרה הצורך.
• כתובת הדף, l: הערך הזה יכול להגיע מהפרמטר page_location, שנאסף באופן אוטומטי על ידי תג הדפדפן של Google Analytics GA4 בכל אירוע. לכן, אין לדרוש מהמשתמש להזין ערך באופן ידני.
• User ID, u: בתג השרת של Baz Analytics, הפרמטר u לא צוין על ידי המשתמש ולא נאסף באופן אוטומטי על ידי התג שבדף. במקום זאת, הוא מאוחסן בקובץ cookie של דפדפן כדי שניתן יהיה לזהות משתמשים בביקורים מרובים באתר. כפי שניתן לראות בקטע הטמעה בהמשך, זהו תג השרת של Baz Analytics שמשתמש ב-API setCookie כדי להגדיר את קובץ ה-cookie. כלומר, התג של Baz Analytics הוא היחיד שיודע איפה ואיך קובץ ה-cookie מאוחסן. בדומה ל-l, הפרמטר u אמור להיאסף באופן אוטומטי.

אחרי שמסיימים לקבוע את הגדרות התג, הוא אמור להיראות כך:

הטמעת תגים

עכשיו, לאחר שתצורת התג הושקה בריבוע, אתם מוכנים להמשיך ליישם את ההתנהגות שלו ב-JavaScript בארגז חול (sandbox).

התג צריך לבצע ארבע פעולות:

1. צריך לקבל את שם האירוע מההגדרה של התג.
2. צריך לקבל את כתובת ה-URL של הדף מהנכס page_location של האירוע.
3. חישוב של מזהה משתמש. התג יחפש את מזהה המשתמש בקובץ cookie בשם _bauid. אם קובץ ה-cookie לא נמצא, התג יחשב ערך חדש ויאחסן אותו לבקשות עתידיות.
4. יוצרים כתובת URL ושולחים בקשה לשרת האיסוף של Baz Analytics.

כדאי גם להקדיש כמה רגעים כדי להבין איך התג נכנס לתוך הקונטיינר באופן כללי. לרכיבי קונטיינרים שונים יש תפקידים שונים, ולכן יש גם דברים שהתג לא עושה או לא צריך לעשות.

• לא אמורים לבדוק את האירוע כדי להחליט אם הוא צריך להתקיים. לשם כך מיועד טריגר.
• אין להפעיל את המאגר עם ה-API של runContainer. זו העבודה של הלקוח.
• מלבד קובצי cookie, חשוב לא לנסות לבצע אינטראקציה ישירות עם הבקשה או התגובה. זה גם העבודה של הלקוח.

אם תכתבו תבנית תג שמבצעת אחת מהפעולות האלה, משתמשי התג עלולים להתנהג בצורה מבלבלת. לדוגמה, תג ששולח תגובה לבקשה הנכנסת ימנע מהלקוח לעשות זאת. זה עלול לבטל את הציפיות של המשתמשים בנוגע לאופן שבו הקונטיינר אמור להתנהג.

בהמשך לכל אלה, מופיע הטמעה של התג עם הערות ב-JS ב-Sandbox.

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

כך התג מוטמע. כדי להשתמש בתג, צריך להגדיר את ההרשאות שלו ל-API בצורה נכונה. נכנסים לכרטיסייה Permissions בכלי לעריכת התבניות ומציינים את ההרשאות הבאות:

• קורא ערכי קובצי cookie: _bauid
• קורא את נתוני האירועים: event_name ו-page_location
• שולחת בקשות HTTP: https://www.example.com/*
• מגדיר קובץ cookie: _bauid

מומלץ גם לכתוב בדיקות של התג. למידע נוסף על בדיקת תבניות, קראו את הקטע בדיקות במדריך למפתחים.

לבסוף, אל תשכחו לנסות להריץ את התג באמצעות הלחצן Run Code לפחות פעם אחת. כך תוכלו למנוע ביצוע של הרבה טעויות פשוטות בשרת.

שליחת התג לגלריית תבניות הקהילה

כבר עברתם את כל העבודה כדי ליצור, לבדוק ולפרוס תג חדש, ולכן אין סיבה לשמור אותו לעצמכם. אם לדעתכם התג החדש יכול להיות מועיל לאנשים אחרים, כדאי לשלוח אותו לגלריית תבניות הקהילה.

סיכום

במדריך הזה למדתם את העקרונות הבסיסיים של כתיבת תג לקונטיינר בשרת. למדת:

• באילו ממשקי API אפשר להשתמש כדי לקרוא נתוני אירועים, לשלוח בקשות HTTP ולהגדיר קובצי Cookie בדפדפן.
• שיטות מומלצות לעיצוב אפשרויות ההגדרה של תג.
• ההבדל בין נתונים שצוינו על ידי משתמשים לבין נתונים שנאספים באופן אוטומטי ולמה ההבחנה הזו חשובה.
• תפקידו של תג במאגר: מה צריך לעשות ומה לא לעשות.
• מתי ואיך לשלוח תבניות תגים לגלריית תבניות הקהילה.