כתיבת יישומי פלאגין

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

הגדרת פלאגין

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

ה-constructor של יישומי הפלאגין

הדוגמה הבאה היא הבסיסית ביותר לפלאגין analytics.js:

// Defines the plugin constructor.
function MyPlugin() {
  console.log('myplugin has been required...');
}

// Registers the plugin for use.
ga('provide', 'myplugin', MyPlugin);

יישומי פלאגין צריכים לפעול כראוי גם במקרים שבהם השם של האובייקט הגלובלי ga השתנה. לכן, אם אתם כותבים פלאגין לשימוש של צד שלישי, עליכם לכלול בדיקה אם המשתנה GoogleAnalyticsObject הוגדר למחרוזת שאינה 'ga'. הפונקציה providePlugin הבאה עושה זאת:

// Provides a plugin name and constructor function to analytics.js. This
// function works even if the site has customized the ga global identifier.
function providePlugin(pluginName, pluginConstructor) {
  var ga = window[window['GoogleAnalyticsObject'] || 'ga'];
  if (typeof ga == 'function') {
    ga('provide', pluginName, pluginConstructor);
  }
}

הגדרת מכונות פלאגין

כאשר תור הפקודות ga() מריץ פקודת require, הוא יוצר אובייקט חדש באמצעות האופרטור new בפונקציה הבונה של הפלאגין provide. ה-constructor מועבר לאובייקט המעקב כארגומנט הראשון, וכל אפשרויות התצורה שמועברות לפקודה require כארגומנט השני שלו.

כדאי להוסיף לתג Google Analytics את פקודת ה-require הבאה:

ga('create', 'UA-XXXXX-Y', 'auto');
ga('require', 'localHitSender', {path: '/log', debug: true});
ga('send', 'pageview');

והקוד localHitSender:

function LocalHitSender(tracker, config) {
  this.path = config.path;
  this.debug = config.debug;
  if (this.debug) {
    console.log('localHitSender enabled for path: ' + this.path);
    console.log('on tracker: ' + tracker.get('name'));
  }
}

providePlugin('localHitSender', LocalHitSender);

כשהפקודה require רצה, הפרטים הבאים יתועדו במסוף (שימו לב שהשם של מכשיר המעקב שמוגדר כברירת מחדל הוא "t0"):

// localHitSender enabled for path: /log
// on tracker: t0

הגדרת שיטות פלאגין

יישומי פלאגין יכולים לחשוף את השיטות שלהם שניתן להפעיל באמצעות התחביר של תור הפקודות ga:

ga('[trackerName.]pluginName:methodName', ...args);

כאשר trackerName הוא אופציונלי ו-methodName תואם לשם של פונקציה באב הטיפוס של בוני הפלאגין. אם methodName לא קיים בפלאגין או שהפלאגין לא קיים, תופיע שגיאה.

דוגמה לקריאות ל-method של יישומי פלאגין:

// Execute the 'doStuff' method using the 'myplugin' plugin.
ga('create', 'UA-XXXXX-Y', 'auto');
ga('require', 'myplugin');
ga('myplugin:doStuff');

// Execute the 'setEnabled' method of the 'hitCopy' plugin on tracker 't3'.
ga('create', 'UA-XXXXX-Y', 'auto', {name: 't3'});
ga('t3.require', 'hitcopy');
ga('t3.hitcopy:setEnabled', false);

דוגמה להגדרות של שיטות פלאגין:

// myplugin constructor.
var MyPlugin = function(tracker) {
};

// myplugin:doStuff method definition.
MyPlugin.prototype.doStuff = function() {
  alert('doStuff method called!');
};

// hitcopy plugin.
var HitCopy = function(tracker) {
};

// hitcopy:setEnabled method definition.
HitCopy.prototype.setEnabled = function(isEnabled) {
  this.isEnabled = isEnabled;
}:

יישומי הפלאגין בטעינה

יישומי פלאגין נטענים בדרך כלל מקובץ JavaScript נפרד או מאוגדים יחד עם קוד האפליקציה הראשי.

<script async src="myplugin.js"></script>

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

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

הקוד הבא מראה איך הפקודה ga('require', 'myplugin') לא מבוצעת בפועל עד לשימוש בפקודה ga('provide', 'myplugin', ...), שלוש שניות מאוחר יותר.

ga('require', 'myplugin');

function MyPlugin() {
  console.log('myplugin has been required...');
}

// Waits 3 second after running the `require`
// command before running the `provide` command.
setTimeout(function() {
  ga('provide', 'myplugin', MyPlugin);
}, 3000);

דוגמאות

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

// campaign-loader.js

function providePlugin(pluginName, pluginConstructor) {
  var ga = window[window['GoogleAnalyticsObject'] || 'ga'];
  if (typeof ga == 'function') {
    ga('provide', pluginName, pluginConstructor);
  }
}

/**
 * Constructor for the campaignLoader plugin.
 */
var CampaignLoader = function(tracker, config) {
  this.tracker = tracker;
  this.nameParam = config.nameParam || 'name';
  this.sourceParam = config.sourceParam || 'source';
  this.mediumParam = config.mediumParam || 'medium';
  this.isDebug = config.debug;
};

/**
 * Loads campaign fields from the URL and updates the tracker.
 */
CampaignLoader.prototype.loadCampaignFields = function() {
  this.debugMessage('Loading custom campaign parameters');

  var nameValue = getUrlParam(this.nameParam);
  if (nameValue) {
    this.tracker.set('campaignName', nameValue);
    this.debugMessage('Loaded campaign name: ' + nameValue);
  }

  var sourceValue = getUrlParam(this.sourceParam);
  if (sourceValue) {
    this.tracker.set('campaignSource', sourceValue);
    this.debugMessage('Loaded campaign source: ' + sourceValue);
  }

  var mediumValue = getUrlParam(this.mediumParam);
  if (mediumValue) {
    this.tracker.set('campaignMedium', mediumValue);
    this.debugMessage('Loaded campaign medium: ' + mediumValue);
  }
};

/**
 * Enables / disables debug output.
 */
CampaignLoader.prototype.setDebug = function(enabled) {
  this.isDebug = enabled;
};

/**
 * Displays a debug message in the console, if debugging is enabled.
 */
CampaignLoader.prototype.debugMessage = function(message) {
  if (!this.isDebug) return;
  if (console) console.debug(message);
};

/**
 * Utility function to extract a URL parameter value.
 */
function getUrlParam(param) {
  var match = document.location.search.match('(?:\\?|&)' + param + '=([^&#]*)');
  return (match && match.length == 2) ? decodeURIComponent(match[1]) : '';
}

// Register the plugin.
providePlugin('campaignLoader', CampaignLoader);

ניתן לכלול את הקוד שלמעלה בדף HTML באופן הבא:

<script>
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','//www.google-analytics.com/analytics.js','ga');

ga('create', 'UA-XXXXX-Y', 'auto');
ga('require', 'campaignLoader', {
  debug: true,
  nameParam: 'cname',
  sourceParam: 'csrc',
  mediumParam: 'cmed'
});
ga('campaignLoader:loadCampaignFields');

ga('send', 'pageview');
</script>

<!--Note: plugin scripts must be included after the tracking snippet. -->
<script async src="campaign-loader.js"></script>

מעקב אוטומטי אחר יישומי פלאגין

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