דף זה תורגם על ידי Cloud Translation API.

הפניית API של Google Tag

Google Tag (gtag.js) API מורכב מפונקציה אחת, 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>' });

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

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

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