Google Tag (gtag.js) API מורכב מפונקציה אחת, gtag()
, עם התחביר הבא:
gtag(<command>, <command parameters>);
<command>
היא אחת מהפקודות הבאות:<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>
הוא מזהה שמזהה באופן ייחודי את יעד ההיטים, כמו נכס ב-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 |
G-XXXXXXXXXX |
היעד שממנו יש לאחזר את הערכים. |
<field_name> | FieldName | client_id | שם השדה להורדה. |
קריאה חוזרת (callback) | Function |
(field) => console.log(field) |
פונקציה שיופעלה עם השדה המבוקש, או
|
FieldName
שם השדה יכול להיות השם של שדה בהתאמה אישית שהגדרתם באמצעות הפקודה 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', {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>});
לדוגמה, ניתן לשתף פרמטרים של campaign כך שניתן יהיה לגשת אליהם באמצעות תגים מרובים באותו דף.
הדוגמה הבאה ממחישה איך מגדירים שם ומזהה של קמפיין לאירוע שופינג בלאק פריידיי. מכיוון שהשתמשתם ב-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>
הוא:
- אירוע מומלץ. לכל אירוע מומלץ אפשר להוסיף פרמטרים מומלצים.
- אירוע מותאם אישית. אירוע בהתאמה אישית הוא שם של אירוע שרירותי שאתם יוצרים, עם פרמטרים שרירותיים (כלומר מותאמים אישית). לדוגמה, ראו איך משתמשים באירועים מותאמים אישית ב-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' |
מאפשרת שמירה של נתונים שקשורים לפרסום, כמו קובצי cookie (אינטרנט) או מזהי מכשירים (אפליקציות). |
ad_user_data |
'granted' | 'denied' |
מגדיר את ההסכמה לשליחת נתוני המשתמש אל Google למטרות פרסום. |
ad_personalization |
'granted' | 'denied' |
מגדירה הסכמה לפרסום מותאם אישית. |
analytics_storage |
'granted' | 'denied' |
מאפשרת שמירה של נתונים, כמו קובצי cookie (אתר) או מזהי אפליקציות (אפליקציות), שקשורים לניתוח נתונים, למשל משך ביקור. |
wait_for_update |
מספר שלם כלשהו | הגדרת פרק זמן באלפיות השנייה של המתנה לקריאה לעדכון ההסכמה. |