Home

Chrome Platform Analytics (CPA) is a JavaScript library that lets you use Google Analytics to measure user interactions in Chrome Platform Apps and Extensions.

• Overview
  • Features
  • Approach
• Prerequisites
• API Reference
• How-To
  • Configure your app
  • Initialize service objects
  • Track app view changes
  • Track events
  • Add privacy support (aka "opt-out")

Overview

The Google Analytics Platform lets you measure user interactions with your business across various devices and environments. The platform provides resources to collect, store, process, and report on user interactions. Chrome Platform Analytics (CPA) is a client library that lets you collect user interactions in Chrome Platform Apps (also known as Packaged Apps) and Extensions, and send them to the Google Analytics Platform.

Features

Google Analytics users will find the Chrome Platform Analytics library very familiar. In addition, the CPA library:

• uses an "app-centric" model that is better suited for Chrome Platform Apps & Extensions than the web-centric official Google Analytics JavaScript libraries;
• provides support for both Closure-based and traditional JavaScript projects;
• provides library-level support for opt-out, which makes it easy to build privacy-friendly apps; and
• works when a user's device is offline (the library is network-aware and does not cause errors when the network is unavailable)

Approach

The Chrome Platform Analytics library generally follows the model established by well-known Google Analytics (GA) tracking libraries, including:

• the analytics.js library,
• the ga.js library,
• and to a lesser extent the GA Android SDK.

Many of the features you're familiar with in the above libraries are available in the CPA library. The CPA library also provides methods for specific types of hits, such as "event" and "appView". Whenever possible we recommend you use these logical API methods, as they provide input validation and promote improved readability in your code.

Prerequisites

Before you use the Chrome Platform Analytics library, you should:

• know how to use Google Analytics;
• be familiar with the Google Analytics Policies (you must adhere to these plolicies; most notably you must permit your users to opt out of analytics tracking); and
• get a Google Analytics "App" tracking property.

API Reference

• (namespace) analytics - How you access analytics.GoogleAnalytics. Start here.
• analytics.GoogleAnalytics - How you access analytics.Tracker and analytics.Config.
• analytics.Tracker - How you send hits to Google Analytics.
• analytics.Config - How you inspect and manipulate the runtime configuration.

How-To

Configure your app

The library needs permission to communicate with Google Analytics. This permission must be listed in your Chrome App's Manifest file. The storage permission is also required because user-specific settings are stored using Chrome's storage API.

"permissions": [
  "https://www.google-analytics.com/",
  "storage"
],

If you are using the Closure tools, compile the Analytics code into your app the same way you compile in the Closure library or any other third-party Closure-style libraries. Otherwise, include google-analytics-bundle.js in your app:

<script src="google-analytics-bundle.js"></script>

Initialize service objects

// If you're using the closure compiler...
goog.require('analytics.getService');

// You'll usually only ever have to create one service instance.
var service = analytics.getService('ice_cream_app');

// You can create as many trackers as you want. Each tracker has its own state
// independent of other tracker instances.
var tracker = service.getTracker('UA-XXXXX-X');  // Supply your GA Tracking ID.

Track app view changes

When starting your app, or changing "places" in your app, you should always send an AppView hit. AppView information appears in the "Real-Time" reporting section in Google Analytics reporting for your property.

tracker.sendAppView('MainView');

Track events

Track user actions using an Event. Events have an optional numeric value that is averaged together by Google Analytics.

tracker.sendEvent('Flavor', 'Choose', 'Chocolate');

Add privacy support (aka "opt-out")

In order to use Google Analytics (and therefore the CPA library) you must allow users to opt out of tracking. This can be done using the setTrackingPermitted(boolean) method on the analytics.Config object. Passing false to this method disables reporting of information to Google Analytics. This setting is persisted across app sessions.

service.getConfig().addCallback(
    function(config) {
      var permitted = myApp.askUser('Allow anonymous usage tracking?');
      config.setTrackingPermitted(permitted);
      // If "permitted" is false the library will automatically stop
      // sending information to Google Analytics and will persist this
      // behavior automatically.
    });

See Respecting-User-Privacy for more information on this topic.