הפניית API של Google Tag

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)

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

FieldName

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

שם השדה יעדים נתמכים
client_id
  • Google Analytics 4
  • Google Analytics 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', '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> הוא:

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