Skip to content

Latest commit

 

History

History
299 lines (221 loc) · 10.4 KB

README.md

File metadata and controls

299 lines (221 loc) · 10.4 KB
Raw

Google Analytics Module

Connects to Google Analytics for app event tracking in a Titanium Appcelerator Application. The 2.x release of this module is targeted for the Google Analytics SDK for iOS v3 and Google Analytics SDK v4 for Android.

64bit Capability

Version 3.0.0 of this module depends on version 3.5.0.GA (or greater) of the titanium SDK, which provides 64bit support on the iOS platform. If you are upgrading your application to use this new version and you are experiencing build problems, try clearing out your build and Resources folders and then recompile.

Set up Google Analytics

First step: you have to create a new app property in your Google Analytics-account. Refer to this page for more information.

Google Play Services

If you find that you are experiencing errors related to Google Play Services, then you should do two things:

  1. Ensure the device you are using has Google Play installed.

  2. Ensure your local sdk has the Google Play libraries installed. It is best if the library is at least version 21.

If you have checked both and you are still experiencing errors, then you can try uninstalling your local Google Play library and re-installing it.

Usage

To access this module from JavaScript, you need to do the following:

var GA = require("analytics.google");

The GA variable is a reference to the Module object. To interact with the tracker, create a tracker instance using the getTracker method.

var tracker = GA.getTracker("UA-1234567-8");
tracker.trackEvent({
	category: "Loading",
	action: "cancelled"
});

It has been suggested to store the tracker object on Alloy.Globals for convenience. For example:

// In Alloy.js
var GA = require("analytics.google");
Alloy.Globals.tracker = GA.getTracker(Alloy.CFG.googleAnalyticsId);

// Now in any controller, you can use the API as outlined in the documentation.
Alloy.Globals.tracker.trackEvent({
  category: "Loading",
  action: "cancelled"
});

Reference

Module.trackUncaughtExceptions

Set this property on the module to true when you want to enable uncaught exception tracking (crashes). Note this will not catch crashes on the Javascript thread (i.e. the Titanium "Red Screen of Death"), but should catch the exceptions on the native threads. In Android, we must initialize a tracker prior to setting this. If more than a single Tracker is used in the app, the last one set is the one that will track the uncaught exceptions.

var GA = require("analytics.google");
var tracker = GA.getTracker("UA-XXXXXXX-X"); // Android: Must be called prior to setting trackUncaughtExceptions
GA.trackUncaughtExceptions = true;

Module.optOut

Set this property to true if you want to disable analytics across the entire app.

var GA = require("analytics.google");
GA.optOut = false;

Module.dryRun

Set this property to true if you want to enable debug mode. This will prevent sending data to Google Analytics.

var GA = require("analytics.google");
GA.dryRun = true;

Module.dispatchInterval

Data collected using the Google Analytics SDK for Android is stored locally before being dispatched on a separate thread to Google Analytics. By default, data is dispatched from the Google Analytics SDK for Android every 30 minutes. By default, data is dispatched from the Google Analytics SDK for iOS every 2 minutes. Set this property if you would like to change the interval in seconds. Note that the iOS SDK requires the value in seconds and the Android SDK requires the value in minutes at the moment.

var GA = require("analytics.google");
if(Ti.Platform.osname == 'android') {
    GA.dispatchInterval = 2; // in minutes
}
else if(Ti.Platform.name == 'iPhone OS') {
    GA.dispatchInterval = 120; // in seconds
}

Module.getTracker(id)

Retrieve an analytics tracker object. Must pass the "UA-XXXXXXX-X" id string that you get from Google Analytics.

Tracker.setUser(params)

Tracks a user sign in with an 'anonymous' identifier. You will be breaking Google's terms of service if you use any of the user's personal information (including email address).

Property Type Description Required
userId String Unique identifier Yes
category String The event category Yes
action String The event action Yes 
tracker.setUser({
	userId: "123456",
	category: "UX",
	action: "User Sign In"
});

Tracker.trackEvent(params)

Tracks an event taking the following parameters:

Property Type Description Required
category String The event category Yes
action String The event action Yes
label String The event label No
value Integer The event value No 
tracker.trackEvent({
	category: "category",
	action: "test",
	label: "label",
	value: 1
});

Tracker.trackSocial(params)

Tracks social interactions taking the following parameters:

Property Type Description Required
network String e.g. facebook, pinterest, twitter Yes
action String The event action Yes
target String The event target No 
tracker.trackSocial({
	network: "facebook",
	action: "action",
	target: "target"
});

Tracker.trackTiming(params)

Tracks a timing taking the following parameters:

Property Type Description Required
category String The event category Yes
time Number In milliseconds Yes
name String The event name No
label String The event label No 
tracker.trackTiming({
	category: "Loading",
	time: 150,
	name: "",
	label: ""
});

Tracker.trackScreen(params)

Tracks a screen change using the screen's name.

Property Type Description Required
screenName String The name of the screen you want to record Yes 
tracker.trackScreen({
	screenName: "Home Screen"
});

Tracker.trackException(params)

Tracks an exception, for example a login error or network timeout.

Property Type Description Required
description String A string you wish to log to GA (up to 100 characters) No
fatal Boolean True if fatal exception, false otherwise. Default value is false. No 
tracker.trackException({
	description: "Facebook login error",
	fatal: false
});

Tracker.trackTransaction(params)

Tracks an ecommerce transaction.

Property Type Description Required
transactionId String A unique identifier Yes
affiliation String A category for the transaction. e.g. StoreFront Yes
revenue Number The total revenue including tax and shipping Yes
tax Number The amount of tax in the transaction Yes
shipping Number The amount of shipping in the transaction Yes
currency String The currency code. e.g. USD, CAD, etc. No 
tracker.trackTransaction({
	transactionId: "123456",
	affiliation: "Store",
	revenue: 24.99 * 0.7,
	tax: 0.6,
	shipping: 0,
	currency: "CAD"
});

Tracker.trackTransactionItem(params)

Tracks an ecommerce transaction's item.

Property Type Description Required
transactionId String A unique identifier that matches the identifier used in trackTransaction Yes
name String The name of the item Yes
sku String A reference number for the item Yes
category String A category for the item No
price Number The price of the item Yes
quantity Number The number of items purchased Yes
currency String The currency code. e.g. USD, CAD, etc. No 
tracker.trackTransactionItem({
	transactionId: "123456",
	name: "My Alphabet Book",
	sku: "ABC123",
	category: "product category",
	price: 24.99,
	quantity: 1,
	currency: "CAD"
});

Custom Dimensions and Metrics

The above method parameters can be extended using customMetric and customDimention properties. For example:

tracker.trackSocial({
	network: "facebook",
	action: "action",
	target: "target",
	customDimension: {
		"1": "Ottawa",
		"2": "Toronto"
	},
	customMetric: {
		"1": 45.4,
		"2": 68.3
	}
});

As per the Google Analytics API, custom metrics and dimensions are 1-based. Each property is expected to be defined by a string representation of the numeric index with its corresponding value. Metric values are expected to be numeric and Dimension values are expected to be strings.

Google Play Services

Version 2.1.0 of the android module uses Google Play Services Version 6.1 (rev 21 - 6171000).

Contributors

License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.