הפניית 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)
ארגומנט Type דוגמה תיאור
<target> string G-XXXXXXXX

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

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

שם השדה

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

שם השדה יעדים נתמכים
client_id
  • Google Analytics 4
  • Universal Analytics ל-Google 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', 'G-XXXXXXXXXX', 'client_id', (clientID) => {
  sendOfflineEvent(clientID, "tutorial_begin")
});

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

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

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

gtag('get', 'G-XXXXXXXXXX', '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>' });