README
google-analytics-plugin
Provides Apache Cordova/Phonegap support for Google Analytics using the native sdks for Android & iOS.
- Android Native SDK v4 (using Google Play Services SDK)
- iOS Native SDK v3
This plugin provides support for some of the more specific analytics functions (screen, event & exception tracking, custom metrics & dimensions) and also the more generic set and send functions which can be used to implement all of the Google Analytics collection features.
As an example tracking a screen could be implemented using either the sendAppView function or the send function:
var analytics = navigator.analytics;
// set the tracking id
analytics.setTrackingId('UA-XXXXX-X');
// ...or set multiple tracking ids
analytics.setMultipleTrackingIds(['UA-XXXXX-1', 'UA-XXXXX-2']);
analytics.sendAppView('home', successCallback, errorCallback);
// or the same could be done using the send function
var Fields = analytics.Fields,
HitTypes = analytics.HitTypes,
LogLevel = analytics.LogLevel,
params = {};
params[Fields.HIT_TYPE] = HitTypes.APP_VIEW;
params[Fields.SCREEN_NAME] = 'home';
analytics.setLogLevel(LogLevel.INFO);
analytics.send(params, successCallback, errorCallback);
The send & set functions provide maximum flexibility and allow you to utilize all of the Google Analytics collection calls. Some helper functions are also provided to support some of the more common analytic functions.
For more information about measurement protocol refer to the following page:
Measurement Protocol Developer Guide
Installation
cordova plugin add com.cmackay.plugins.googleanalytics
API
analytics
- analytics
- .Fields
- .HitTypes
- .LogLevel
- .setTrackingId(trackingId, [success], [error])
- .setMultipleTrackingIds(trackingIds, [success], [error])
- .setDispatchInterval(seconds, [success], [error])
- .getAppOptOut([success])
- .setAppOptOut([enabled], [success], [error])
- .setLogLevel(logLevel, [success], [error])
- .dispatchHits([success], [error])
- .get(key, success, [error])
- .set(key, value, [success], [error])
- .send(params, [success], [error])
- .close([success], [error])
- .customDimension(id, [value], [success], [error])
- .customMetric(id, [value], [success], [error])
- .sendEvent(category, action, [label], [value], [success], [error])
- .sendEventWithParams(category, action, [label], [value], params, [success], [error])
- .sendAppView(screenName, [success], [error])
- .sendAppViewWithParams(screenName, params, [success], [error])
- .sendTiming(category, variable, label, time, [success], [error])
- .sendException(description, [fatal], [success], [error])
- .trackUnhandledScriptErrors([opts], [success], [error])
analytics.Fields
GA Field Types
Kind: static property of analytics
analytics.HitTypes
GA Hit Types
Kind: static property of analytics
analytics.LogLevel
Log Levels
Kind: static property of analytics
analytics.setTrackingId(trackingId, [success], [error])
Sets the tracking id
Kind: static method of analytics
| Param | Type | Description |
|---|---|---|
| trackingId | string |
the trackingId |
| [success] | function |
the success callback |
| [error] | function |
the error callback |
analytics.setMultipleTrackingIds(trackingIds, [success], [error])
Sets multiple tracking ids. This will override any tracking id previously set.
Kind: static method of analytics
| Param | Type | Description |
|---|---|---|
| trackingIds | array |
array of trackingId parameters |
| [success] | function |
the success callback |
| [error] | function |
the error callback |
analytics.setDispatchInterval(seconds, [success], [error])
Sets the dispatch Interval
Kind: static method of analytics
| Param | Type | Description |
|---|---|---|
| seconds | number |
the interval in seconds |
| [success] | function |
the success callback |
| [error] | function |
the error callback |
analytics.getAppOptOut([success])
Get app-level opt out flag that will disable Google Analytics
Kind: static method of analytics
| Param | Type | Description |
|---|---|---|
| [success] | function |
the success callback (value is passed to callback) |
analytics.setAppOptOut([enabled], [success], [error])
Set app-level opt out flag that will disable Google Analytics
Kind: static method of analytics
| Param | Type | Default | Description |
|---|---|---|---|
| [enabled] | boolean |
true |
true for opt out or false to opt in |
| [success] | function |
the success callback | |
| [error] | function |
the error callback |
analytics.setLogLevel(logLevel, [success], [error])
Sets the log level
Kind: static method of analytics
| Param | Type | Description |
|---|---|---|
| logLevel | number |
the log level (refer to LogLevel for values) |
| [success] | function |
the success callback |
| [error] | function |
the error callback |
analytics.dispatchHits([success], [error])
Manually dispatches hits
Kind: static method of analytics
| Param | Type | Description |
|---|---|---|
| [success] | function |
the success callback |
| [error] | function |
the error callback |
analytics.get(key, success, [error])
Gets a field value. Returned as argument to success callback. If multiple trackers are being used, this returns an array of trackerId and field value pairs, e.g., [{ "UA-XXXXX-1" : "field_value1" }, { "UA-XXXXX-2" : "field_value2" }]
Kind: static method of analytics
| Param | Type | Description |
|---|---|---|
| key | string |
the key |
| success | function |
the success callback |
| [error] | function |
the error callback |
analytics.set(key, value, [success], [error])
Sets a field value
Kind: static method of analytics
| Param | Type | Description |
|---|---|---|
| key | string |
the key |
| value | the value | |
| [success] | function |
the success callback |
| [error] | function |
the error callback |
analytics.send(params, [success], [error])
Generates a hit to be sent with the specified params and current field values
Kind: static method of analytics
| Param | Type | Description |
|---|---|---|
| params | object |
the params |
| [success] | function |
the success callback |
| [error] | function |
the error callback |
analytics.close([success], [error])
Closes the the tracker
Kind: static method of analytics
| Param | Type | Description |
|---|---|---|
| [success] | function |
the success callback |
| [error] | function |
the error callback |
analytics.customDimension(id, [value], [success], [error])
Sets a custom dimension
Kind: static method of analytics
| Param | Type | Description |
|---|---|---|
| id | number |
the id |
| [value] | string |
the value |
| [success] | function |
the success callback |
| [error] | function |
the error callback |
analytics.customMetric(id, [value], [success], [error])
Sets a custom metric
Kind: static method of analytics
| Param | Type | Description |
|---|---|---|
| id | number |
the id |
| [value] | number |
the value |
| [success] | function |
the success callback |
| [error] | function |
the error callback |
analytics.sendEvent(category, action, [label], [value], [success], [error])
Sends an event
Kind: static method of analytics
| Param | Type | Default | Description |
|---|---|---|---|
| category | string |
the category | |
| action | string |
the action | |
| [label] | string |
"''" |
the label |
| [value] | number |
0 |
the value |
| [success] | function |
the success callback | |
| [error] | function |
the error callback |
analytics.sendEventWithParams(category, action, [label], [value], params, [success], [error])
Sends an event with additional params
Kind: static method of analytics
| Param | Type | Default | Description |
|---|---|---|---|
| category | string |
the category | |
| action | string |
the action | |
| [label] | string |
"''" |
the label |
| [value] | number |
0 |
the value |
| params | object |
the params | |
| [success] | function |
the success callback | |
| [error] | function |
the error callback |
analytics.sendAppView(screenName, [success], [error])
Sends a screen view
Kind: static method of analytics
| Param | Type | Description |
|---|---|---|
| screenName | string |
the screenName |
| [success] | function |
the success callback |
| [error] | function |
the error callback |
analytics.sendAppViewWithParams(screenName, params, [success], [error])
Sends a screen view with additional params
Kind: static method of analytics
| Param | Type | Description |
|---|---|---|
| screenName | string |
the screenName |
| params | object |
the params |
| [success] | function |
the success callback |
| [error] | function |
the error callback |
analytics.sendTiming(category, variable, label, time, [success], [error])
Sends a user timing
Kind: static method of analytics
| Param | Type | Description |
|---|---|---|
| category | string |
the category |
| variable | string |
the variable |
| label | string |
the label |
| time | number |
the time |
| [success] | function |
the success callback |
| [error] | function |
the error callback |
analytics.sendException(description, [fatal], [success], [error])
Sends an exception
Kind: static method of analytics
| Param | Type | Description |
|---|---|---|
| description | string |
the exception description |
| [fatal] | boolean |
marks the exception as fatal |
| [success] | function |
the success callback |
| [error] | function |
the error callback |
analytics.trackUnhandledScriptErrors([opts], [success], [error])
Tracks unhandled scripts errors (window.onerror) and then calls sendException. This function optionally can be passed an object containing a formmatter function which takes in all the args to window.onError and should return a String with the formatted error description to be sent to Google Analytics. Also the object can provide a fatal property which will be passed to sendException (defaults to true).
Kind: static method of analytics
| Param | Type | Description |
|---|---|---|
| [opts] | object |
the options { formatter: Function, fatal: Boolean } |
| [success] | function |
the success callback |
| [error] | function |
the error callback |