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