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

To use a specific version of Google's play-services-analytics library just specify it with the ANALYTICS_VERSION variable.

cordova plugin add com.cmackay.plugins.googleanalytics --variable ANALYTICS_VERSION='11.0.1'

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 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