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

利用 iOS 版 Google Analytics(分析)移动应用 SDK,您可以轻松地在基于 iOS 的应用中实现 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 类别标记的事件。如需详细了解事件跟踪,请参阅事件跟踪指南
电子商务跟踪
使用电子商务跟踪功能跟踪购物车交易和应用内购买。 如需跟踪交易,请调用 addTransaction 方法以创建总体交易,以及为购物篮中的每个产品创建 addItem 方法。收集数据后,您可以在 Google Analytics(分析)界面的“电子商务”报告部分中查看这些数据。 如需详细了解电子商务跟踪,请参阅电子商务跟踪指南
自定义变量
自定义变量是指您可以插入跟踪代码中以优化 Google Analytics(分析)跟踪的名称/值对标记。如需详细了解如何使用自定义变量,请参阅自定义变量指南
NoThumb 支持
iPhone 版 SDK 现在附带 NoThumb 版库以及标准 Thumb 版本。如需使用库的 NoThumb 版本,请使用文件 libGoogleAnalytics_NoThumb.a,而不是文件 libGoogleAnalytics.a

开始使用

要求

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

设置

  • 打开 Xcode 并创建新的 iPhone 操作系统项目。
  • GANTracker.hlibGoogleAnalytics.a 从 SDK 的库目录拖动到新项目中。
  • 在您的项目中添加 CFNetwork 框架并关联到 libsqlite3.0.dylib

Google Analytics(分析)移动应用 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

调用 addTransactionaddItem 可将交易或商品添加到内部电子商务缓冲区中,您可以在其中添加更多商品和交易。只有在调用 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(分析)就可以在存储 IP 地址前移除其最后一个八位位组,从而对来自 SDK 的信息进行匿名化处理。

以下示例展示了如何进行设置:

 [[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。您之所以需要这样做,是因为在调用 startTrackerWithAccountID 之前,Google Analytics(分析)使用的 SQLite 数据库尚未设置,而 setReferrer 需要该数据库。如果您尚未调用 startTrackerWithAccountID,则会返回错误。

    第二个限制是,传递到 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