הפניית API של Google Tag

‫API של Google Tag‏ (gtag.js) מורכב מפונקציה אחת, gtag(), עם התחביר הבא:

gtag(<command>, <command parameters>);

• ‫<command> היא אחת מהפקודות הבאות:
  • config
  • get
  • set
  • event
  • consent
• ‫<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>' });

gtag('config', '<TARGET_ID>', {<additional_config_info>});

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)

FieldName

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

דוגמאות

קבלת ערך ל-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

משתמשים בפקודה consent כדי להגדיר את ההסכמה.

gtag('consent', {<consent_arg>}, {<consent_params>});

מידע נוסף על ההתנהגות שמוגדרת על ידי הפרמטרים האלה זמין במאמר בנושא הסכמה במרכז העזרה.

‫<consent_arg> הוא 'default' או 'update'. הפרמטר 'default' משמש להגדרת פרמטרים של הסכמה שיוגדרו כברירת מחדל, והפרמטר 'update' משמש לעדכון הפרמטרים האלה אחרי שהמשתמש מציין את ההסכמה שלו.

יש תמיכה ב<consent_params> הבאים: