@advanced-rest-client/app-analytics

app-analytics

Event based component to support Google Analytics measurement protocol.

The component support both imperative and declarative API so it can be used in regular HTML template using your favourite templating engine and in JavaScript.

The appname and trackingid attributes (appName and trackingId properties respectively) are required parameters. Without it the element won't initialize a call to GA endpoint.

If clientid attribute (clientId property) is not set then it generates one automatically and store is in localStorage. Note, that if current environment does not support localStorage (like Chrome Apps) you need to provide this property manually or otherwise it will be regenerated each time the user opens the app.

Note, Google Analytics does not allow sending any information that may lead to a user.

Always give the user ability to disable tracking. Under EU laws you need to have permission from the user to store data on local device. To disable analytics simply remove the element from the DOM or set disabled property.

Note, the disabled state is persistent in localStorage and automatically restored when element is initialized. If the environment does not support localStorage you need to set this attribute manually each time the element is initialized.

Using events API

You can directly call one of send*() functions. See API Reference below for more info.

• sendEvent
• sendException
• sendScreen
• sendSocial
• sendTimings

You can also use HTML events to send a hit. In this case dispatch a send-analytics event with required type property on the detail object which describes what king of hit should be send. Possible values are: pageview, screenview, event, social, exception or timing.

Other parameters depends on the type.

Sending screenview hit

const event = new CustomEvent('send-analytics', {
 bubbles: true,
 composed: true,
 detail: {
   type: 'screenview',
   name: 'Some scree name' // required
 }
});
document.body.dispatchEvent(event);

Sending event hit

const event = new CustomEvent('send-analytics', {
 bubbles: true,
 composed: true,
 detail: {
   type: 'event',
   category: 'Some category', // required.
   action: 'Some action', // required.
   label: 'Some label',
   value: 123
 }
});
document.body.dispatchEvent(event);

Sending exception hit

const event = new CustomEvent('send-analytics', {
 bubbles: true,
 composed: true,
 detail: {
   type: 'exception',
   description: 'Exception description', // required.
   fatal: true, // default false
 }
});
document.body.dispatchEvent(event);

Sending social hit

const event = new CustomEvent('send-analytics', {
 bubbles: true,
 composed: true,
 detail: {
   type: 'social',
   network: 'Facebook', // required.
   action: 'Share', // required
   target: 'https://www.shared.com/resource' // required
 }
});
document.body.dispatchEvent(event);

Sending timing hit

const event = new CustomEvent('send-analytics', {
 bubbles: true,
 composed: true,
 detail: {
   type: 'timing',
   category: 'Bootstrap', // required.
   variable: 'databaseInitTime', // required
   value: 123, // required
   label: 'Optional label'
 }
});
document.body.dispatchEvent(event);

Custom metrics and dimensions

Use <app-analytics-custom> element as a child of <app-analytics> to set custom properties. This metrics / dimensions will be used with every hit as long as this elements exists as a children of the <app-analytics> element.

Example

<app-analytics trackingid="UA-XXXXXXX">
 <app-analytics-custom type="metric" index="1" value="5"></app-analytics-custom>
</app-analytics>

To send custom data with single hit only without creating <app-analytics-custom> children, add customDimensions or customMetrics to the event detail object. Both objects must be an array of custom definition objects that includes index and value.

Example

const event = new CustomEvent('send-analytics', {
 bubbles: true,
 composed: true,
 detail: {
   type: 'event',
   category: 'Engagement',
   action: 'Click',
   label: 'Movie start',
   customDimensions: [{
     index: 1, // index of the custom dimension
     value: 'Author name' // Value of the custom dimension
   }]
 }
});
document.body.dispatchEvent(event);

Usage

In a HTML page

<script type="module" src="@advanced-rest-client/app-analytics/app-analytics.js"></script>
<script type="module" src="@advanced-rest-client/app-analytics/app-analytics-custom.js"></script>

<app-analytics trackingid="UA-XXXXXXX">
 <app-analytics-custom type="metric" index="1" value="5"></app-analytics-custom>
</app-analytics>

In a LitElement template

import { LitElement, html } from 'lit-element';
import '@advanced-rest-client/app-analytics/app-analytics.js';
import '@advanced-rest-client/app-analytics/app-analytics-custom.js';

class SampleElement extends LitElement {
  render() {
    return html`
    <button @click="${this._handler}">Click with action</button>

    <app-analytics trackingid="UA-XXXXXXX">
     <app-analytics-custom type="metric" index="1" value="5"></app-analytics-custom>
    </app-analytics>
    `;
  }

  _handler(e) {
    this.shadowRoot.querySelector('app-analytics').sendScreen('Main screen');
  }
}
customElements.define('sample-element', SampleElement);

Imperative use

<app-analytics trackingid="UA-XXXXXXX">
 <app-analytics-custom type="metric" index="1" value="5"></app-analytics-custom>
</app-analytics>
<script>
{
  document..querySelector('app-analytics').sendScreen('Main screen');
}
</script>

New in version 3

• Dropped support for Polymer library. It is now a plain web component.
• Added aria-hidden attribute.
• Removed internal recognition of offline mode. Use offline property instead to enable queueing for events to be send when back online.

Development

git clone https://github.com/@advanced-rest-client/app-analytics
cd app-analytics
npm install

Running the demo locally

npm start

Running the tests

npm test

Changelog

3.0.0 (2019-07-19)

Breaking

• Upgrading to Polymer 3 (b34675e4fc4f9cbbef0d10e512928b4b3f8c0e76)

build

• bumping version to stable (a9b2195e2b1a6088e2d7f9172e868c856c14afe4)

chore

• dropping support for Polymer library (d58440a979a8a0daf6dbef1bb743e08b9dea7b27)

docs

• updating docs (f169c7d53b234ac798ce3427763f11c1c4607fe9)
• updating typpings (40911ae1df69c32a3124e5abc2cd7f74f043fc2b)

Docs

• Updating readme (d890e574dad41255a12486c073e8bb3068aac0f5)

fix

• fixing _baseParams type (8c0e131f0264a78bc51cf110909ed58c5a644e45)
• removing Polymer as a dependency (1e79488ad5f026ee97a40b14cddc390a4fe52dcd)

Fix

• Fixing configuration when disabled/cid changes (5b2d6e58b833d62e99f7347dad125a937fdc2d2b)

test

• finishing test for new version (5210d394409d17f981e0e4784653481a4d6237bf)
• fixing tests for edge (35b8958642980a70ec17316d8b88f970c47dc9b1)

Update

• Adding type check for local storage for chrome apps (809e22ac9753e606d2dbd0867bc6ab9982f05766)
• Adding type check for localStorage (040004f363f0374aa05893e8590db610ed6edb00)
• Removed support for disabling GA. Remove element from the DOM instead. (d6d04a56d63495b3b724f53eb355ccab7ccd46ef)
• Updating import paths to match web spec (e19246bc8609ecd07ae5b451fe8c27106ca03c7c)