הפניית API של Google Tag

‫API של Google Tag‏ (gtag.js) מורכב מפונקציה אחת, gtag(), עם התחביר הבא:

gtag(<command>, <command parameters>);

‫<command> היא אחת מהפקודות הבאות:
- config
- get
- set
- event
- consent
‫<command parameters> הם הפרמטרים שאפשר להעביר אל gtag(). פרמטרים של פקודות משתנים בהתאם לפקודה. אפשר לעיין בחומרי העזר של הפקודות.

אפשר להפעיל פקודות של gtag() בכל מקום בדף, כל עוד הפקודות מופיעות מתחת לקטע הקוד של Google Tag. במדריך ההתקנה מוסבר איך מוסיפים את קטע הקוד לדף.

היקף הפרמטר

אפשר להגדיר את ערכי הפרמטרים כך שיהיו רלוונטיים לאירועים ספציפיים, לכל האירועים שנשלחים אל <TARGET_ID> מסוים או לכל האירועים. כדי לעשות את זה, משתמשים בפקודות event, config ו-set.

ערכי פרמטרים שמוגדרים בהיקף אחד לא משנים את הערכים שמוגדרים לאותו פרמטר בהיקף אחר. בדוגמה הבאה, הפקודה config לא משנה את הערך הגלובלי של campaign_id שהוקצה קודם באמצעות הפקודה set. אחרי הרצת שתי הפקודות, הערך הגלובלי של campaign_id עדיין '1234'.

// Set global campaign ID
gtag('set', { 'campaign_id': '1234' });

// Set campaign ID for <TARGET_ID>
gtag('config','<TARGET_ID>', { 'campaign_id': 'ABCD' });

קדימות של פרמטרים

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

// Set campaign information at the global scope
gtag('set', { 'campaign_name': 'Black Friday Sale' });

// Set currency for <TARGET_ID1> to 'USD'
gtag('config','<TARGET_ID1>', { 'currency': 'USD' });

// Process a conversion event with currency: 'GBP'
gtag('event','conversion', { 'currency': 'GBP', 'send_to': '<TARGET_ID1>' });

// Process a conversion event with currency: 'EUR'
gtag('event','conversion');

// Process a conversion event with currency: 'USD'
gtag('event','conversion', { 'send_to': '<TARGET_ID1>' });

`config`

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

gtag('config', '<TARGET_ID>', {<additional_config_info>});

נקודות חשובות לגבי <TARGET_ID>:

‫<TARGET_ID> בפקודה gtag('config', <TARGET_ID>, ...) הוא מזהה תג שמציין לאן gtag.js צריך לשלוח נתוני אירועים. יכול להיות שזה יעד כמו נכס ב-Google Analytics, חשבון Google Ads, הגדרת Floodlight או Google Tag עם כמה יעדים.
מזהה תג, כמו GT-XXXXXX, G-XXXXXX או AW-YYYYYY, הוא מזהה של Google Tag. מוסיפים את המזהה הזה לקוד של האתר כדי לטעון את Google Tag.
אפשר להגדיר Google Tag אחד (שמזוהה לפי מזהה התג) כך שישלח נתונים לכמה יעדים. למרות שמזהי תגים מסוימים עשויים להיראות זהים למזהי יעד, כמו G-XXXXXX עבור נכס ב-Google Analytics או AW-YYYYYY עבור חשבון Google Ads, המזהה <TARGET_ID> בפקודה config מתייחס למופע הספציפי של Google Tag שנטען בדף.
הפקודה gtag('config', ...) מגדירה את אופן הפעולה של Google Tag שמשויך ל-<TARGET_ID> הספציפי. בדרך כלל, מזהה התג שכלול בסקריפט src טוען את Google Tag, אבל אפשר להשתמש בכל מזהה תג תקין שמשויך לחשבון בפקודה gtag('config').
ל-Google Tag אחד יכולים להיות כמה מזהי תג שמשויכים אליו, בדרך כלל בגלל מיזוג תגים. אפשר להשתמש בכל אחד מהמזהים המשויכים האלה בפרמטר src של הסקריפט כדי לטעון את Google Tag.
אם אתם שולחים נתונים לכמה יעדים או משתמשים בכמה תגים, אתם צריכים לכלול רק קטע קוד אחד של Google Tag עם מזהה תג אחד בסקריפט src. לאחר מכן כוללים פקודה gtag('config') לכל מזהה תג או יעד נוסף.

‫<additional_config_info> הוא צמד אחד או יותר של ערכי פרמטר.

בדוגמה הזו מוגדר תג לשליחת נתונים לחשבון Google Ads:

gtag('config', 'TAG_ID');

כאשר TAG_ID הוא מזהה התג של Google Tag.

כדי להדגים איך שולחים פרטי הגדרה נוספים, הנה דוגמה להגדרת תג לשליחת נתונים לחשבון Analytics עם פרמטר send_page_view שמעביר ערך של false, ופרמטר groups שמעביר ערך של 'agency'.

gtag('config', 'TAG_ID', {
  'send_page_view': false,
  'groups': 'agency'
});

`get`

מאפשרת לכם לקבל ערכים שונים מ-gtag.js, כולל ערכים שמוגדרים בפקודה set.

gtag('get', '<target>', '<field_name>', callback)

ארגומנט	סוג	דוגמה	תיאור
<target>	`string`	G-XXXXXXXXXX	היעד שממנו המערכת תאחזר ערכים.
<field_name>	FieldName	client_id	שם השדה שהמערכת תאחזר.
callback	`Function`	`(field) => console.log(field)`	פונקציה שתופעל בשדה המבוקש, או `undefined` אם השדה לא מוגדר.

FieldName

שם השדה יכול להיות השם של שדה מותאם אישית שהגדרתם באמצעות הפקודה gtag('set'), או אחד מהערכים הבאים:

שם השדה	יעדים נתמכים
client_id	Google Analytics 4
session_id	Google Analytics 4
session_number	Google Analytics 4
gclid	Google Ads Floodlight

דוגמאות

קבלת ערך ל-Promise

const gclidPromise = new Promise(resolve => {
  gtag('get', 'DC-XXXXXXXX', 'gclid', resolve)
});

gclidPromise.then((gclid) => {
  // Do something with gclid...
})

שליחת אירוע אל Measurement Protocol

gtag('get', 'G-XXXXXXXXXX', 'client_id', (clientID) => {
  sendOfflineEvent(clientID, "tutorial_begin")
});

function sendOfflineEvent(clientID, eventName, eventData) {
  // Send necessary data to your server...
}

קבלת ערך שהגדרתם

gtag('set', {campaign_name: 'Spring_Sale'});

gtag('get', 'G-XXXXXXXXXX', 'campaign_name', (campaign_name) => {
  // Do something with currency value you set earlier.
})

`set`

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

gtag('set', {<parameter-value-pair>, <parameter-value-pair>});

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

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

gtag('set', 'campaign', {
  'id': 'abc',
  'source': 'google',
  'name': 'black_friday_promotion',
  'term': 'running+shoes',
});

`event`

משתמשים בפקודה event כדי לשלוח נתוני אירועים.

gtag('event', '<event_name>', {<event_params>});

‫<event_name> הוא אחד מהערכים הבאים:

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

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

הפקודה הבאה event מפעילה את האירוע המומלץ screen_view עם שני פרמטרים: app_name ו-screen_name.

gtag('event', 'screen_view', {
  'app_name': 'myAppName',
  'screen_name': 'Home'
});

`consent`

משתמשים בפקודה consent כדי להגדיר את ההסכמה.

gtag('consent', {<consent_arg>}, {<consent_params>});

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

‫<consent_arg> הוא 'default' או 'update'. הפרמטר 'default' משמש להגדרת פרמטרים של הסכמה שיוגדרו כברירת מחדל, והפרמטר 'update' משמש לעדכון הפרמטרים האלה אחרי שהמשתמש מציין את ההסכמה שלו.

יש תמיכה ב<consent_params> הבאים:

שם השדה	ערכים מותרים	תיאור
`ad_storage`	`'granted'` \| `'denied'`	מאפשר אחסון של נתונים שקשורים לפרסום, כמו קובצי Cookie (באתרים) או מזהי מכשירים (באפליקציות).
`ad_user_data`	`'granted'` \| `'denied'`	מגדיר הסכמה לשליחת נתוני המשתמש אל Google למטרות פרסום.
`ad_personalization`	`'granted'` \| `'denied'`	מגדיר הסכמה לפרסום מותאם אישית.
`analytics_storage`	`'granted'` \| `'denied'`	מאפשר אחסון של נתונים (כמו קובצי Cookie באתרים או מזהי אפליקציות באפליקציות) שקשורים לניתוח, למשל משך הביקור.
`wait_for_update`	כל מספר שלם חיובי	מגדיר את הזמן באלפיות השנייה להמתנה לקריאה לעדכון מצב ההסכמה.