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.
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.
First step: you have to create a new app property in your Google Analytics-account. Refer to this page for more information.
If you find that you are experiencing errors related to Google Play Services, then you should do two things:
-
Ensure the device you are using has Google Play installed.
-
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.
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"
});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;Set this property to true if you want to disable analytics across the entire app.
var GA = require("analytics.google");
GA.optOut = false;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;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
}Retrieve an analytics tracker object. Must pass the "UA-XXXXXXX-X" id string that you get from Google Analytics.
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"
});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
});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"
});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: ""
});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"
});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
});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"
});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"
});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.
Version 2.1.0 of the android module uses Google Play Services Version 6.1 (rev 21 - 6171000).
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.