iOS 版 Google Analytics(分析)SDK - 迁移到 v3

本指南将介绍如何升级到 iOS 版 Google Analytics(分析)SDK V3。

概览:V3 的新变化

V3 中的 API 经过了重构,在本机平台和网络平台中更加一致。V2 用户应当注意以下变化:

  • 匹配的发送现在只使用send:(NSDictionary *)params方法。
  • 自动客户端会话管理功能已被移除。您现在可以在管理界面中配置会话超时。了解详情
  • 调试模式被 Logger 所取代。
  • 新功能:您可以添加 dryRun 标志,避免所发送的数据出现在报告中。
  • 新功能:iOS 版现在支持局部货币。

如需完整的变更列表,请参阅变更日志

开始之前

在开始升级到 v3 之前,您需要有:

升级路径

要开始升级,请选择从您当前的实现方案到 v3 的升级路径:

v1.x 到 v3

我们建议 Google Analytics(分析)iOS SDK v1.x 用户按照 v3 使用入门指南的说明开始使用 v3。

v2.x 到 v3

v2.x 用户应当遵循以下步骤来升级到 v3:

  1. 使用新的 send:方法替换所有的 send<hit-type> 便捷方法。
    // v2 (Old)
    id<GAITracker> tracker = [[GAI sharedInstance] defaultTracker];
    [tracker sendView:@"HomeScreen"];
    
    // v3
    id<GAITracker> tracker = [[GAI sharedInstance] defaultTracker];
    // Set the screen name on the tracker so that it is used in all hits sent from this screen.
    [tracker set:kGAIScreenName value:@"Home Screen"];
    
    // Send a screenview.
    // [tracker send:[[GAIDictionaryBuilder createAppView]  build]];   // Previous V3 SDK versions.
    [tracker send:[[GAIDictionaryBuilder createScreenView]  build]];   // SDK Version 3.08 and up.
    
  2. 自动客户端会话管理功能在 v3 中已被移除。现在,会话超时时长可以在管理界面中进行设置,默认值为 30 分钟。您还可以使用 sessionControl 参数来手动开始或结束会话。详细了解 v3 中的会话管理。

  3. 自动屏幕跟踪功能的用户应当将对 GAITrackedViewController.trackedViewName 的引用替换为 GAITrackedViewController.screenName
    // v2 (Old)
    #import "GAITrackedViewController.h"
    
    @implementation AboutViewController
    
    - (void)viewDidAppear:(BOOL)animated {
      [super viewDidAppear:animated];
      self.trackedViewName = @"About Screen";
    }
    
    // ... Rest of ViewController implementation.
    
    // v3
    #import "GAITrackedViewController.h"
    
    @implementation AboutViewController
    
    - (void)viewDidAppear:(BOOL)animated {
      [super viewDidAppear:animated];
      self.screenName = @"About Screen";
    }
    
    // ... Rest of ViewController implementation.
    
  4. 调试模式已被弃用 -- 请改为使用 Logger
    // v2 (Old)
    [GAI sharedInstance].debug = YES;
    
    // v3
    [[GAI sharedInstance].logger setLogLevel:kGAILogLevelVerbose];
    
  5. GAI.useHttp 属性已被移除 -- 要使用 HTTP 而非默认的 HTTPS 来发送匹配,请在每个 GAITracker 中设置 kGAIUseSecure 参数:
    // v2 (Old)
    // AppDelegate.m
    
    #import AppDelegate.h
    #import GAI.h
    
    - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    
        static NSString const *kGaPropertyId = @"UA-XXXX-Y";
        id tracker = [[GAI sharedInstance] trackerWithTrackingId:kGaPropertyId];
    
        // Send hits using HTTP (default=HTTPS).
        tracker.useHttps = NO;
    
    }
    
    // v3
    // AppDelegate.m
    
    #import AppDelegate.h
    #import GAI.h
    
    - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    
        static NSString const *kGaPropertyId = @"UA-XXXX-Y";
        id tracker = [[GAI sharedInstance] trackerWithTrackingId:kGaPropertyId];
    
        // Send hits using HTTP (default=HTTPS).
        [tracker set:kGAIUseSecure value:[@NO stringValue]];
    
    }
    
  6. v3 SDK 不会在应用启动时自动开始一个新会话。如果想要继续使用 v2 的行为模式,您需要自行实现用户启动应用时的会话控制逻辑:
  7. // AppDelegate.m
    
    #import AppDelegate.h
    #import GAI.h
    
    - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    
        static NSString const *kGaPropertyId = @"UA-XXXX-Y";
        id tracker = [[GAI sharedInstance] trackerWithTrackingId:kGaPropertyId];
    
        // CAUTION: Setting session control directly on the tracker persists the
        // value across all subsequent hits, until it is manually set to null.
        // This should never be done in normal operation.
        //
        // [tracker set:kGAISessionControl value:@"start"];
    
        // Instead, send a single hit with session control to start the new session.
        [tracker send:[[[GAIDictionaryBuilder createEventWithCategory:@"UX"
                                                               action:@"appstart"
                                                                label:nil
                                                                value:nil] set:@"start" forKey:kGAISessionControl] build]];
    
    
  8. 应用级选择停用设置不再由 SDK 长久保存,而是必须在每次应用启动时设置(默认值为 NO)。 详细了解应用级选择停用设置

参考信息

下文将提供参考示例,向您演示如何使用 V3 SDK 来设置和发送数据。

在 v3 中使用字典来发送数据

在 V3 中,数据的发送只使用一个 send: 方法,该方法将包含 Google Analytics(分析)字段和值的 NSDictionary 用作参数。我们还提供了 GAIDictionaryBuilder 实用工具类来简化构建匹配的流程:

id<GAITracker> tracker = [[GAI sharedInstance] defaultTracker];
[tracker set:kGAIScreenName value:@"Home Screen"];

// Previous V3 SDK versions.
// [tracker send:[[GAIDictionaryBuilder createAppView] setValue:@"Premium"  // Creates a Map of hit type 'AppView' (screenview) and set any additional fields.
//                                                     forKey:[customDimensionForIndex:1] build]; // Build and return the dictionary to the send method.

// SDK Version 3.08 and up.
[tracker send:[[GAIDictionaryBuilder createScreenView] setValue:@"Premium"  // Creates a Map of hit type 'ScreenView' and set any additional fields.
                                                       forKey:[customDimensionForIndex:1] build]; // Build and return the dictionary to the send method.

GAIDictionaryBuilder 类可用于构建所支持的任何匹配类型,例如事件:

id<GAITracker> tracker = [[GAI sharedInstance] defaultTracker];

[tracker send:[[GAIDictionaryBuilder createEventWithCategory:@"ui_action"     // Event category (required)
                                                      action:@"button_press"  // Event action (required)
                                                       label:@"play"          // Event label
                                                       value:nil] build]];    // Event value

了解有关在 v3 中发送数据的详情

在跟踪器中设置数据 (v3)

您可以使用 set:value:forKey 方法直接在 GAITracker 中设置值。直接设置的值会应用于该 GAITracker 的所有后续匹配:

// Values set directly on a tracker apply to all subsequent hits.
[tracker set:kGAIScreenName value:@"Home Screen"];

// This screenview hit will include the screen name "Home Screen".
// [tracker send:[[GAIDictionaryBuilder createAppView] build]];   // Previous V3 SDK versions.
[tracker send:[[GAIDictionaryBuilder createScreenView] build]];   // SDK Version 3.08 and up.

// And so will this event hit.
[tracker send:[[GAIDictionaryBuilder createEventWithCategory:@"ui_action"
                                                      action:@"button_press"
                                                       label:@"play"
                                                       value:nil] build]];

要清除在 GAITracker 中设置的值,请将相应属性设置为 nil

// Clear the previously-set screen name value.
[tracker set:kGAIScreenName
       value:nil];

// Now this event hit will not include a screen name value.
[tracker send:[[GAIDictionaryBuilder createEventWithCategory:@"ui_action"
                                                      action:@"button_press"
                                                       label:@"play"
                                                       value:nil] build]];

详细了解在 v3 中设置数据的相关信息