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

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

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

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

• Google Analytics
• בקשת HTTP

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

מטרות

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

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

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

התג של Baz Analytics

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

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

הגדרת התג

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

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

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

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

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

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

מאיפה מגיעים הנתונים?

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

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

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

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

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

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

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

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

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

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

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

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

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

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

הטמעת תגים

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

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

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

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

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

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

לאחר שקראתם את כל ההסברים האלה, הנה הטמעה עם הערות של התג ב-JS בסביבת ארגז חול.

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

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

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

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

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

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

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

סיכום

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

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