Mobile App Implementation Guide

This document is for mobile developers and describes how to use Google Analytics to measure user interactions and answer questions about app usage.

Introduction

Google Analytics for mobile apps provides a platform to measure user interactions, allowing you to better understand and optimize user engagement with your app.

The default implementation of Google Analytics will automatically provide the following information about your app:

  • the number of users and sessions
  • session duration
  • operating systems
  • device models
  • geography

This guide will explain how you can implement additional Google Analytics features to better understand your users and their behavior.

Before you begin

Before working through this guide, it’s recommended that you review the resources below to learn how to setup Google Analytics for Mobile Apps:

Overview

Dragon Catcher

This guide uses a sample app to walk you through the implementation of additional Google Analytics features. The app is called Dragon Catcher and has the following gameplay characteristics:

  • a level consists of a player, dragons, a fenced area, a well, and trees
  • the player’s objective is to catch dragons by moving them into the fenced area
  • the player can visit different areas of the level and objects like a well or a magic tree
  • the player advances to the next level once they have caught all the dragons
  • the player starts the game on the first level which is named Barren Fields.

Using Google Analytics, some of the questions about user behavior that can be answered about Dragon Catcher:

The rest of this document illustrates how these questions can be answered by implementing Google Analytics features for the Dragon Catcher game.

What actions are my users performing? (Events)

If there are important actions that you want to track within your app then events can be used to describe this action in Google Analytics. An event consists of four parameters: category, action, label and value. For details on how events work in Google Analytics see Anatomy of Event Tracking.

For example, in Dragon Catcher, a user rescuing a dragon or visiting a specific area in the level are important actions that we want to measure using events. The code snippet below illustrates how to measure this in Google Analytics.

Android SDK v4

// To determine how many dragons are being rescued, send an event when the
// player rescues a dragon.
tracker.send(new HitBuilders.EventBuilder()
    .setCategory("Barren Fields")
    .setAction("Rescue")
    .setLabel("Dragon")
    .setValue(1)
    .build());

// To determine if players are visiting the magic tree, send an event when the
// player is in the vicinity of the magic tree.
tracker.send(new HitBuilders.EventBuilder()
    .setCategory("Barren Fields")
    .setAction("Visited")
    .setLabel("Magic Tree")
    .setValue(1)
    .build());

// To determine if players are visiting the well, send an event when the player
// is in the vicinity of the well.
tracker.send(new HitBuilders.EventBuilder()
    .setCategory("Barren Fields")
    .setAction("Visited")
    .setLabel("Well")
    .setValue(1)
    .build());

iOS SDK v3

// To determine how many dragons are being rescued, send an event when the
// player rescues a dragon.
[tracker send:[[GAIDictionaryBuilder createEventWithCategory:@"Barren Fields"
                                                      action:@"Rescue"
                                                       label:@"Dragon"
                                                       value:@1] build]];

// To determine if players are visiting the magic tree, send an event when the
// player is in the vicinity of the magic tree.
[tracker send:[[GAIDictionaryBuilder createEventWithCategory:@"Barren Fields"
                                                      action:@"Visited"
                                                       label:@"Magic Tree"
                                                       value:@1] build]];

// To determine if players are visiting the well, send an event when the player
// is in the vicinity of the well.
[tracker send:[[GAIDictionaryBuilder createEventWithCategory:@"Barren Fields"
                                                      action:@"Visited"
                                                       label:@"Well"
                                                       value:@1] build]];

GA Plugin for Unity v3

// To determine how many dragons are being rescued, send an event when the
// player rescues a dragon.
googleAnalytics.LogEvent("Barren Fields", "Rescue", "Dragon", 1);

// To determine if players are visiting the magic tree, send an event when the
// player is in the vicinity of the magic tree.
googleAnalytics.LogEvent("Barren Fields", "Visited", "Magic Tree", 1);

// To determine if players are visiting the well, send an event when the player
// is in the vicinity of the well.
googleAnalytics.LogEvent("Barren Fields", "Visited", "Well", 1);

Measuring player "achievements"

Player "achievements" can be measured using events in Google Analytics. For example, to measure an achievement of rescuing 5 dragons, the number of dragons a player has rescued is recorded and then once the player has reached the threshold an event is sent to Google Analytics:

Android SDK v4

if (numDragonsRescued > 5) {
  if (!user.hasAchievement(RESCUED_ACHIEVEMENT) {
    tracker.send(new HitBuilders.EventBuilder()
        .setCategory("Achievement")
        .setAction("Unlocked")
        .setLabel("5 Dragons Rescued")
        .setValue(1)
        .build());
  } else {
    tracker.send(new HitBuilders.EventBuilder()
        .setCategory("Achievement")
        .setAction("Earned")
        .setLabel("5 Dragons Rescued")
        .setValue(1)
        .build());
  }
}

iOS SDK v3

if (numDragonsRescued > 5) {
  if (![user hasAchievement:RESCUED_ACHIEVEMENT]) {
    [tracker send:[[GAIDictionaryBuilder createEventWithCategory:@"Achievement"
                                                          action:@"Unlocked"
                                                           label:@"5 Dragons Rescued"
                                                           value:@1] build]];
  } else {
    [tracker send:[[GAIDictionaryBuilder createEventWithCategory:@"Achievement"
                                                          action:@"Earned"
                                                           label:@"5 Dragons Rescued"
                                                           value:@1] build]];
  }
}

GA Plugin for Unity v3

if (numDragonsRescued > 5) {
  if (!user.HasAchievement(RESCUED_ACHIEVEMENT) {
    googleAnalytics.LogEvent("Achievement", "Unlocked", "5 Dragons Rescued", 1);
  } else {
    googleAnalytics.LogEvent("Achievement", "Earned", "5 Dragons Rescued", 1);
  }
}

Developer guides for events

Reporting for events

Event data is available in:

How much money are users spending in my app? (Enhanced Ecommerce)

If you want to measure in-app purchases by users then ecommerce tracking can be used to track the purchase and understand related product performance and user behavior. Ecommerce tracking can be used to measure the purchase of a specific item or a virtual currency.

For example, in Dragon Catcher, to measure the purchase of some items, transaction data is sent to Google Analytics with an event:

Android SDK v4

Product product = new Product()
    .setName("Dragon Food")
    .setPrice(40.00);

ProductAction productAction = new ProductAction(ProductAction.ACTION_PURCHASE)
    .setTransactionId("T12345");

// Add the transaction data to the event.
HitBuilders.EventBuilder builder = new HitBuilders.EventBuilder()
    .setCategory("In-Game Store")
    .setAction("Purchase")
    .addProduct(product)
    .setProductAction(productAction);

// Send the transaction data with the event.
tracker.send(builder.build());

iOS SDK v3

GAIEcommerceProduct *product = [[GAIEcommerceProduct alloc] init];
[product setName:@"Dragon Food"];
[product setPrice:@40.00];

GAIEcommerceProductAction *productAction = [[GAIEcommerceProductAction alloc] init];
[productAction setAction:kGAIPAPurchase];
[productAction setTransactionId:@"T12345"];

GAIDictionaryBuilder *builder = [GAIDictionaryBuilder createEventWithCategory:@"In-Game Store"
                                                                       action:@"Purchase"
                                                                        label:nil
                                                                        value:nil];
// Add the transaction data to the event.
[builder setProductAction:productAction];
[builder addProduct:product];

// Send the transaction data with the event.
[tracker send:[builder build]];

GA Plugin for Unity v3

// Note: Using Android SDK v3 and standard Ecommerce tracking.

googleAnalytics.LogItem("T12345", "Dragon Food", "Food_SKU", "Items", 40.00, 1);
googleAnalytics.LogTransaction("T12345", "In-Game Store", 40.00, 0.00, 0.00);

If a user purchases virtual currency it's recommended that you measure the exchange of real money when sending the transaction data to Google Analytics. When the user spends the virtual currency to purchase items then measure this using events. For example:

Android SDK v4

/**
 * When the user purchases the virtual currency (Gems) measure the transaction
 * using enhanced ecommerce.
 */
Product product =  new Product()
    .setName("2500 Gems")
    .setPrice(5.99);

ProductAction productAction = new ProductAction(ProductAction.ACTION_PURCHASE)
    .setTransactionId("T67890");

// Add the transaction to the screenview.
HitBuilders.ScreenViewBuilder builder = new HitBuilders.ScreenViewBuilder()
    .addProduct(product)
    .setProductAction(productAction);

// Send the transaction with the screenview.
tracker.setScreenName("In-Game Store");
tracker.send(builder.build());


/**
 * When the user purchases an item using the virtual currency (Gems) send an
 * event to measure this in Google Analytics.
 */
HitBuilders.EventBuilder builder = new HitBuilders.EventBuilder()
    .setCategory("In-Game Store")
    .setAction("Purchase")
    .setLabel("Sword")
    .setValue(35);
tracker.send(builder.build());

iOS SDK v3

/**
 * When the user purchases the virtual currency (Gems) measure the transaction
 * using enhanced ecommerce.
 */
GAIEcommerceProduct *product = [[GAIEcommerceProduct alloc] init];
[product setName:@"2500 Gems"];
[product setPrice:@5.99];

GAIEcommerceProductAction *productAction = [[GAIEcommerceProductAction alloc] init];
[productAction setAction:kGAIPAPurchase];
[productAction setTransactionId:@"T67890"];

GAIDictionaryBuilder *builder = [GAIDictionaryBuilder createScreenView];

// Add the transaction data to the screenview.
[builder setProductAction:productAction];
[builder addProduct:product];

// Send the transaction with the screenview.
[tracker set:kGAIScreenName value:@"In-Game Store"]
[tracker send:[builder build]];


/**
 * When the user purchases an item using the virtual currency (Gems) send an
 * event to measure this in Google Analytics.
 */
GAIDictionaryBuilder *builder = [GAIDictionaryBuilder createEventWithCategory:@"In-Game Store"
                                                                       action:@"Purchase"
                                                                        label:@"Sword"
                                                                        value:@35];
[tracker send:[builder build]];

GA Plugin for Unity v3

// Note: Using Android SDK v3 and standard Ecommerce tracking.

/**
 * When the user purchases the virtual currency (Gems) measure the transaction
 * using enhanced ecommerce.
 */

googleAnalytics.LogItem("T12345", "2500 Gems", "GEM2500_SKU", "Items", 5.99, 1);
googleAnalytics.LogTransaction("T12345", "In-Game Store", 5.99, 0.00, 0.00);

/**
 * When the user purchases an item using the virtual currency (Gems) send an
 * event to measure this in Google Analytics.
 */
googleAnalytics.LogEvent("In-Game Store", "Purchase", "Sword", 35);

Developer guides for enhanced ecommerce

Reporting for enhanced ecommerce

Ecommerce data is available in:

Are users completing my app objectives? (Goals)

If you have specific objectives for your app that you want users to complete then you can define and measure these objectives using Goals in Google Analytics. For example, a goal could be for users to reach a certain game level or to purchase an item. To learn more on how goals work see About goals (Help Center).

In the Dragon Catcher game, a goal can be set up to measure when in-app purchases are made if an event is sent to Google Analytics for each purchase. The goal can be defined in the web interface admin, without any additional code, using the following parameters:

  • Goal Type (Equals): Event
  • Category (Equals): In-Game Store
  • Action (Equals): Purchase
  • Use the Event value as the Goal Value for the conversion: Yes

Goal Reporting

Goal data is available in:

How do users with a specific trait behave? (Custom Dimensions & Metrics)

If you want to track users with specific attributes/traits/metadata then custom dimensions can be used to send this type of data to Google Analytics and in analysis. See the Custom Dimensions & Metrics feature reference to learn more about how custom dimensions work.

For example, in Dragon Catcher, to find out the percentage of users that are in the first level, second level, etc. a custom dimension can be set with the user’s current level and sent to Google Analytics. The steps are:

  1. Create a custom dimension with a User scope. User scope is used because this value should persist across all of that user's sessions. See Set up or edit custom dimensions (Help Center).
  2. Update the custom dimension value when the user's level has changed.

The following snippet illustrates how to update the user's state in Google Analytics where the user level custom dimension index is 1 and the user's level has changed to Barren Fields:

Android SDK v4

// Set the user level custom dimension when sending a hit to Google Analytics
// such as a screenview or event.
tracker.setScreen("BarrenFields");
tracker.send(new HitBuilders.ScreenViewBuilder()
    .setCustomDimension(1, "Barren Fields")
    .build()
);

iOS SDK v3

// Set the user level custom dimension when sending a hit to Google Analytics
// such as a screenview or event.
[tracker set:kGAIScreenName value:@"BarrenFields"];
[tracker send:[[[GAIDictionaryBuilder createScreenView]
         set:@"Barren Fields"
      forKey:[GAIFields customDimensionForIndex:1]] build]];

GA Plugin for Unity v3

// Set the user level custom dimension when sending a hit to Google Analytics
// such as a screenview or event.
googleAnalytics.LogScreen(new AppViewHitBuilder()
    .SetScreenName("BarrenFields").SetCustomDimension(1, "Barren Fields"));

Developer guides for Custom Dimensions & Metrics

Reporting for Custom Dimensions & Metrics

Custom dimensions can be included in and applied as a segment to:

Applying the custom dimension as a segment will allow you to analyze users who are currently in a specific level within the game.

How long does it take for a user to accomplish a task? (Custom Timings)

If you want to measure how long something takes to complete in the app then user timings can be used for time based measurements in Google Analytics. User timings are similar to events, but are time based, and can include a category, value, name (variable), and label. To learn about how user timings work see About Site Speed.

For example, in Dragon Catcher to measure how long it takes for a user to rescue their first dragon you can send something like:

Android SDK v4

// Build and send a timing hit.
tracker.send(new HitBuilders.TimingBuilder()
    .setCategory("Barren Fields")
    .setValue(45000)  // 45 seconds.
    .setVariable("First Rescue")
    .setLabel("Dragon")
    .build());

iOS SDK v3

[tracker send:[[GAIDictionaryBuilder createTimingWithCategory:@"Barren Fields"
                                                     interval:@45000   // 45 seconds.
                                                         name:@"First Rescue"
                                                        label:@"Dragon"] build]];

GA Plugin for Unity v3

// Build and send a timing hit.
googleAnalytics.LogTiming("Barren Fields",45000,"First Rescue","Dragon");

Developer guides for custom timings

Reporting for custom timings

Custom timings data is available in:

  • Analytics Academy - Improve your Analytics skills with free online courses including mobile app analytics fundamentals.
  • Collection APIs & SDKs - Learn about all the ways you can send data to Google Analytics