ה-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) |
פונקציה שמופעלת עם השדה המבוקש, או |
שם השדה
שם השדה יכול להיות שם של שדה מותאם אישית שהגדרתם באמצעות הפקודה gtag('set')
, או אחד מהערכים הבאים:
שם השדה | יעדים נתמכים |
---|---|
client_id |
|
session_id |
|
gclid |
|
דוגמאות
הרווחת הבטחה
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>
יכול להיות:
- אירוע מומלץ. כל אירוע מומלץ יכול לכלול פרמטרים מומלצים.
- אירוע מותאם אישית. אירוע מותאם אישית הוא שם של אירוע שרירותי שאתם יוצרים, עם פרמטרים שרירותיים (כלומר בהתאמה אישית). לדוגמה, אפשר להשתמש באירועים מותאמים אישית ב-Google Analytics.
<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' |
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>' });