Google Analytics Plugin
Cordova (PhoneGap) 3.0+ Plugin to connect to Google Analytics native SDK.
Prerequisites:
- A Cordova 3.0+ project for iOS and/or Android
- A Mobile App property through the Google Analytics Admin Console
Note: Demo Project available.
Platform SDK supported
- iOS, using Google Analytics SDK for iOS, v3.10
- Android, using Google Play Services for Android, v6.1
Quick start
To install this plugin, follow the Command-line Interface Guide. You can use one of the following command lines:
cordova plugin add cordova-plugin-analytics
cordova plugin add https://github.com/appfeel/analytics-google.git
Make sure to review the Google Analytics terms and SDK Policy
Javascript API
Note: All success callbacks are in the form 'function () {}'
, and all failure callbacks are in the form 'function (err) {}'
where err
is a String explaining the error reason.
Start Google Analytics
startTrackerWithId(id, success, fail);
Start Analtytics tracker:
- {String} id: (Required) your Google Analytics Universal code: UA-XXXXXXX-X.
- {function()} success: (Optional) success callback.
- {function()} failure: (Optional) failure callback.
Track Views, Events and Timings
trackView(screenName, options, success, error);
Tracks a screen view.
- {String} screenName: (Required) the name of the screen to track.
- {Object} options: (Optional) JSON object with additional options (see options).
- {function()} success: (Optional) success callback.
- {function()} failure: (Optional) failure callback.
trackEvent(category, action, label, value, options, success, error);
Tracks an event:
- {String} category: (Required) category of the event.
- {String} action: (Required) action of the event.
- {String} label: (Required) label of the event.
- {Long} value: (Required) value of the event.
- {Object} options: (Optional) JSON object with additional options (see options).
- {function()} success: (Optional) success callback.
- {function()} failure: (Optional) failure callback.
trackTiming(category, variable, value, label, options, success, error);
Tracks a timing hit:
- {String} category: (Required) category of the timing hit.
- {String} variable: (Required) measured variable (name) of the timing hit.
- {Long} value: (Required) value of the timing hit (time in milliseconds).
- {String} label: (Optional) label of the timing hit.
- {Object} options: (Optional) JSON object with additional options (see options).
- {function()} success: (Optional) success callback.
- {function()} failure: (Optional) failure callback.
options
A JSON object contining the following optional values:
- {Object} analytics.OPTIONS.CUSTOM_DIMENSIONS: JSON object with { dimensionIndex: dimensionValue, ... } pairs.
- {Object} analytics.OPTIONS.CUSTOM_METRICS: JSON object with { metricIndex: metricValue, ... } pairs.
- {String} analytics.OPTIONS.CAMPAIGN_URL: Campaign url. Example: http://www.appfeel.com?utm_campaign=analytics&utm_source=github (see here for more info).
Track Ecommerce
trackEcommerce(options, success, error);
Tracks an ecommerce hit. Note: Options are optional if they are optional in Google Analytics SDK. Note: You can optionally specify CUSTOM_DIMENSIONS, CUSTOM_METRICS and/or CAMPAIGN_URL in any tracking options object. Note: If PRODUCT_SCREEN_NAME, CATEGORY and ACTION values are provided in options, en event will be tracked instead a screen view. Note: If PRODUCT_SCREEN_NAME is specified, the tracking action will be senwith PRODUCT_SCREEN_NAME and then the tracker view will be set to previous screen value.
- {Object} options: (Optional) JSON object with ecommers options (see ecommerce options).
- {function()} success: (Optional) success callback.
- {function()} failure: (Optional) failure callback.
trackPromotion(options, success, error);
Track a promotion: Note: Options are optional if they are optional in Google Analytics SDK. Note: You can optionally specify CUSTOM_DIMENSIONS, CUSTOM_METRICS and/or CAMPAIGN_URL in any tracking options object. Note: If PRODUCT_SCREEN_NAME, CATEGORY and ACTION values are provided in options, en event will be tracked instead a screen view. Note: If PRODUCT_SCREEN_NAME is specified, the tracking action will be senwith PRODUCT_SCREEN_NAME and then the tracker view will be set to previous screen value.
- {Object} options: (Optional) JSON object with ecommers options (see ecommerce options).
- {function()} success: (Optional) success callback.
- {function()} failure: (Optional) failure callback.
Ecommerce examples
Note: See Google Documentation for a more detailed explanation.
Specifying Currency:
analytics.setCustomParam("&cu", "EUR");
Measuring impressions:
var options = {}; optionsanalyticsOPTIONSPRODUCT_ID = "P12345"; optionsanalyticsOPTIONSPRODUCT_NAME = "AppFeel Warhol T-Shirt"; optionsanalyticsOPTIONSPRODUCT_CATEGORY = "Apparel/T-Shirts"; optionsanalyticsOPTIONSPRODUCT_BRAND = "AppFeel"; optionsanalyticsOPTIONSPRODUCT_VARIANT = "Black"; optionsanalyticsOPTIONSPRODUCT_POSITION = 2; optionsanalyticsOPTIONSPRODUCT_SCREEN_NAME = "My Impression Screen"; optionsanalyticsOPTIONSPRODUCT_QUANTITY = 2; optionsanalyticsOPTIONSPRODUCT_PRICE = 1899; optionsanalyticsOPTIONSPRODUCT_LIST = "Search Results"; optionsanalyticsOPTIONSCUSTOM_DIMENSIONS = 1: "Member" ; optionsanalyticsOPTIONSCUSTOM_METRICS = 1: 30 4: 123 ; analytics;
Measuring actions:
var options = {}; optionsanalyticsOPTIONSPRODUCT_ID = "P12345"; optionsanalyticsOPTIONSPRODUCT_NAME = "AppFeel Warhol T-Shirt"; optionsanalyticsOPTIONSPRODUCT_CATEGORY = "Apparel/T-Shirts"; optionsanalyticsOPTIONSPRODUCT_BRAND = "AppFeel"; optionsanalyticsOPTIONSPRODUCT_VARIANT = "Black"; optionsanalyticsOPTIONSPRODUCT_POSITION = 2; optionsanalyticsOPTIONSPRODUCT_SCREEN_NAME = "My Impression Screen"; optionsanalyticsOPTIONSPRODUCT_QUANTITY = 2; optionsanalyticsOPTIONSPRODUCT_PRICE = 1899; optionsanalyticsOPTIONSPRODUCT_LIST = "Related Products"; optionsanalyticsOPTIONSPRODUCT_LIST_SOURCE = "My product list source"; optionsanalyticsOPTIONSPRODUCT_ACTION = analyticsOPTIONSPRODUCT_ACTION_CLICK; analytics;
Measuring impressions and actions:
var options = {}; optionsanalyticsOPTIONSPRODUCT_ID = "P12345"; optionsanalyticsOPTIONSPRODUCT_NAME = "AppFeel Warhol T-Shirt"; optionsanalyticsOPTIONSPRODUCT_CATEGORY = "Apparel/T-Shirts"; optionsanalyticsOPTIONSPRODUCT_BRAND = "AppFeel"; optionsanalyticsOPTIONSPRODUCT_VARIANT = "Black"; optionsanalyticsOPTIONSPRODUCT_POSITION = 2; optionsanalyticsOPTIONSPRODUCT_SCREEN_NAME = "My Impression Screen"; optionsanalyticsOPTIONSPRODUCT_QUANTITY = 2; optionsanalyticsOPTIONSPRODUCT_PRICE = 1899; optionsanalyticsOPTIONSPRODUCT_LIST = "Related Products"; optionsanalyticsOPTIONSPRODUCT_LIST_SOURCE = "My product list source"; optionsanalyticsOPTIONSPRODUCT_ACTION = analyticsOPTIONSPRODUCT_ACTION_DETAIL; optionsanalyticsOPTIONSRELATED_PRODUCT_ID = "P12346"; optionsanalyticsOPTIONSRELATED_PRODUCT_NAME = "AppFeel Warhol T-Shirt"; optionsanalyticsOPTIONSRELATED_PRODUCT_CATEGORY = "Apparel/T-Shirts"; optionsanalyticsOPTIONSRELATED_PRODUCT_BRAND = "AppFeel"; optionsanalyticsOPTIONSRELATED_PRODUCT_VARIANT = "White"; optionsanalyticsOPTIONSRELATED_PRODUCT_POSITION = 2; optionsanalyticsOPTIONSRELATED_PRODUCT_SCREEN_NAME = "My Impression Screen"; optionsanalyticsOPTIONSRELATED_PRODUCT_QUANTITY = 2; optionsanalyticsOPTIONSRELATED_PRODUCT_PRICE = 1899; analytics;
Measuring add to chart:
var options = {}; optionsanalyticsOPTIONSPRODUCT_ID = "P12345"; optionsanalyticsOPTIONSPRODUCT_NAME = "AppFeel Warhol T-Shirt"; optionsanalyticsOPTIONSPRODUCT_CATEGORY = "Apparel/T-Shirts"; optionsanalyticsOPTIONSPRODUCT_BRAND = "AppFeel"; optionsanalyticsOPTIONSPRODUCT_VARIANT = "Black"; optionsanalyticsOPTIONSPRODUCT_POSITION = 2; optionsanalyticsOPTIONSPRODUCT_SCREEN_NAME = "My Impression Screen"; optionsanalyticsOPTIONSPRODUCT_QUANTITY = 2; optionsanalyticsOPTIONSPRODUCT_PRICE = 1899; optionsanalyticsOPTIONSPRODUCT_COUPON_CODE = "APPARELSALE"; optionsanalyticsOPTIONSCATEGORY = "Ecommerce"; optionsanalyticsOPTIONSACTION = "+Chart"; optionsanalyticsOPTIONSPRODUCT_ACTION = analyticsOPTIONSPRODUCT_ACTION_ADD; analytics;
Measuring remove from chart:
var options = {}; optionsanalyticsOPTIONSPRODUCT_ID = "P12345"; optionsanalyticsOPTIONSPRODUCT_ACTION = analyticsOPTIONSPRODUCT_ACTION_REMOVE; analytics;
Measuring checkout process:
var options = {}; optionsanalyticsOPTIONSPRODUCT_ID = "P12345"; optionsanalyticsOPTIONSPRODUCT_NAME = "AppFeel Warhol T-Shirt"; optionsanalyticsOPTIONSPRODUCT_CATEGORY = "Apparel/T-Shirts"; optionsanalyticsOPTIONSPRODUCT_BRAND = "AppFeel"; optionsanalyticsOPTIONSPRODUCT_VARIANT = "Black"; optionsanalyticsOPTIONSPRODUCT_POSITION = 2; optionsanalyticsOPTIONSPRODUCT_SCREEN_NAME = "My Impression Screen"; optionsanalyticsOPTIONSPRODUCT_QUANTITY = 2; optionsanalyticsOPTIONSPRODUCT_PRICE = 1899; optionsanalyticsOPTIONSPRODUCT_COUPON_CODE = "APPARELSALE"; optionsanalyticsOPTIONSCATEGORY = "Ecommerce"; optionsanalyticsOPTIONSACTION = "Checkout"; optionsanalyticsOPTIONSPRODUCT_ACTION = analyticsOPTIONSPRODUCT_ACTION_CHECKOUT; optionsanalyticsOPTIONSCHECKOUT_STEP = 1; optionsanalyticsOPTIONSCHECKOUT_OPTION = "Visa"; analytics;
Measure a changed checkout option:
Note: You should not set any product or impression values.
var options = {}; optionsanalyticsOPTIONSCATEGORY = "Ecommerce"; optionsanalyticsOPTIONSACTION = "CheckoutOption"; optionsanalyticsOPTIONSPRODUCT_ACTION = analyticsOPTIONSPRODUCT_ACTION_CHECKOUT_OPTION; optionsanalyticsOPTIONSCHECKOUT_STEP = 1; optionsanalyticsOPTIONSCHECKOUT_OPTION = "Fedex"; analytics;
Measuring transactions:
var options = {}; optionsanalyticsOPTIONSPRODUCT_ID = "P12345"; optionsanalyticsOPTIONSPRODUCT_NAME = "AppFeel Warhol T-Shirt"; optionsanalyticsOPTIONSPRODUCT_CATEGORY = "Apparel/T-Shirts"; optionsanalyticsOPTIONSPRODUCT_BRAND = "AppFeel"; optionsanalyticsOPTIONSPRODUCT_VARIANT = "Black"; optionsanalyticsOPTIONSPRODUCT_POSITION = 2; optionsanalyticsOPTIONSPRODUCT_SCREEN_NAME = "My Impression Screen"; optionsanalyticsOPTIONSPRODUCT_QUANTITY = 2; optionsanalyticsOPTIONSPRODUCT_PRICE = 1899; optionsanalyticsOPTIONSPRODUCT_COUPON_CODE = "APPARELSALE"; optionsanalyticsOPTIONSPRODUCT_LIST = "Search Results"; optionsanalyticsOPTIONSPRODUCT_ID = "P12346"; optionsanalyticsOPTIONSPRODUCT_NAME = "AppFeel Warhol T-Shirt"; optionsanalyticsOPTIONSPRODUCT_CATEGORY = "Apparel/T-Shirts"; optionsanalyticsOPTIONSPRODUCT_BRAND = "AppFeel"; optionsanalyticsOPTIONSPRODUCT_VARIANT = "White"; optionsanalyticsOPTIONSPRODUCT_POSITION = 2; optionsanalyticsOPTIONSPRODUCT_SCREEN_NAME = "My Impression Screen"; optionsanalyticsOPTIONSPRODUCT_QUANTITY = 2; optionsanalyticsOPTIONSPRODUCT_PRICE = 1899; optionsanalyticsOPTIONSPRODUCT_COUPON_CODE = "APPARELSALE"; optionsanalyticsOPTIONSPRODUCT_LIST = "Search Results"; optionsanalyticsOPTIONSCATEGORY = "Ecommerce"; optionsanalyticsOPTIONSACTION = "Purchase"; optionsanalyticsOPTIONSPRODUCT_ACTION = analyticsOPTIONSPRODUCT_ACTION_PURCHASE; optionsanalyticsOPTIONSTRANSACTION_ID = "T12345"; optionsanalyticsOPTIONSTRANSACTION_AFFILIATION = "AppFeel Store - Online"; optionsanalyticsOPTIONSTRANSACTION_REVENUE = 1329; optionsanalyticsOPTIONSTRANSACTION_TAX = 570; optionsanalyticsOPTIONSTRANSACTION_SHIPPING = 500; optionsanalyticsOPTIONSTRANSACTION_COUPON_CODE = "SUMMER2014"; analytics;
Measuring refunds:
Partial refund:
var options = {}; optionsanalyticsOPTIONSPRODUCT_ID = "P12346"; optionsanalyticsOPTIONSPRODUCT_QUANTITY = 1; optionsanalyticsOPTIONSCATEGORY = "Ecommerce"; optionsanalyticsOPTIONSACTION = "Refund"; optionsanalyticsOPTIONSPRODUCT_ACTION = analyticsOPTIONSPRODUCT_ACTION_REFUND; optionsanalyticsOPTIONSTRANSACTION_ID = "T12345"; analytics;
Entire transaction:
var options = {}; optionsanalyticsOPTIONSCATEGORY = "Ecommerce"; optionsanalyticsOPTIONSACTION = "Refund"; optionsanalyticsOPTIONSPRODUCT_ACTION = analyticsOPTIONSPRODUCT_ACTION_REFUND; optionsanalyticsOPTIONSTRANSACTION_ID = "T12345"; analytics;
Measuring promotion impressions:
var options = {}; optionsanalyticsOPTIONSCATEGORY = "Ecommerce"; optionsanalyticsOPTIONSACTION = "Promotion-view"; optionsanalyticsOPTIONSPROMOTION_ID = "PROMO_1234 "; optionsanalyticsOPTIONSPROMOTION_NAME = "Summer Sale"; optionsanalyticsOPTIONSPROMOTION_CREATIVE = "summer_banner2"; optionsanalyticsOPTIONSPROMOTION_POSITION = "banner_slot1"; analytics;
Measuring promotion clicks:
var options = {}; optionsanalyticsOPTIONSCATEGORY = "Ecommerce"; optionsanalyticsOPTIONSACTION = "Promotion-click"; optionsanalyticsOPTIONSLABEL = "Summer Sale"; optionsanalyticsOPTIONSPROMOTION_ID = "PROMO_1234 "; optionsanalyticsOPTIONSPROMOTION_NAME = "Summer Sale"; optionsanalyticsOPTIONSPROMOTION_CREATIVE = "summer_banner2"; optionsanalyticsOPTIONSPROMOTION_POSITION = "banner_slot1"; optionsanalyticsOPTIONSPRODUCT_ACTION = analyticsOPTIONSPRODUCT_ACTION_CLICK; analytics;
Note: PRODUCT_ACTION and PRODUCT_ACTION_CLICK are not typo errors.
Social
trackSocial(network, action, target, options, success, error);
Tracks a timing hit:
- {String} network: (Required) The social network with which the user is interacting (e.g. Facebook, Google+, Twitter, etc.).
- {String} action: (Required) The social action taken (e.g. Like, Share, +1, etc.).
- {String} target: (Required) The content on which the social action is being taken (i.e. a specific article or video).
- {Object} options: (Optional) JSON object with additional options (see options).
- {function()} success: (Optional) success callback.
- {function()} failure: (Optional) failure callback.
Example:
analytics;
Configuration
setDispatchPeriod(period, success, error);
Specifies the dispatch period:
- {Number} period: (Required) Dispatch period in seconds.
- {function()} success: (Optional) success callback.
- {function()} failure: (Optional) failure callback.
setAppParams(options, success, error);
Override default app params:
- {Object} options: (Required) JSON object with app params (see below).
- {function()} success: (Optional) success callback.
- {function()} failure: (Optional) failure callback.
Example (all fields in options object are optional):
analytics;
setCampaignFromUrl(url, success, error);
Set campaign url:
- {Object} url: (Required) Campaign url. Example: http://www.appfeel.com?utm_campaign=com.analytics.google&utm_source=github&utm_content=setCampaignFromUrl&utm_medium=link (see here for more info).
- {function()} success: (Optional) success callback.
- {function()} failure: (Optional) failure callback.
setCustomParams(options, success, error);
Set any custom parameters you wish (append an & - ampersand - before each key):
- {Object} options: (Required) JSON object with custom params params (see here for more info).
- {function()} success: (Optional) success callback.
- {function()} failure: (Optional) failure callback.
Example:
analytics;
setCustomParam(key, value, success, error);
Set any custom param you wish (append an & - ampersand - before each key):
- {String} key: (Required) parameter name (see here for more info).
- {String} value: (Required) value for parameter.
- {function()} success: (Optional) success callback.
- {function()} failure: (Optional) failure callback.
setUserId(id, success, error);
Specify user id (improves cross-device tracking).
- {String} id: (Required) user id.
- {function()} success: (Optional) success callback.
- {function()} failure: (Optional) failure callback.
setDebugMode(success, error);
Sets log level to VERBOSE.
- {function()} success: (Optional) success callback.
- {function()} failure: (Optional) failure callback.