Android 版 Google Analytics(分析)SDK v1(旧版)

借助 Android 版 Google Analytics(分析)移动应用 SDK,您可以轻松地在基于 Android 的应用中加入 Google Analytics(分析)。本文档介绍了如何将 SDK 与您的应用集成。

SDK 概览

此 SDK 使用一种跟踪模型,旨在跟踪用户访问传统网站并与传统网页中的微件互动。因此,以下术语反映了传统的网站跟踪模型,并被映射到跟踪移动应用。您应该熟悉 Google Analytics(分析)跟踪,以便了解此 SDK 的工作原理。

使用移动跟踪 SDK,通过以下 Analytics 互动类型跟踪您的手机应用:

浏览量跟踪
网页浏览是衡量传统网站获得流量的标准方式。由于移动应用不包含 HTML 网页,因此您必须决定何时(以及多久)触发网页浏览请求。此外,由于网页浏览请求旨在报告目录结构,您应为请求提供描述性名称,以充分利用 Google Analytics(分析)内容报告中的网页路径命名。您选择的名称将作为网页路径填充在 Google Analytics(分析)报告中,即使它们实际并不是 HTML 网页,但您可以利用这一点来构造路径,以为调用提供额外的分组方式。
事件跟踪
在 Analytics(分析)中,事件旨在跟踪用户与网页浏览元素的互动情况。您可以使用 Google Analytics(分析)的事件跟踪功能进行其他调用,这些功能将在 Google Analytics(分析)报告界面的“事件跟踪”部分中报告。事件是按类别分组的,也可以使用按事件划分的标签,以便灵活地生成报告。例如,多媒体应用可以针对其 video 类别进行播放/停止/暂停操作,并为每个视频名称分配一个标签。然后,Google Analytics(分析)报告会汇总所有带有 video 类别标记的事件。如需详细了解事件跟踪,请参阅事件跟踪指南
电子商务跟踪
使用电子商务跟踪功能跟踪购物车交易和应用内购买。 如需跟踪交易,请使用 Transaction 类表示总体购买信息,并使用 Item 类表示购物篮中的每件商品。收集数据后,您可以在 Google Analytics(分析)界面的“电子商务”报告部分中查看这些数据。 如需详细了解电子商务跟踪,请参阅电子商务跟踪指南
自定义变量
自定义变量是指您可以插入跟踪代码中以优化 Google Analytics(分析)跟踪的名称/值对标记。如需详细了解如何使用自定义变量,请参阅自定义变量指南

开始使用

要求

要将 Google Analytics(分析)跟踪功能与您的 Android 应用集成,您需要具备:

设置

  • libGoogleAnalytics.jar 添加到项目的 /libs 目录中。
  • 将以下权限添加到项目的 AndroidManifest.xml 清单文件中:
    • <uses-permission android:name="android.permission.INTERNET" />
    • <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

SDK 中提供了一个示例应用,用于演示如果设置成功,您的项目会是什么样子。您可以将其用作您自己的 Google Analytics(分析)集成应用的模板。

使用 SDK

开始使用该 SDK 之前,您必须先在 www.google.com/analytics 上免费创建帐号,并在该帐号中使用虚假但具有描述性的网站网址(例如 http://mymobileapp.mywebsite.com)创建新的网站媒体资源。创建媒体资源后,请记下为新创建的媒体资源生成的网站媒体资源 ID 的副本。

您必须在应用或服务条款中告知用户,您有权匿名跟踪并报告用户在应用中的活动。使用 Google Analytics(分析)SDK 时还需要遵守 Google Analytics(分析)服务条款,您必须在注册帐号时同意接受这些条款。

示例和最佳做法

您可以在 code.google.com 上的 analytics-api-samples 项目下找到示例代码和最佳做法。

EasyTracker 库

有一个 EasyTracker 库。它几乎不需要任何开发工作就可以提供应用和 Activity 级别的跟踪。您可以在 analytics-api-samples 项目的下载部分中找到该代码段。

启动智能设备

通过调用 GoogleAnalyticsTracker.getInstance() 获取跟踪器单例。然后调用其 startNewSession 方法,并传递要跟踪的网络媒体资源 ID 和活动。如果您的应用只有一个 activity,您可以直接在该 activity 的 onCreate 方法中调用此方法。例如:

package com.google.android.apps.analytics.sample;

import com.google.android.apps.analytics.GoogleAnalyticsTracker;

import android.app.Activity;
import android.os.Bundle;
import android.view.View;
import android.view.View.OnClickListener;
import android.widget.Button;

public class TestActivity extends Activity {

  GoogleAnalyticsTracker tracker;

  @Override
  protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);

    tracker = GoogleAnalyticsTracker.getInstance();

    // Start the tracker in manual dispatch mode...
    tracker.startNewSession("UA-YOUR-ACCOUNT-HERE", this);

    // ...alternatively, the tracker can be started with a dispatch interval (in seconds).
    //tracker.startNewSession("UA-YOUR-ACCOUNT-HERE", 20, this);

    setContentView(R.layout.main);
    Button createEventButton = (Button)findViewById(R.id.NewEventButton);
    createEventButton.setOnClickListener(new OnClickListener() {
      @Override
      public void onClick(View v) {
        tracker.trackEvent(
            "Clicks",  // Category
            "Button",  // Action
            "clicked", // Label
            77);       // Value
      }
    });

    Button createPageButton = (Button)findViewById(R.id.NewPageButton);
    createPageButton.setOnClickListener(new OnClickListener() {
      @Override
      public void onClick(View v) {
        // Add a Custom Variable to this pageview, with name of "Medium" and value "MobileApp" and
        // scope of session-level.
        tracker.setCustomVar(1, "Navigation Type", "Button click", 2);
        // Track a page view. This is probably the best way to track which parts of your application
        // are being used.
        // E.g.
        // tracker.trackPageView("/help"); to track someone looking at the help screen.
        // tracker.trackPageView("/level2"); to track someone reaching level 2 in a game.
        // tracker.trackPageView("/uploadScreen"); to track someone using an upload screen.
        tracker.trackPageView("/testApplicationHomeScreen");
      }
    });

    Button quitButton = (Button)findViewById(R.id.QuitButton);
    quitButton.setOnClickListener(new OnClickListener() {
      @Override
      public void onClick(View v) {
        finish();
      }
    });

    Button dispatchButton = (Button)findViewById(R.id.DispatchButton);
    dispatchButton.setOnClickListener(new OnClickListener() {
      @Override
      public void onClick(View v) {
        // Manually start a dispatch, not needed if the tracker was started with a dispatch
        // interval.
        tracker.dispatch();
      }
    });
  }

  @Override
  protected void onDestroy() {
    super.onDestroy();
    // Stop the tracker when it is no longer needed.
    tracker.stopSession();
  }
}

如果您的应用中有多个 activity,您可以使用 analytics-api-samples 项目的 Downloads 部分提供的 EasyTracker 库。

跟踪网页浏览和事件

跟踪网页浏览和事件非常简单:只需在每次想要触发网页浏览时调用跟踪器对象的 trackPageView。调用 trackEvent 即可录制事件。如需详细了解网页浏览和事件,请参阅上文中的 SDK 概览

使用自定义变量

添加自定义变量也很简单:只需使用移动 SDK 提供的 setCustomVar 方法即可。您需要提前规划以将每个自定义变量映射到的哪个索引,因此不会覆盖任何之前存在的变量。如需详细了解自定义变量,请参阅自定义变量指南。请注意,setCustomVar 方法并不会直接发送数据。而是通过跟踪到的下一个网页浏览或事件发送数据。您必须在跟踪网页浏览或事件之前调用 setCustomVar请注意,自定义变量的默认范围为页面级范围。

使用电子商务跟踪

您可以通过以下 4 种方式在应用中启用电子商务跟踪:

  • addTransaction
  • addItem
  • trackTransactions
  • clearTransactions

调用 addTransactionaddItem 可将交易或商品添加到内部电子商务缓冲区中,您可以在其中添加更多商品和交易。只有在调用 trackTransactions 时,事务和项才会发送到调度程序,并且排队等待发送到 Google Analytics(分析)。

如需清除缓冲区,您可以调用 clearTransactions 方法。注意:它不会找回之前发送给调度员的任何交易或 Google Analytics(分析)已收集的任何交易。

以下示例代码可以帮助您上手。我们假定系统在确认或拒绝购买交易时调用 onPurchaseCompleted 方法。

  /**
   * The purchase was processed.  We will track the transaction and its associated line items
   * now, but only if the purchase has been confirmed.
   *
   * @param purchase A PurchaseObject containing all of the transaction information needed to
   *     send the ecommerce hit to Google Analytics.
   */
  public void onPurchaseCompleted(PurchaseObject purchase) {
    tracker.addTransaction(new Transaction.Builder(
        purchase.getTransactionId(),
        purchase.getTotal())
        .setStoreName(purchase.getStoreName())
        .setTotalTax(purchase.getTotalTax())
        .setShippingCost(purchase.getShippingCost())
        .build());
    for (PurchaseLineItem lineItem : purchase.getLineItems()) {
        tracker.addItem(new Item.Builder(
            purchase.getTransactionId(),
            lineItem.getItemSKU(),
            lineItem.getItemCost(),
            lineItem.getQuantity())
            .setItemName(lineItem.getItemName())
            .setItemCategory(lineItem.getItemCategory())
            .build());
    }
    if (purchase.isConfirmed()) {
      tracker.trackTransactions();
    } else {
      // The purchase was denied or failed in some way.  We need to clear out
      // any data we've already put in the Ecommerce buffer.
      tracker.clearTransactions();
    }
  }

如需详细了解电子商务,请参阅电子商务跟踪指南

对 IP 地址进行匿名处理

如需对用户 IP 信息进行匿名化处理,请使用 setAnonymizeIp 方法。 这样一来,Google Analytics(分析)就可以在存储 IP 地址前移除其最后一个八位位组,从而对来自 SDK 的信息进行匿名化处理。

你可以随时调用 setAnonymizeIp

设置采样率

您可以使用方法 setSampleRate 设置采样率。 如果您的应用产生了大量 Google Analytics(分析)流量,则设置采样率可能会阻止系统使用抽样数据生成报告。抽样在各个唯一身份用户之间一致进行,因此在启用采样率的情况下,趋势和报告会保持完整性。 setSampleRate 方法接受一个 int 参数。该参数的有效值是 0 到 100 之间的任何整数(含 0 和 100)。

比率为 0 表示关闭命中生成,比率为 100 表示将数据发送到 Google Analytics(分析)。 最好在调用任何跟踪方法之前先调用 setSampleRate

如需详细了解抽样,请参阅抽样概念指南

批量命中

为了节省连接和电池电量开销,我们建议您批量处理跟踪请求。如果您希望发出批量请求,可以随时对跟踪对象调用 dispatch,此操作可以手动执行,也可以按特定的时间间隔执行。

已知问题

  • 在不同线程上调用 GoogleAnalyticsTracker 方法可能会导致隐藏错误。请务必在同一线程中进行所有调用。
  • 跟踪广告系列

    SDK 支持两种类型的广告系列跟踪。

    - Google Play 广告系列跟踪 - 可让您通过 Google Play 跟踪安装引荐流量。
    - 常规广告系列跟踪 – 可让您跟踪将用户引荐到您应用的任何广告系列。

    Google Play 广告系列跟踪

    Android 1.6 OS 版本支持在指向 Google Play 的下载链接中使用 referrer 网址参数。Android 版 Google Analytics(分析)SDK 使用此参数在 Google Analytics(分析)中为您的应用自动填充广告系列信息。这样可以记录应用安装的来源,并将其与未来的网页浏览和事件相关联,例如,这对于衡量应用的特定广告效果很有用。

    为了使引荐跟踪正常工作,您必须将以下代码段添加到项目的 AndroidManifest.xml 清单文件中:

    <!-- Used for install referrer tracking -->
    <receiver android:name="com.google.android.apps.analytics.AnalyticsReceiver" android:exported="true">
      <intent-filter>
        <action android:name="com.android.vending.INSTALL_REFERRER" />
      </intent-filter>
    </receiver>
    

    要通过 Google Play 设置 Google Analytics(分析)广告系列跟踪,请使用下面的网址构建工具生成引荐链接。使用该链接将用户引荐到您的应用程序。Google Analytics(分析)SDK 将自动解析和记录引荐信息,并填入 Google Analytics(分析)报告中。

    要生成引荐链接,您可以使用 Google Play 广告系列网址构建工具。必须提供软件包名称广告系列来源广告系列媒介广告系列名称。如需详细了解每个参数,请参阅下文中的表格

    常规广告系列跟踪

    借助 Android 版 Google Analytics(分析)SDK 1.3 版,您现在可以跟踪 Google Play 以外的其他来源的广告系列。 例如,如果您想知道应用是通过广告中的某个链接启动的,您可以在导致应用启动的 intent 中检查广告系列引荐信息,然后将该广告系列信息存储在 Google Analytics(分析)中。

    如需设置广告系列引荐信息,请使用 setReferrer 方法,如下所示:

      tracker.setReferrer(referrer);
    

    使用此功能有两个限制。首先,您必须先调用 startNewSession,然后再调用 setReferrer。您之所以需要这样做,是因为在调用 startNewSession 之前,Google Analytics(分析)使用的 SQLite 数据库尚未设置,而 setReferrer 需要该数据库。如果您尚未调用 startNewSession,则会收到 IllegalStateException

    第二个限制是,传递到 setReferrer 的引荐字符串必须遵循特定的格式。它必须采用一组网址参数的形式,并且必须至少包含 GCLID 参数或 utm_campaign、utm_medium 和 utm_source 中的一项。在后一种情况下,它也可以包含 utm_term 和 utm_content 参数。

    GCLID 参数是自动标记功能的一部分,可自动将 Google Analytics(分析)与 Google Ads 相关联。使用自动标记功能的广告系列引荐示例可能如下所示:

    referrer = “gclid=gclidValue”;
    

    人工广告系列引荐字符串可能如下所示:

    referrer = “utm_campaign=campaign&utm_source=source&utm_medium=medium&utm_term=term&utm_content=content”;
    

    如果您将格式错误的引荐来源网址字符串传递给 setReferrer,则系统不会更改引荐来源网址信息,而且您会获得返回值 false。返回值为 true 表示引荐来源已更新,并会添加到后续的每个命中中。

    另请注意,当您调用 setReferrer 且返回 true 时,系统会启动新会话。

    参数 必需 说明 示例
    utm_campaign 广告系列名称,用于关键字分析,以标识具体的产品推广活动或战略广告系列。 utm_campaign=spring_sale
    utm_source 广告系列来源,用来确定具体的搜索引擎、简报或其他来源。 utm_source=google
    utm_medium 广告系列媒介,用来确定电子邮件或按点击付费广告(CPC)等媒介。 utm_medium=cpc
    utm_term 广告系列字词,用于付费搜索,为广告提供关键字 utm_term=running+shoes
    utm_content 广告系列内容,用于A/B测试和内容定位广告,以识别指向相同网址的不同广告或链接。 utm_content=logolink
    utm_content=textlink