iOS 版 Google Analytics（分析）SDK v1（旧版）

适用于 iOS 的 Google Analytics（分析）移动应用 SDK 可让您在基于 iOS 的应用中轻松实施 Google Analytics（分析）。本文档介绍了如何将 SDK 与您的应用集成。

SDK 概览

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

通过以下 Google Analytics（分析）互动类型，使用移动跟踪 SDK 跟踪手机应用：

浏览量跟踪
网页浏览是衡量传统网站流量的标准方式。由于移动应用不包含 HTML 网页，因此您必须决定何时（以及多久触发一次）网页浏览请求。此外，由于网页浏览请求旨在报告目录结构，因此您应为请求提供描述性名称，以便充分利用 Google Analytics（分析）内容报告中的网页路径命名。即使您选择的名称实际上不是 HTML 网页，也会作为网页路径填充到您的 Google Analytics（分析）报告中，但您可以通过结构化路径来为您的调用提供其他分组方式，从而充分利用这些名称。
事件跟踪
在 Google Analytics（分析）中，事件用于跟踪用户与网页元素的互动，这与网页浏览请求不同。您可以使用 Google Analytics（分析）的事件跟踪功能来进行其他调用，这些调用将在 Google Analytics（分析）报告界面的“事件跟踪”部分中报告。系统按类别对事件进行分组，也可以按事件使用标签，这使得报告更加灵活。例如，多媒体应用的视频类别可以具有播放/停止/暂停操作，并为每个视频名称分配一个标签。然后，Google Analytics（分析）报告会汇总所有标记为 video 类别的事件的事件。如需详细了解事件跟踪，请参阅事件跟踪指南
电子商务跟踪
使用电子商务跟踪功能，您可以跟踪购物车交易和应用内购买情况。 要跟踪某笔交易，请调用 addTransaction 方法以创建一整笔交易，并为购物篮中的每个产品创建 addItem 方法。 收集到的数据后，即可在 Google Analytics（分析）界面的“电子商务报告”部分进行查看。有关电子商务跟踪的更多信息，请参阅电子商务跟踪指南。
自定义变量
自定义变量是您可以插入到跟踪代码中以便优化 Google Analytics（分析）跟踪的名称值对标记。如需详细了解如何使用自定义变量，请参阅自定义变量指南。
NoThumb 支持
适用于 iPhone 的 SDK 现在附带 NoThumb 版本的库以及标准 Thumb 版本。如需使用该库的 NoThumb 版本，请使用文件 libGoogleAnalytics_NoThumb.a，而非文件 libGoogleAnalytics.a。

使用入门

要求

要将 Google Analytics（分析）的跟踪功能与您的 iOS 应用集成，您需要：

初始设置

  • 打开 Xcode 并创建新的 iPhone OS 项目。
  • 将 GANTracker.h 和 libGoogleAnalytics.a 从 SDK 的 Library 目录拖动到新项目中。
  • 在您的项目中添加 CFNetwork 框架并链接到 libsqlite3.0.dylib。

Google Analytics for Mobile Apps SDK 可与任何运行 iOS 2.0 或更高版本的 iPhone 或 iPod Touch 一起使用，该库兼容支持原生应用程序的所有 iOS 版本。

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 库。它提供应用和 UIViewController 级跟踪，几乎无需进行开发工作。您可以在 analytics-api-samples 项目的下载部分中找到该部分。

启动智能设备

通过对通过 [GANTracker sharedTracker] 获得的跟踪器单例调用 startTrackerWithAccountID 方法来启动跟踪器。在应用委托的 applicationDidFinishLaunching 方法中，直接调用此方法通常很方便。传递网络媒体资源 ID、所需的调度周期和可选的委托。例如：

#import "BasicExampleAppDelegate.h"

#import "GANTracker.h"

// Dispatch period in seconds
static const NSInteger kGANDispatchPeriodSec = 10;

@implementation BasicExampleAppDelegate

@synthesize window = window_;

- (void)applicationDidFinishLaunching:(UIApplication *)application {
  // **************************************************************************
  // PLEASE REPLACE WITH YOUR ACCOUNT DETAILS.
  // **************************************************************************
  [[GANTracker sharedTracker] startTrackerWithAccountID:@"UA-0000000-1"
                                        dispatchPeriod:kGANDispatchPeriodSec
                                              delegate:nil];

  NSError *error;
  if (![[GANTracker sharedTracker] setCustomVariableAtIndex:1
                                                       name:@"iPhone1"
                                                      value:@"iv1"
                                                  withError:&error]) {
    // Handle error here
  }

  if (![[GANTracker sharedTracker] trackEvent:@"my_category"
                                       action:@"my_action"
                                        label:@"my_label"
                                        value:-1
                                   withError:&error]) {
    // Handle error here
  }

  if (![[GANTracker sharedTracker] trackPageview:@"/app_entry_point"
                                   withError:&error]) {
    // Handle error here
  }

  [window_ makeKeyAndVisible];
}

- (void)dealloc {
  [[GANTracker sharedTracker] stopTracker];
  [window_ release];
  [super dealloc];
}

@end

跟踪网页浏览和事件

跟踪网页浏览和事件非常简单：每当您希望触发网页浏览时，只需调用跟踪器对象的 trackPageView 即可。调用 trackEvent 以录制事件。如需详细了解网页浏览和事件，请参阅上文中的 SDK 概览。

使用自定义变量

添加自定义变量也很简单：使用移动 SDK 提供的 setCustomVariableAtIndex 方法即可。您需要提前规划每个自定义变量对应的索引，这样就不会覆盖任何先前存在的变量。有关自定义变量的更多信息，请参阅自定义变量指南。请注意，setCustomVariableAtIndex 方法本身不会直接发送数据，而是会随下一个跟踪的网页浏览或事件一起发送数据。您必须在跟踪网页浏览或事件之前调用 setCustomVariableAtIndex。请注意，自定义变量的默认范围为网页级范围。

使用电子商务跟踪

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

  • addTransaction
  • addItem
  • trackTransactions
  • clearTransactions

调用 addTransaction 和 addItem 会将交易或商品添加到内部电子商务缓冲区，然后您可以向该缓冲区添加更多商品和交易。只有在调用 trackTransactions 时，交易和商品才会发送到调度程序，并排队等待发送到 Google Analytics（分析）。

如需清空缓冲区，您可以调用 clearTransactions 方法。注意：它不会调用之前发送给调度程序的任何交易，也不会找回 Google Analytics（分析）已收集的任何交易。

以下示例代码可帮助您上手。 

  /**
   * The purchase was processed.  We will track the transaction and its associated line items
   * now, but only if the purchase has been confirmed.
   */
- (void) processPurchase:Purchase purchase {
  [[GANTracker sharedTracker] addTransaction:[purchase transactionId]
                                  totalPrice:[purchase totalPrice]
                                   storeName:[purchase store]
                                    totalTax:[purchase tax]
                                shippingCost:[purchase shipping]
                                   withError:&error];
  if (error) {
    // Handle error
  }
  for (PurchaseItem item in [purchase items]) {
    [[GANTracker sharedTracker] addItem:[purchase transactionId]
                                itemSKU:[item itemSKU]
                              itemPrice:[item price]
                              itemCount:[item count]
                           itemCategory:[item category]
                              withError:&error];
    if (error) {
      // Handle error
    }
  }

  if ([purchase isConfirmed]) {
    [[GANTracker sharedTracker] trackTransactions:&error];
  } 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.
    [[GANTracker sharedTracker] clearTransactions:&error];
  }
}

有关电子商务的更多信息，请参阅电子商务跟踪指南。

对 IP 地址进行匿名处理

如需将用户 IP 信息匿名化，请将属性 anonymizeIp 设为“是”。 这会告知 Google Analytics（分析）匿名化 SDK 发送的信息，即在存储前移除 IP 地址的最后一个八位位组。

以下示例说明了如何设置此参数：

 [[GANTracker sharedTracker] setAnonymizeIp:YES];

您可以随时设置 anonymizeIp。

设置采样率

您可以使用 sampleRate 属性设置采样率。 如果您的应用生成大量 Google Analytics（分析）流量，设置采样率可能会导致系统无法使用抽样数据生成报告。对唯一身份用户进行抽样时会保持一致，因此在启用采样率后，趋势和报告能够保持完整性。 sampleRate 参数是一个 NSUInteger，其值可以介于 0 到 100（含 0 和 100）之间。以下示例将 sampleRate 设为 95%：

 [[GANTracker sharedTracker] setSampleRate:95];

如果该指定速率为 0，则会关闭命中生成功能；如果指定速率为 100，则会将所有数据发送到 Google Analytics（分析）。 最好在调用任何跟踪方法之前先设置 sampleRate。

您可以参阅抽样概念指南，详细了解抽样。

批处理命中

为了节省网络连接和电池开销，我们建议您批量处理您的跟踪请求。您可以随时针对跟踪对象调用 dispatch 来发出批量请求，并且可以手动进行，也可以按特定的时间间隔执行此操作。

已知问题

  • 引荐/流量来源：目前无法在 iOS 设备上跟踪应用下载的广告系列/引荐来源。
  • 我们强烈建议您不要在以下情况下调用 dispatch：
    • 在 applicationWillTerminate 方法中
    • 在 applicationDidEnterBackground 中，
    • 调用 stopTracker 之前
    这样做可能会导致命中发送两次。请改用 dispatchSynchronous: 方法。
  • 在不同线程上调用 GANTracker 方法可能会导致模糊的 SQLite 错误。请确保在同一线程中进行所有调用。

    • 跟踪广告系列

    常规广告系列跟踪

    借助 iOS 版 Google Analytics（分析）SDK 1.3 版，您现在可以跟踪广告系列引荐。 例如，如果您的应用实现了自定义网址方案，那么您可以创建一个包含广告系列查询参数的网址。当您的应用启动响应此类网址时，您可以检索查询参数并将其传递给 setReferrer，以便将信息存储在 Google Analytics（分析）中。

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

      [[GANTracker sharedTracker] setReferrer:referrer withError:&error];

    使用此功能需要遵守以下两项限制。首先，您必须先调用 startTrackerWithAccountID，然后才能调用 setReferrer。您需要这样做，因为 Google Analytics（分析）使用的 SQLite 数据库不是在调用 startTrackerWithAccountID 之前设置的，而 setReferrer 需要该数据库。如果您尚未调用 startTrackerWithAccountID，则会收到返回错误。

    第二个限制是，传递到 setReferrer 的引荐字符串需要遵循特定的格式。该参数必须采用一组网址参数的形式，并且必须包含至少 1 个 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