GoogleAnalytics

public final class GoogleAnalytics extends Object

The top level Google Analytics singleton that provides methods for configuring Google Analytics and creating Tracker objects.

Applications can get an instance of this class by calling getInstance(Context). getInstance(Context) is thread safe and can be called from any thread. It is recommended that Google Analytics be initialized early in the application lifecycle to correctly report unhandled exceptions. Application.Application.onCreate() is the recommended place for configuring Google Analytics.

A basic configuration of Google Analytics look like this:

 package com.example;

 class MyApp extends Application {
   public static GoogleAnalytics analytics;
   public static Tracker tracker;

   @Overwrite
   public void onCreate() {
     analytics = GoogleAnalytics.getInstance(this);
     analytics.setLocalDispatchPeriod(1800);

     tracker = analytics.newTracker("UA-000-1"); // Replace with actual tracker id
     tracker.enableExceptionReporting(true);
     tracker.enableAdvertisingIdCollection(true);
     tracker.enableAutoActivityTracking(true);
   }
 }
Analytics requires INTERNET and ACCESS_NETWORK_STATE permissions. Optionally a WAKE_LOCK permission can be requested to improve dispatching on non-Google Play devices.

To use a custom application class such as MyApp, it needs to be set in the AndroidManifest as the application name attribute.

A snippet for common GoogleAnalytics configuration in ApplicationManifest.xml looks like this:

 <manifest>
   <!-- Google Analytics required permissions -->
   <uses-permission android:name="android.permission.INTERNET" />
   <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

   <!-- Optional permission for reliable local dispatching on non-Google Play devices -->
   <uses-permission android:name="android.permission.WAKE_LOCK" />

   <application
     name="com.example.MyApp"> <!-- Replace with the custom app class when applicable -->

     <!-- Add the following meta-data for devices running Google Play service. -->
     <meta-data
       android:name="com.google.android.gms.version"
       android:value="@integer/google_play_services_version" />

     <!-- Optionally, register AnalyticsReceiver and AnalyticsService to support background
          dispatching on non-Google Play devices -->
     <receiver android:name="com.google.android.gms.analytics.AnalyticsReceiver"
         android:enabled="true">
         <intent-filter>
             <action android:name="com.google.android.gms.analytics.ANALYTICS_DISPATCH" />
         </intent-filter>
     </receiver>
     <service android:name="com.google.android.gms.analytics.AnalyticsService"
         android:enabled="true"
         android:exported="false"/>

     <!-- Optionally, register CampaignTrackingReceiver to enable installation campaign
         reporting -->
     <receiver android:name="com.google.android.gms.analytics.CampaignTrackingReceiver"
         android:exported="true">
         <intent-filter>
             <action android:name="com.android.vending.INSTALL_REFERRER" />
         </intent-filter>
     </receiver>

     <!-- ... -->
   </application>
 </manifest>

Applications can optionally provide a metadata reference to a global configuration XML resource file in the <application> element of their AndroidManifest.xml:

 <manifest>
   <application>
     <!-- ... -->

     <meta-data
       android:name="com.google.android.gms.analytics.globalConfigResource"
       android:resource="@xml/analytics_global_config" />

     <!-- ... -->
   </application>
 </manifest>
The configuration file should be stored in the applications res/xml directory and it should look like this: 
 <?xml version="1.0" encoding="utf-8" ?>
 <resources>
     <!-- The application name. Defaults to name specified for the application label -->
     <string name="ga_appName">My App</string>

     <!-- The application version. Defaults to android:versionName specified in the
       AndroidManifest.xml -->
     <string name="ga_appVersion">1.0</string>

     <!-- The dispatching period in seconds when Google Play services is unavailable. The
     default period is 1800 seconds or 30 minutes -->
     <integer name="ga_dispatchPeriod">1800</integer>

     <!-- Enable dry run mode. Default is false -->
     <bool name="ga_dryRun">false</bool>
 </resources>

ga_logLevel setting is deprecated. See Logger interface for details.

Public Method Summary

void
dispatchLocalHits()
Dispatches hits queued in the application store (views, events, or transactions) to Google Analytics if a network connection is available.
void
enableAutoActivityReports(Application application)
On devices running API level 14 (ICE_CREAM_SANDWICH) or above, applications can call this method in lieu of making explicit calls to reportActivityStart(Activity) and reportActivityStop(Activity).
boolean
getAppOptOut()
Returns whether the state of the application-level opt is on.
static GoogleAnalytics
getInstance(Context context)
Gets the GoogleAnalytics instance, creating it when necessary.
Logger
getLogger()
This method is deprecated. Logger interface is deprecated. See Logger interface for details.
boolean
isDryRunEnabled()
Returns whether dry run mode is on.
Tracker
newTracker(String trackingId)
Returns a Tracker instance with the given trackingId.
Tracker
newTracker(int configResId)
Returns a Tracker instance preconfigured with the values specified in configResId.
void
reportActivityStart(Activity activity)
Report the start of an Activity, so that it can be tracked by any Trackers that have enabled auto activity tracking (see Tracker.enableAutoActivityTracking(boolean).) This will also start a new session if necessary.
void
reportActivityStop(Activity activity)
Report the end of an Activity.
void
setAppOptOut(boolean optOut)
Sets or resets the application-level opt out flag.
void
setDryRun(boolean dryRun)
Toggles dry run mode.
void
setLocalDispatchPeriod(int dispatchPeriodInSeconds)
Sets dispatch period for the local dispatcher.
void
setLogger(Logger logger)
This method is deprecated. Logger interface is deprecated. See Logger interface for details.

Inherited Method Summary

Public Methods

public void dispatchLocalHits ()

Dispatches hits queued in the application store (views, events, or transactions) to Google Analytics if a network connection is available. This method only works when Google Play service is not available on the device and local dispatching is used. In general, applications should not rely on the ability to dispatch hits manually.

public void enableAutoActivityReports (Application application)

On devices running API level 14 (ICE_CREAM_SANDWICH) or above, applications can call this method in lieu of making explicit calls to reportActivityStart(Activity) and reportActivityStop(Activity). This method is a noop if called on a device running API level less than 14.

Parameters
application The Application whose activities starts and stops should be automatically reported.

public boolean getAppOptOut ()

Returns whether the state of the application-level opt is on.

public static GoogleAnalytics getInstance (Context context)

Gets the GoogleAnalytics instance, creating it when necessary. It is safe to call this method from any thread.

public Logger getLogger ()

This method is deprecated.
Logger interface is deprecated. See Logger interface for details.

Return the current Logger implementation in use. If no Logger has been set, a default Logger is provided that logs to android.util.Log with Logger.LogLevel set to Logger.LogLevel.WARNING.

public boolean isDryRunEnabled ()

Returns whether dry run mode is on.

public Tracker newTracker (String trackingId)

Returns a Tracker instance with the given trackingId. If the given trackingId is not null or empty, it will be set on the tracker and it is ready to send hits. Calling newTracker() multiple times with the same trackingId will create multiple Tracker objects with the same trackingId.

If the trackingId is empty, you can still get a tracker, but you must set the tracking id before sending any hits. This is useful if you do not know the tracking id at the time of tracker creation, or if you want to use the same tracker instance to track multiple tracking ids. Using the same instance to track multiple tracking ids is not recommended since you need to be careful about not mixing the data you are sending to multiple profiles. It can be useful if you have a lot of tracking ids and you want to avoid object creation overhead involved in instantiating one tracker per tracking id.

Parameters
trackingId string of the form UA-xxxx-y

public Tracker newTracker (int configResId)

Returns a Tracker instance preconfigured with the values specified in configResId. Calling newTracker() multiple times with the same trackingId will create multiple Tracker objects with the same configuration.

If the trackingId is empty, you can still get a tracker, but you must set the tracking id before sending any hits. This is useful if you do not know the tracking id at the time of tracker creation, or if you want to use the same tracker instance to track multiple tracking ids. Using the same instance to track multiple tracking ids is not recommended since you need to be careful about not mixing the data you are sending to multiple profiles. It can be useful if you have a lot of tracking ids and you want to avoid object creation overhead involved in instantiating one tracker per tracking id.

Parameters
configResId The resource id of your tracker configuration file. See Tracker for more information about what configuration elements can be included in that file.

public void reportActivityStart (Activity activity)

Report the start of an Activity, so that it can be tracked by any Trackers that have enabled auto activity tracking (see Tracker.enableAutoActivityTracking(boolean).) This will also start a new session if necessary. This method should be called from the Activity.onStart() method in each Activity in your application that you'd like to track.

If auto activity reports are enabled (see enableAutoActivityReports(Application)) on a device running API level 14 or above, this method will be a noop.

Parameters
activity the Activity that is to be tracked.

public void reportActivityStop (Activity activity)

Report the end of an Activity. Note that this method should be called from the Activity.onStop() method in each Activity in your application that you'd like to track. For proper operation, this method must be called in all Activities where reportActivityStart(Activity) is called.

If auto activity reports are enabled (see enableAutoActivityReports(Application)) on a device running API level 14 or above, this method will be a noop.

Parameters
activity the Activity that is to be tracked.

public void setAppOptOut (boolean optOut)

Sets or resets the application-level opt out flag. If set, no hits will be sent to Google Analytics. The value of this flag will not persist across application starts. The correct value should thus be set in application initialization code.

Parameters
optOut true if application-level opt out should be enforced.

public void setDryRun (boolean dryRun)

Toggles dry run mode. In dry run mode, the normal code paths are executed locally, but hits are not sent to Google Analytics servers. This is useful for debugging calls to the Google Analytics SDK without polluting recorded data.

By default, this flag is disabled.

public void setLocalDispatchPeriod (int dispatchPeriodInSeconds)

Sets dispatch period for the local dispatcher. The dispatcher will check for hits to dispatch every dispatchPeriod seconds. If zero or a negative dispatch period is given, automatic dispatch will be disabled, and the application will need to dispatch events manually using dispatchLocalHits().

This method only works if local dispatching is in use. Local dispatching is only used in the absence of Google Play services on the device. In general, applications should not rely on the ability to dispatch hits manually.

Parameters
dispatchPeriodInSeconds the new dispatch period in seconds

public void setLogger (Logger logger)

This method is deprecated.
Logger interface is deprecated. See Logger interface for details.

Return the current Logger implementation in use. If no Logger has been set, a default Logger is provided that logs to android.util.Log with Logger.LogLevel set to Logger.LogLevel.WARNING.

Parameters
logger The Logger implementation to use for logging.