This service lets you integrate google analytics tracker in your AngularJS applications easily.
You can use basic functions, `Analytics.trackEvent('video', 'play', 'django.mp4');` or more advanced e-commerce features like product tracking, promo codes, transactions...
Proudly brought to you by [@revolunet](http://twitter.com/revolunet), [@deltaepsilon](https://github.com/deltaepsilon), [@justinsa](https://github.com/justinsa) and [contributors](https://github.com/revolunet/angular-google-analytics/graphs/contributors)
**Note:** the single account syntax is internally represented as an unnamed account object that will have all properties defined to defaults, except for name.
// Set a single account with all properties defined
// Universal Analytics only
AnalyticsProvider.setAccount({
tracker: 'UA-12345-12',
name: "tracker1",
fields: {
cookieDomain: 'foo.example.com',
cookieName: 'myNewName',
cookieExpires: 20000
// See: [Analytics Field Reference](https://developers.google.com/analytics/devguides/collection/analyticsjs/field-reference) for a list of all fields.
// This function is used to qualify or disqualify an account object to be run with commands.
// If the function does not exist, is not a function, or returns true then the account object will qualify.
// If the function exists and returns false then the account object will be disqualified.
// The 'args' parameter is the set of arguments (which contains the command name) that will be sent to Universal Analytics.
return true;
},
set: {
forceSSL: true
// This is any set of `set` commands to make for the account immediately after the `create` command for the account.
// The property key is the command and the property value is passed in as the argument, _e.g._, `ga('set', 'forceSSL', true)`.
// Order of commands is not guaranteed as it is dependent on the implementation of the `for (property in object)` iterator.
},
trackEvent: true,
trackEcommerce: true
});
```
**Note:** the above properties are referenced and discussed in proceeding sections.
**Note:** the `cookieConfig` property is being **deprecated** for the `fields` property. At present `cookieConfig` is an alias for `fields` in an account object.
In the case of universal analytics, this value will be used as the default for any tracker that does not have the `displayFeatures` property defined. All trackers with `displayFeatures: true` will be registered for display features.
In the case of universal analytics, this value will be used as the default for any tracker that does not have the `enhancedLinkAttribution` property defined. All trackers with `enhancedLinkAttribution: true` will be registered for enhanced link attribution.
In the case of universal analytics, these values will be used as the default for any tracker that does not have the `crossDomainLinker` and `crossLinkDomains` properties defined. All trackers with `crossDomainLinker: true` will register the cross-linked domains.
This cookie configuration will be used as the default for any tracker that does not have the `cookieConfig` property defined.
### Track Events
This property is defined for universal analytics account objects only and is false by default.
If `trackEvent: true` for an account object then all `trackEvent` calls will be supported for that account object.
Set `trackEvent: false` for an account object that is not tracking events.
### Track E-Commerce
This property is defined for universal analytics account objects only. This property defaults to true if e-commerce is enabled (either classic or enhanced) and false otherwise.
If `trackEcommerce: true` for an account object then all e-commerce calls will be supported for that account object.
**Note:** Using this configuration option requires that you already know the user wants to opt-out before the analytics script is injected on the page. This is somewhat unlikely for most use cases given the nature of a single page application. This module provides a better alternative with `Offline` mode since you can effectively opt the user out of tracking by enabling offline mode at any time during execution.
// Log all outbound calls to an in-memory array accessible via ```Analytics.log``` (default is false).
// This is useful for troubleshooting and seeing the order of calls with parameters.
AnalyticsProvider.logAllCalls(true);
```
### Test Mode
```js
// This method is designed specifically for unit testing and entering test mode cannot be changed after
// being called. Test mode skips the insertion of the Google Analytics script tags (both classic and universal)
// and ensures there is a $window.ga() method available for calling by unit tests. This corrects transient
// errors that were seen during unit tests due to the operation of the Google Analytics scripts.
AnalyticsProvider.enterTestMode();
```
### Debug Mode
```js
// Calling this method will enable debugging mode for Universal Analytics. Supplying a truthy value for the
// optional parameter will further enable trace debugging for Universal Analytics. More information on this
// is available here: https://developers.google.com/analytics/devguides/collection/analyticsjs/debugging.
AnalyticsProvider.enterDebugMode(Boolean);
```
## Using the Analytics Service
**IMPORTANT!** Due to how Google Analytics works, it is important to remember that you must always call `Analytics.pageView();` when you want to push setting changes and function calls to Google Analytics.
### Automatic Page View Tracking
If you are relying on automatic page tracking, you need to inject Analytics at least once in your application.
```js
// As an example, add the service to the run call:
app.run(function(Analytics) {});
```
### Declaring a Controller
```js
// As an example, a simple controller to make calls from:
app.controller('SampleController', function (Analytics) {
// Add calls as desired - see below
});
```
### Accessing Configuration Settings
The following configuration settings are intended to be immutable. While the values can be changed in this list by the user, this will not impact the behavior of the service as these values are not referenced internally; exceptions are noted below but are not intended to be utilized in such a way by the user. No guarantee will be made for future versions of this service supporting any functionality beyond reading values from this list.
```js
// This is a mutable array. Changes to this list will impact service behaviors.
Analytics.configuration.accounts;
// If `true` then universal analytics is being used.
// If `false` then classic analytics is being used.
Analytics.configuration.universalAnalytics;
Analytics.configuration.crossDomainLinker;
Analytics.configuration.crossLinkDomains;
Analytics.configuration.currency;
Analytics.configuration.debugMode;
Analytics.configuration.delayScriptTag;
Analytics.configuration.disableAnalytics;
Analytics.configuration.displayFeatures;
Analytics.configuration.domainName;
// ecommerce and enhancedEcommerce are mutually exclusive; either both will be false or one will be true.
Analytics.configuration.ecommerce;
Analytics.configuration.enhancedEcommerce;
Analytics.configuration.enhancedLinkAttribution;
Analytics.configuration.experimentId;
Analytics.configuration.ignoreFirstPageLoad;
Analytics.configuration.logAllCalls;
Analytics.configuration.pageEvent;
Analytics.configuration.removeRegExp;
Analytics.configuration.traceDebuggingMode;
Analytics.configuration.trackPrefix;
Analytics.configuration.trackRoutes;
Analytics.configuration.trackUrlParams;
```
### Get or Set Cookie Configuration
**NOTE:** These methods are being **deprecated**. Use the `fields` property on the account object instead.
**Note:** Changing the cookie configuration after the AnalyticsProvider configuration does not update the individual account objects used by universal analytics (analytics.js). If you want to change the account objects used by universal analytics those can be accessed through `Analytics.configuration.accounts`, but such modification to the accounts object is unsupported.
// Returns the current URL that would be sent if a `trackPage` call was made.
// The returned value takes into account all configuration settings that modify the URL.
Analytics.getUrl();
```
### Manual Script Tag Injection
If `delayScriptTag(true)` was set during configuration then manual script tag injection is required. Otherwise, the script tag will be automatically injected and configured when the service is instantiated.
```js
// Manually create classic analytics (ga.js) script tag
Analytics.createScriptTag();
// Manually create universal analytics (analytics.js) script tag
Analytics.createAnalyticsScriptTag();
```
### Advanced Settings / Custom Dimensions
The `set` call allows for advanced configuration and definitions in univeral analytics only. This is a no-op when using classic analytics.
```js
// Set the User Id
Analytics.set('&uid', 1234);
// Register a custom dimension for the default, unnamed account object
// e.g., ga('set', 'dimension1', 'Paid');
Analytics.set('dimension1', 'Paid');
// Register a custom dimenstion for a named account object
`ga-track-event-if` is a conditional check. If the attribute value evaluates falsey, the event will **NOT** be fired. This is useful for user tracking opt-out, _etc._
AdBlock has a module named [EasyPrivacy](https://easylist-downloads.adblockplus.org/easyprivacy.txt) that is meant to block web tracking scripts. angular-google-analytics.js gets filtered out by the EasyPrivacy blacklist.
Users who are already concatenating and minifying their scripts should not notice a problem as long as the new script name is not also on the EasyPrivacy blacklist. Alternatively, consider changing the file name manually.
As AngularJS itself, this module is released under the permissive [MIT License](http://revolunet.mit-license.org). Your contributions are always welcome.
## Development
After forking you will need to run the following from a command line to get your environment setup:
1. ```npm install```
2. ```bower install```
After install you have the following commands available to you from a command line:
1. ```grunt lint```
2. ```npm test``` or ```grunt``` or ```grunt test```
3. ```npm test-server``` or ```grunt test-server```
