הפניית API של Google Tag

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

gtag(<command>, <command parameters>);
  • <command> היא אחת מהפקודות הבאות:
  • <command parameters> הם הפרמטרים שאפשר להעביר אל gtag(). הפרמטרים של הפקודה משתנים בהתאם לפקודה. ראה הפניה הבאה.

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

config

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

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

<TARGET_ID> הוא מזהה שמזהה באופן ייחודי את היעד להיטים, כמו נכס Google Analytics או חשבון Google Ads. <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 UA-XXXXXXXX-Y

היעד שממנו יש לשלוף את הערכים.
<field_name> שם שדה client_id שם השדה שיש לקבל.
קריאה חוזרת (callback) Function (field) => console.log(field)

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

שם שדה

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

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

דוגמאות

להפיק ערך מההבטחה 

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

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

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

gtag('get', 'UA-XXXXXXXX-Y', 'client_id', (clientID) => {
  sendOfflineEvent(clientID, "tutorial_begin")
});

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

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

gtag('set', {currency: 'USD'});

gtag('get', 'UA-XXXXXXXX-Y', 'currency', (currency) => {
  // Do something with currency value you set earlier.
})

set

היא מאפשרת להגדיר ערכים שיישמרו בכל קריאות gtag() הבאות בדף.

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

<parameter-value-pair> הוא שם מפתח והערך שיש לשמור לאורך gtag() שיחות. לדוגמה, הקוד הבא מגדיר את הערך של country לערך 'US', ואת הערך currency לערך 'USD' עבור כל האירועים הבאים בדף:

gtag('set', {
  'country': 'US',
  'currency': 'USD'
});

השימוש בפקודה set שונה מהעברת ערכים ישירות לפקודה event. כשמעבירים ערכים ישירות לפקודה event, הערכים האלה חלים רק על האירוע שמופעל. אבל עם set, הערכים נשארים בדף הנוכחי ועוברים עם כל האירועים הבאים. כדי להמחיש זאת, ניגודיות בין שתי הדוגמאות הבאות:

gtag('event', 'login', {'method': 'Google'});
gtag('event', 'share');

וגם

gtag('set', {'method': 'Google'});
gtag('event', 'login');
gtag('event', 'share');

בדוגמה הראשונה, האירוע login יועבר עם הערך method של 'Google' והאירוע share יועבר ללא פרמטרים. בדוגמה השנייה, גם login וגם share יועברו עם הערך method של 'Google'.

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'
analytics_storage 'granted' | 'denied'
wait_for_update כל מספר שלם חיובי

היקף הפרמטר

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

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

// Set global currency to Euros
gtag('set', { 'currency': 'EUR' });

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

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

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

// Set global currency to Euros
gtag('set', { 'currency': 'EUR' });

// 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>' });