הפניית API של Google Tag

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

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

אפשר להפעיל פקודות 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 כדי להגדיר את ההסכמה.

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 כל מספר שלם חיובי ההגדרה הזו קובעת את משך הזמן באלפיות השנייה להמתנה לקריאה לעדכון של מצב ההסכמה.