Instrumentation

<msc-ga> is a web component which base on Google Analytics to provide easy setup and accurate tracking beacons.

I think moduleview counts should be separate from pageview. Pageview counts doesn't equal each module's view.

Try to think about it. When a user visit your website and system take all module's view even them don't appeare in viewport. This will hurt module's click through rate.

That's why I like to redesign beacon sending rule and provide <msc-ga> for you.

To let developers could capture the exactly beacons they want and setup with easy and smooth way.

Basic Usage

<msc-ga> is a web component. All we need to do is put the required script into your HTML document. Then follow <msc-ga>'s html structure and everything will be all set.

Required Script

<script async
        src="https://your-domain/pack-msc-ga.js">        
</script>

Structure

Put the content inside <msc-ga> as its child.

Note: content should be JSON for <msc-ga>'s init config and wrapped in script tag.

<msc-ga>
  <script type="application/json">
    {
      "vars": {
        var-name: var-value,
        ...
      },
      "extraTrackerData": {
        extraTrackerData-name: extraTrackerData-value,
        ...
      },
      "triggers": {
        trigger-name: trigger-object,
        ...
      }
    }
  </script>
</msc-ga>

Configuration

Let's take a look about figure out each part do.

vars

Developers could define some variables in vars and reuse them in other sections. Google Analytics property id must set as account.

The following code indicate some of extraTrackerData's value inherit vars'. (Use ${var-name} format)

{
  "vars": {
    "account": "UA-XXXXXX-X",
    "documentGroup": "msc-ga",
    "merchandiseId": "100430268264",
    "categoryId": "23000"
  },
  "extraTrackerData": {
    "contentGroup1": "${documentGroup}",
    "dimension1": "${merchandiseId}",
    "dimension2": "${categoryId}",
    "dimension3": "logined",
    ...
  },
  ...
}

extraTrackerData

Sometimes developers will be requested to attach some extra tracking data in each beacon. Those extra tracking data could be set here.

extraTrackerData's value could be set as you like or just inherit from vars with ${var-name} format.

Developers could figure field name out in Google Analytics document.

{
  ...
  "extraTrackerData": {
    "contentGroup1": "${documentGroup}",
    "dimension1": "${merchandiseId}",
    "dimension2": "${categoryId}",
    "dimension3": "logined",
    ...
  },
  ...
}

triggers - pageview

Developers could define trigger name by theirselves. Both of on and request are required in each trigger object.

{
  ...
  "triggers": {
      "defaultPageview": {
          "on": "visible", // [visible || click]
          "request": "pageview" // [pageview || event]
      },
      ...
  }
}

triggers - click

Set selector to decide what elements should sent beacon after clicked. (selector's format is as same as CSS)

event beacon's value: eventCategory, eventAction, eventLabel could be set in trigger-object's vars.

{
  ...
  "triggers": {
      "anchorClicks": {
          "on": "click",
          "request": "event",
          "selector": "#hd a",
          "vars": {
              "eventCategory": "${documentGroup}",
              "eventAction": "header",
              "eventLabel": "none"
          }
      },
      ...
  }
}

Besides above setting. Developers could rewrite vars with element's dataset attribute.

<a href="?"
   data-vars-event-category="xxx"
   data-vars-event-action="xxx"
   data-vars-event-label="xxx"
>
  trigger element
</a>

triggers - module view

Developers could set visibilitySpec for more accurate visible tracking. All of them are optional and with default value.

The following setting means: tracked module should at least 75% in viewport, and the visible beacon will be fired when module has been continue viewed more than 2s and accumulation viewed-time at least 5s.

(repeat:true means beacon will be fired when requests have been fulfill every time.)

{
  ...
  "triggers": {
      "defaultModuleview": {
          "on": "visible",
          "request": "event",
          "selector": ".code",
          "vars": {
              "eventCategory": "${documentGroup}",
              "eventAction": "moduleview",
              "eventLabel": "none"
          },
          "visibilitySpec": {
            "totalTime": 5000, // default is 0 (ms)
            "visiblePercentage": 0.75, // default is 0.75
            "continuousTime": 2000 // default is 0 (ms)
            "repeat": true // default is true
          }
      },
      ...
  }
}

Somehow developers might need to change the root for observe other element. Just fill the rootSelector and everything will be all done.

Of course, margin around the root is also available. Just fill rootMargin with CSS format.

{
  ...
  "triggers": {
      "defaultModuleview": {
          ...
          "visibilitySpec": {
            ...
            "rootSelector": ".new-root",
            "rootMargin": "10px 20px 10px 10px", // default is "0px"
            ...
          }
      },
      ...
  }
}


Here comes some extra setting for particular situation.

createVars

Sometimes developers might need to have different create setting between develop mode and production mode.

Note: the following seeting are all default value.

{
  ...
  "createVars": {
      "sampleRate": 100,
      "cookieDomain": "none",
      "useAmpClientId": true
  },
  ...
}

ecommerce

It is very important to add transaction and items information in payok page.

This will help commerce site to analyze the user flow and conversion rate.

Once developers had this request, they can setup with ecommerce value.

This page has already setup ecommerce value, you could trace the beacon with devTool - network.

{
  ...
  "ecommerce": {
    "transaction": {
      "id": "1234",
      "affiliation": "Acme Clothing",
      "revenue": "11.99",
      "shipping": "5",
      "tax": "1.29"
    },
    "items": [
      {
        "id": "1234",
        "name": "Fluffy Pink Bunnies",
        "sku": "DD23444",
        "category": "Party Toys",
        "price": "11.99",
        "quantity": "1" 
      },
      ...
    ]
  },
  ...
}

Method

Method Signature Description
get(fieldName) Gets the value of a field stored on the tracker.
set(fieldName|fieldsObject, [fieldValue]) Sets a field/value pair or a group of field/value pairs on the tracker.
send(hitType, [fieldsObject]) Sends a hit to Google Analytics.
setTrigger(triggerObject) Add / modify trigger obejct to msc-ga.
removeTrigger(triggerName) Remove trigger obejct from msc-ga.

Here comes some examples to indicate how to ues these above methods.

<script>
let msgGa, value;
msgGa = document.querySelector('msc-ga');

/* get */
value = msgGa.get('contentGroup1');

/* set */
msgGa.set('dimension1', 'msc-ga');
msgGa.set('dimension2', 'categoryId');
// same as
msgGa.set({
  dimension1: 'msc-ga',
  dimension2: 'categoryId'
});

/* send */
msgGa.send('pageview');
msgGa.send('event', {
  eventCategory: 'video',
  eventAction: 'play'
});

/* setTrigger */
msgGa.setTrigger(
  {
    "name": "defaultModuleview",
    "on": "visible",
    "request": "event",
    "selector": ".code",
    "vars": {
        "eventCategory": "${documentGroup}",
        "eventAction": "moduleview",
        "eventLabel": "none"
    },
    "visibilitySpec": {
      "continuousTime": 1000
      "repeat": false,
      "visiblePercentage": 0.5
    }
  }
);

/* removeTrigger */
msgGa.removeTrigger('defaultModuleview');
</script>