Important: This document describes a legacy version of the plugin. New users should use the latest plugin.

Google Analytics Plugin for Unity - API Reference

This document describes how to send data and lists all of the methods for the Google Analytics Plugin for Unity.

Introduction

When sending data to Google Analytics using the GA Plugin for Unity you can use the Basic method or the Builder method. Builder methods are required if you want to append campaign parameters or custom dimensions or metrics to hits. Hits can be sent using either method interchangeably.

Follow the Developer's Guide to setup and configure the Google Analytics Plugin for Unity for your project.

General

Dispatch Hits

Dispatches hits (view, events, etc.) to Google Analytics if a network connection is available.

public void DispatchHits();

Related resources:

Session Control

A session represents a single period of user interaction with your game. Sessions serve as useful containers of measured activity, which includes screen views, events, and ecommerce transactions.

The following methods can be used to force a session start or end.

// Start a new session.
public void StartSession();
// There should be no need to end a session explicitly. However, if you do
// need to indicate the end of session you can use the following method.
public void StopSession();

Related resources:

Screens

Screens in Google Analytics represent content users are viewing within your game. A screen view consists of a single string field that will be used as the screen name in your Google Analytics reports.

Basic

public void LogScreen(string title);

Builder

public void LogScreen(AppViewHitBuilder builder);

Example

googleAnalytics.LogScreen("Main Menu");

//Builder Hit with all App View parameters (all parameters required):
googleAnalytics.LogScreen(new AppViewHitBuilder()
    .SetScreenName("Main Menu"));

Related resources:

Events

Events are a useful way to collect data about a user's interaction with interactive components of your game, like the use of a particular item. An event consists of four fields that you can use to describe a user's interaction with your game.

Basic

public void LogEvent(string eventCategory,
    string eventAction,
    string eventLabel,
    long value);

Builder

public void LogEvent(EventHitBuilder builder);

Example

googleAnalytics.LogEvent("Achievement", "Unlocked", "Slay 10 dragons", 5);

// Builder Hit with all Event parameters.
googleAnalytics.LogEvent(new EventHitBuilder()
    .SetEventCategory("Achievement")
    .SetEventAction("Unlocked")
    .SetEventLabel("Slay 10 dragons")
    .SetEventValue(5));

// Builder Hit with minimum required Event parameters.
googleAnalytics.LogEvent(new EventHitBuilder()
    .SetEventCategory("Achievement")
    .SetEventAction("Unlocked"));

Related resources:

Crashes & Exceptions

Crash and exception measurement allows you to measure the number and type of caught and uncaught crashes and exceptions that occur in your game.

Basic

public void LogException(string exceptionDescription, bool isFatal);

Builder

public void LogException(ExceptionHitBuilder builder);

Example

googleAnalytics.LogException("Incorrect input exception", true);

// Builder Hit with all Exception parameters.
googleAnalytics.LogException(new ExceptionHitBuilder()
    .SetExceptionDescription("Incorrect input exception")
    .SetFatal(true));

// Builder Hit with minimum required Exception parameters.
googleAnalytics.LogException(new ExceptionHitBuilder());

Related resources:

User Timings

Measuring user timings provides a native way to measure a period of time in Google Analytics. For example, this can be useful to measure resource load times.

Basic

public void LogTiming(string timingCategory,
    long timingInterval,
    string timingName,
    string timingLabel);

Builder

public void LogTiming(TimingHitBuilder builder);

Example

googleAnalytics.LogTiming("Loading", 50L, "Main Menu", "First Load");

// Builder Hit with all Timing parameters.
googleAnalytics.LogTiming(new TimingHitBuilder()
    .SetTimingCategory("Loading")
    .SetTimingInterval(50L)
    .SetTimingName("Main Menu")
    .SetTimingLabel("First load"));

// Builder Hit with minimum required Timing parameters.
googleAnalytics.LogTiming(new TimingHitBuilder()
    .SetTimingCategory("Loading")
    .SetTimingInterval(50L));

Related resources:

Social Interactions

Social interaction measurement allows you to measure a user's interactions with various social network sharing and recommendation widgets embedded in your content.

Basic

public void LogSocial(string socialNetwork,
    string socialAction,
    string socialTarget);

Builder

public void LogSocial(SocialHitBuilder builder);

Example

googleAnalytics.LogSocial("twitter", "retweet", "twitter.com/googleanalytics/status/482210840234295296");

// Builder Hit with all Social parameters.
googleAnalytics.LogSocial(new SocialHitBuilder()
    .SetSocialNetwork("Twitter")
    .SetSocialAction("Retweet")
    .SetSocialTarget("twitter.com/googleanalytics/status/482210840234295296"));

// Builder Hit with minimum required Social parameters.
googleAnalytics.LogSocial(new SocialHitBuilder()
    .SetSocialNetwork("Twitter")
    .SetSocialAction("Retweet"));

Related resources:

E-Commerce

Ecommerce measurement allows you to send in-game purchases and sales to Google Analytics. Ecommerce data in Google Analytics is comprised of transaction and item hits, related by a shared transacation ID.

Transactions

Basic

public void LogTransaction(string transID,
    string affiliation,
    double revenue,
    double tax,
    double shipping);

public void LogTransaction(string transID,
    string affiliation,
    double revenue,
    double tax,
    double shipping,
    string currencyCode);

Builder

public void LogTransaction(TransactionHitBuilder builder);

Example

googleAnalytics.LogTransaction("TRANS001", "Coin Store", 3.0, 0.0, 0.0);
googleAnalytics.LogTransaction("TRANS001", "Coin Store", 3.0, 0.0, 0.0, "USD");

// Builder Hit with all Transaction parameters.
googleAnalytics.LogTransaction(new TransactionHitBuilder()
    .SetTransactionID("TRANS001")
    .SetAffiliation("Coin Store")
    .SetRevenue(3.0)
    .SetTax(0)
    .SetShipping(0.0)
    .SetCurrencyCode("USD"));

// Builder Hit with minimum required Transaction parameters.
googleAnalytics.LogTransaction(new TransactionHitBuilder()
    .SetTransactionID("TRANS001")
    .SetAffiliation("Coin Store")
    .SetRevenue(3.0)
    .SetTax(0)
    .SetShipping(0.0));

Items

Basic

public void LogItem(string transID,
    string name,
    string SKU,
    string category,
    double price,
    long quantity);

public void LogItem(string transID,
    string name,
    string SKU,
    string category,
    double price,
    long quantity,
    string currencyCode);

Builder

public void LogItem(ItemHitBuilder builder);

Example

googleAnalytics.LogItem("TRANS001", "Sword", "SWORD1223", "Weapon", 3.0, 2);
googleAnalytics.LogItem("TRANS001", "Sword", "SWORD1223", "Weapon", 3.0, 2, "USD");

// Builder Hit with all Item parameters.
googleAnalytics.LogItem(new ItemHitBuilder()
    .SetTransactionID("TRANS001")
    .SetName("Sword")
    .SetSKU("SWORD1223")
    .SetCategory("Weapon")
    .SetPrice(3.0)
    .SetQuantity(2)
    .SetCurrencyCode("USD"));

// Builder Hit with minimum required Item parameters.
googleAnalytics.LogItem(new ItemHitBuilder()
    .SetTransactionID("TRANS001")
    .SetName("Sword")
    .SetSKU("SWORD1223")
    .SetPrice(3.0)
    .SetQuantity(2));

Related resources:

Custom Dimensions & Metrics

Custom dimensions enable the association of metadata with hits, users, and sessions in Google Analytics, while custom metrics enable you to create and increment your own metrics in Google Analytics.

You must create and configure Custom Dimensions and Custom Metrics before using them. Once configured, data can be sent as part of any hit by using the Builder method.

Builder

// Custom Dimension.
public T SetCustomDimension(int dimensionNumber, string value);
// Custom Metric.
public T SetCustomMetric(int metricNumber, string value);

Example

// Custom Dimension.
// An AppView hit example, but custom dimensions can be sent with all hit types.
googleAnalytics.LogScreen(new AppViewHitBuilder()
    .SetScreenName("Another screen")
    .SetCustomDimension(1, "200"));

// Custom Metric.
// An Event hit example, but custom metrics can be sent with all hit types.
googleAnalytics.LogEvent(new EventHitBuilder()
    .SetEventCategory("Achievement")
    .SetEventAction("Unlocked")
    .SetEventLabel("Slay 10 dragons")
    .SetEventValue(5)
    .SetCustomMetric(3, "200"));

Related resources:

Campaigns

Measuring campaigns in Google Analytics enables the attribution of campaigns and traffic sources to user activity within your game.

Campaign parameters can be sent as part of any hit by using the Builder method.

Builder

public T SetCampaignName(string campaignName);
public T SetCampaignSource(string campaignSource);
public T SetCampaignMedium(string campaignMedium);
public T SetCampaignKeyword(string campaignKeyword);
public T SetCampaignContent(string campaignContent);
public T SetCampaignID(string campaignID);

Example

googleAnalytics.LogTiming(new TimingHitBuilder()
    .SetTimingCategory("Loading")
    .SetTimingInterval(50L)
    .SetTimingName("Main Menu")
    .SetTimingLabel("First load")
    .SetCampaignName("Summer Campaign")
    .SetCampaignSource("google")
    .SetCampaignMedium("cpc")
    .SetCampaignKeyword("games")
    .SetCampaignContent("Free power ups")
    .SetCampaignId("Summer1"));

// Send campaign parameters with timing hit.
// Builder Hit with minimum required Campaign parameters.
googleAnalytics.LogTiming(new TimingHitBuilder()
    .SetTimingCategory("Loading")
    .SetTimingInterval(50L)
    .SetTimingName("Main Menu")
    .SetTimingLabel("First load")
    .SetCampaignSource("google");

Related resources:

Advanced

These methods are recommended only for power users of Google Analytics that are familiar with tracker concepts.

SetOnTracker

Set values on the tracker to be sent with other hits.

Use variables from Assets/Plugins/Fields.cs for the fieldName parameter (e.g. Fields.SCREEN_NAME).

public void SetOnTracker(Field fieldName, object value);

Example

googleAnalytics.SetOnTracker(Fields.SCREEN_NAME, "Main Menu");

Dispose

Free up managed resources and reset the tracker.

If dispose is called the next tracking hit will have to create a new tracker so it is recommended to only call this method when completely finished with tracking. For example, in an onDispose() method which executes when the user quits your game.

public void Dispose();

Example

googleAnalytics.Dispose();