הפניית API של Google Tag

‫API של Google Tag‏ (gtag.js) מורכב מפונקציה אחת, 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
session_id
  • Google Analytics 4
session_number
  • Google Analytics 4
gclid
  • Google Ads
  • Floodlight

דוגמאות

קבלת ערך ל-Promise 

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

לדוגמה, אפשר לשתף פרמטרים של קמפיין כדי שכמה תגים באותו דף יוכלו לגשת אליהם.

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