ההפניה לתור הפקודות של ga

תור הפקודות ga() מספק ממשק לביצוע כמעט כל מה שצריך לעשות עם ספריית analytics.js.

קטע הקוד של JavaScript למעקב מגדיר את הפונקציה הראשונית ga() של תור הפקודות, כך שניתן להשתמש בה עוד לפני שספריית analytics.js נטענת במלואה. לאחר שספריית analytics.js נטענת, הפריטים בתור הפקודות מתבצעים לפי הסדר שבו הם התקבלו. לאחר השלמת פעולה זו, פקודות חדשות שמועברות לתור מופעלות באופן מיידי.

הערה: קטעי קוד המעקב של JavaScript מאפשרים לשנות את השם של הפונקציה ga() של תור הפקודות. אם אתם עושים זאת, חשוב לוודא שכל קוד שאתם מעתיקים מהאתר הזה מפנה לשם החדש.

כדי שקטע קוד המעקב יהיה קטן ככל האפשר, תור הפקודות ga() עמוס מדי לקבלת ארגומנטים בפורמטים רבים ושונים. במסמך הזה מפורטות כל הדרכים השונות שבהן ניתן להפעיל את פונקציית תור הפקודות של ga().

חתימת פונקציה
ga(command, [...fields], [fieldsObject])	אם תפעילו את הפונקציה של תור הפקודות ga() עם חתימת הפונקציה הבאה, הפקודות יוכנסו לתור כדי לתזמן את ההפעלה שלו אחרי שהספרייה תיטען.
ga(readyCallback)	אם מעבירים את הפונקציה של תור הפקודות ga(), היא תתזמן את הפונקציה שהועברה להפעלה בנקודה הבאה בתור. מכיוון שהפקודות מתבצעות רק לאחר שספריית analytics.js נטענת במלואה, הסיבה הנפוצה ביותר להעביר את תור הפקודות שפונקציה היא קריאה חוזרת (callback) לזמן שבו ספריית analytics.js נטענת ומוכנה לשימוש.

הוספת פקודות לתור

אם תפעילו את הפונקציה של תור הפקודות ga() עם חתימת הפונקציה הבאה, הפקודות יוכנסו לתור כדי לתזמן את ההפעלה שלו אחרי שהספרייה תיטען.

Usage

ga(command, [...fields], [fieldsObject])

פרמטרים

שם	סוג	חובה	תיאור
command	string	כן	מזהה שמייצג את הפקודה שצריך להוסיף לתור. המזהה מורכב משלושה חלקים (שני החלקים הראשונים הם אופציונליים): [trackerName.][pluginName:]methodName trackerName השם של מכשיר המעקב שבו רוצים להפעיל את הפקודה המתוזמנת. אם לא יצוין שם של מכשיר מעקב, הפקודה תופעל במכשיר המעקב שמוגדר כברירת מחדל. pluginName השם של הפלאגין analytics.js שנדרש. אם מציינים pluginName, methodName חייב להיות שיטה שסופקה על ידי הפלאגין. methodName שם השיטה שתוזמנה להפעלה. אם לא מציינים שם של פלאגין, השיטה הזו חייבת להיות אחת משיטות הפקודה שמפורטות בהמשך.
...fields	*	no	פרמטר נוחות אופציונלי אחד או יותר לציון במהירות של שדות נפוצים. מספר השדות והשדות הספציפיים המותרים משתנים בהתאם לשיטת הפקודה קוראים.
fieldsObject	Object	no	אובייקט לציון ערכים נותרים שלא צוינו באף אחד מהפרמטרים של fields. אם מוגדר שדה מסוים גם בפרמטר fields וגם בפרמטר fieldsObject, המערכת תשתמש בערך שבשדה fieldsObject.

למידע נוסף על השדות, ניתן לעיין בחומר העזר בנושא שדות.

דוגמאות

דוגמאות לפקודות ספציפיות מפורטות בהמשך בקטע שיטות פקודות.

אפשר להתקשר חזרה

אם מעבירים את הפונקציה של תור הפקודות ga(), היא תתזמן את הפונקציה שהועברה להפעלה בנקודה הבאה בתור.

מכיוון שהפקודות מתבצעות רק לאחר שספריית analytics.js נטענת במלואה, הסיבה הנפוצה ביותר להעביר את תור הפקודות שפונקציה היא קריאה חוזרת (callback) לזמן שבו ספריית analytics.js נטענת ומוכנה לשימוש.

Usage

ga(readyCallback)

פרמטרים

שם	סוג	חובה	תיאור
readyCallback	Function	כן	פונקציית קריאה חוזרת שתופעל כשהספרייה טעונה במלואה ומוכנה לאינטראקציה איתה. הפונקציה מופעלת עם אובייקט המעקב שמוגדר כברירת מחדל כארגומנט הראשון. אם לא נוצר מעקב ברירת מחדל, הארגומנט הראשון הוא undefined. הערה: כאשר פונקציית הקריאה החוזרת מופעלת, כל שיטות האובייקט של ga זמינות לשימוש.

דוגמאות

// Queues a tracker object for creation.
ga('create', 'UA-XXXXX-Y', 'auto');

// Once the tracker has been created, log the
// client ID to the console.
ga(function(tracker) {
  console.log(tracker.get('clientId'));
});

// Queues a named tracker object for creation.
ga('create', 'UA-XXXXX-Y', 'auto', 'myTracker');

// When there is no default tracker, the first
// argument of the ready callback is `undefined`.
ga(function(tracker) {
  console.log(tracker); // Logs `undefined`.
});

פרטים על שיטת הפקודה

בהמשך מופיעה רשימה של כל השיטות שניתן להעביר לתור הפקודות של ga() (לא כולל שיטות של יישומי פלאגין).

create

יצירת מכונת מעקב חדשה עם השדות שצוינו.

Usage

ga('create', [trackingId], [cookieDomain], [name], [fieldsObject]);

פרמטרים

למידע נוסף על השדות, ניתן לעיין בחומר העזר בנושא שדות.

החזרות

undefined

דוגמאות

// Creates a default tracker for the Property UA-XXXXX-Y
// and uses automatic cookie domain configuration.
ga('create', 'UA-XXXXX-Y', 'auto');

// Creates a tracker with the name "myTracker" for the Property
// UA-XXXXX-Y, sets the cookieDomain to "example.com", and specifies
// a transport mechanism of "beacon".
ga('create', 'UA-XXXXX-Y', 'example.com', 'myTracker', {
  transport: 'beacon'
});

חשוב: אי אפשר לציין שם של מכשיר מעקב בחלק השיטה של הקריאה לפעולה. למשל, ga('myTracker.create', 'UA-XXXXX-Y`) לא עובד.

למידע נוסף על יצירת מכשירי מעקב, קראו את המדריך יצירת מכשירי מעקב.

---

send

שולחת היט ל-Google Analytics.

Usage

ga('[trackerName.]send', [hitType], [...fields], [fieldsObject]);

השדות שנשלחים הם הערכים שצוינו בפרמטרים ...fields ו-fieldsObject, שממוזגים עם השדות שמאוחסנים כרגע בכלי המעקב.

הערה: הערכים שצוינו ב-...fields וב-fieldsObject נשלחים עם ההיט הנוכחי, אבל הם לא מאוחסנים באובייקט המעקב. משתמשים בשיטה set כדי לעדכן מכשיר מעקב.

פרמטרים

השדות שאפשר לציין באמצעות הפרמטרים ...fields משתנים בהתאם לסוג ההיט. הטבלה הבאה מציגה את השדות שתואמים לכל סוג היט. סוגי היטים שלא מופיעים ברשימה לא מקבלים פרמטרים של ...fields, אלא רק fieldsObject.

סוג היט	...fields
pageview	page
event	eventCategory, eventAction, eventLabel, eventValue
social	socialNetwork, socialAction, socialTarget
timing	timingCategory, timingVar, timingValue, timingLabel

למידע נוסף על השדות, ניתן לעיין בחומר העזר בנושא שדות.

החזרות

undefined

דוגמאות

// Sends a pageview hit.
ga('send', 'pageview');

// Sends an event hit for the tracker named "myTracker" with the
// following category, action, and label, and sets the nonInteraction
// field value to true.
ga('send', 'event', 'link', 'click', 'http://example.com', {
  nonInteraction: true
});

מידע נוסף על שליחת היטים זמין במדריך שליחת נתונים ל-Google Analytics.

---

set

מגדיר צמד של שדה וערך יחיד או קבוצה של צמדי שדה/ערך באובייקט מעקב.

Usage

// Sets a single field and value.
ga('[trackerName.]set', fieldName, fieldValue);

// Sets a group of field/value pairs.
ga('[trackerName.]set', fieldsObject);

פרמטרים

למידע נוסף על השדות, ניתן לעיין בחומר העזר בנושא שדות.

החזרות

undefined

דוגמאות

// Sets the page field to "/about.html".
ga('set', 'page', '/about.html');

// Sets the page field to "/about.html" and the title to "About".
ga('set', {
  page: '/about.html',
  title: 'About'
});

מידע נוסף על עדכון מכשירי מעקב זמין במדריך קבלת והגדרה של נתוני מעקב.

---

require

נדרש פלאגין analytics.js.

Usage

ga('[trackerName.]require', pluginName, [pluginOptions]);

פרמטרים

שם	סוג	חובה	תיאור
pluginName	string	כן	שם הפלאגין הנדרש. הערה: אם הפלאגין הוא לא פלאגין רשמי של analytics.js, צריך לספק אותו במקום אחר בדף.
pluginOptions	Object	no	אובייקט אתחול שיועבר לבונה הפלאגין בעת יצירת המופע.

החזרות

undefined

דוגמה

// Requires the Enhanced Ecommerce plugin.
ga('require', 'ec');

// Requires the Advertising Features plugin
// named "myTracker" and override its default cookie name.
ga('myTracker.require', 'displayfeatures', {
  cookieName: 'display_features_cookie'
});

למידע נוסף על דרישת יישומי פלאגין של analytics.js, ניתן לעיין במדריך שימוש ביישומי פלאגין.

---

provide

מספק פלאגין של analytics.js ואת השיטות שלו לשימוש עם תור הפקודות של ga().

ga('provide', pluginName, pluginConstuctor);

הערה: בניגוד לרוב השיטות של ga() בתור, הפרמטר לא מקבל שם של כלי מעקב.

פרמטרים

שם	סוג	חובה	תיאור
pluginName	string	כן	שם הפלאגין שסופק. השם צריך להיות זהה לשם שמופיע בכל הקריאות require.
pluginConstuctor	Function	כן	פונקציית Constructor מספקת את כל הלוגיקה והשיטות של הפלאגין. ה-constructor הזה יופעל עם האובייקט pluginsOptions שצוין בשיטה require.

דוגמה

// Defines a plugin constructor
function MyPlugin(tracker, options) {
  // ...
}

// Provides the plugin for use with the ga() command queue.
ga('provide', 'myplugin', MyPlugin);

למידע נוסף על הוספת יישומי פלאגין מסוג analytics.js, קראו את המדריך בנושא כתיבה של יישומי פלאגין.

---

remove

הסרה של אובייקט מעקב.

Usage

ga('[trackerName.]remove');

דוגמאות

// Remove the default tracker.
ga('remove');

// Remove the  tracker named "myTracker".
ga('myTracker.remove');