Google Analytics SDK dành cho iOS – Di chuyển sang phiên bản 3

Hướng dẫn này mô tả cách nâng cấp lên phiên bản 3 của SDK Google Analytics dành cho iOS.

Xem nhanh: Tính năng mới trong phiên bản 3

Các API trong phiên bản 3 đã được tái cấu trúc để nhất quán hơn trên các nền tảng gốc và web. Tất cả người dùng phiên bản 2 cần lưu ý những thay đổi sau:

Các lượt truy cập hiện được gửi bằng một phương thức send:(NSDictionary *)params duy nhất.
Tính năng quản lý phiên tự động phía máy khách đã bị loại bỏ. Bạn có thể định cấu hình thời gian chờ của phiên trong giao diện quản lý. Tìm hiểu thêm.
Chế độ gỡ lỗi đã được thay thế bằng Logger
Mới: Thêm một cờ dryRun để ngăn dữ liệu đã gửi xuất hiện trong báo cáo.
Mới: Chúng tôi đã thêm hỗ trợ nội tệ cho iOS.

Để xem danh sách đầy đủ các thay đổi, hãy xem Nhật ký thay đổi.

Trước khi bạn bắt đầu

Trước khi bắt đầu nâng cấp lên phiên bản 3, bạn sẽ cần:

Lộ trình nâng cấp

Để bắt đầu, hãy chọn một đường dẫn nâng cấp lên v3 trong cách triển khai hiện tại của bạn:

Phiên bản 1.x sang phiên bản 3
Phiên bản 2.x sang phiên bản 3

phiên bản 1.x sang phiên bản 3

Người dùng Google Analytics iOS SDK phiên bản 1.x nên làm theo Hướng dẫn bắt đầu sử dụng phiên bản 3 để bắt đầu sử dụng phiên bản 3.

phiên bản 2.x sang phiên bản 3

Người dùng phiên bản 2.x nên làm theo các bước sau để nâng cấp lên phiên bản 3:

Thay thế tất cả phương thức tiện lợi send<hit-type> bằng phương thức send: mới:

// 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.

Tính năng quản lý phiên phía máy khách tự động đã bị loại bỏ trong phiên bản 3. Bạn có thể đặt khoảng thời gian chờ của phiên trong giao diện quản lý và đặt mặc định là 30 phút. Bạn cũng có thể bắt đầu và dừng phiên theo cách thủ công bằng cách sử dụng tham số sessionControl. Tìm hiểu thêm về tính năng quản lý phiên trong phiên bản 3.

Người dùng của tính năng Tự động theo dõi màn hình phải thay thế các tệp tham chiếu đến GAITrackedViewController.trackedViewName bằng 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.

Chế độ gỡ lỗi hiện không còn được dùng nữa - hãy sử dụng Logger thay thế:

// v2 (Old)
[GAI sharedInstance].debug = YES;

// v3
[[GAI sharedInstance].logger setLogLevel:kGAILogLevelVerbose];

Thuộc tính GAI.useHttp đã bị xoá -- để gửi lượt truy cập bằng HTTP thay vì HTTPS mặc định, hãy đặt tham số kGAIUseSecure trên từng GAITracker:

// 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]];

}

SDK phiên bản 3 không còn tự động bắt đầu một phiên mới khi ứng dụng mở. Nếu muốn duy trì hành vi này từ phiên bản 2, bạn cần triển khai logic kiểm soát phiên của riêng mình khi người dùng khởi động ứng dụng:

// 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]];

SDK không còn duy trì chế độ cài đặt chọn không tham gia cấp ứng dụng này nữa và phải được đặt mỗi khi chạy ứng dụng (mặc định là NO). Tìm hiểu thêm về cách đặt chế độ chọn không sử dụng ở cấp ứng dụng.

Tài liệu tham khảo

Các phần sau đây cung cấp ví dụ tham khảo về cách thiết lập và gửi dữ liệu bằng SDK V3.

Gửi dữ liệu bằng từ điển trong phiên bản 3

Trong phiên bản 3, dữ liệu được gửi bằng một phương thức send: duy nhất. Phương thức này lấy NSDictionary trong số các trường và giá trị Google Analytics làm đối số. Một lớp tiện ích GAIDictionaryBuilder được cung cấp để đơn giản hoá quá trình tạo lượt truy cập:

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.

Bạn có thể sử dụng lớp GAIDictionaryBuilder để tạo bất kỳ loại lượt truy cập nào được hỗ trợ, chẳng hạn như sự kiện:

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

Tìm hiểu thêm về cách gửi dữ liệu trong phiên bản 3.

Cài đặt dữ liệu trên Công cụ theo dõi trong phiên bản 3

Bạn cũng có thể đặt các giá trị trực tiếp trên GAITracker bằng phương thức set:value:forKey. Các giá trị đã đặt trực tiếp được áp dụng cho tất cả các lượt truy cập tiếp theo từ 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]];

Để xóa giá trị đã được đặt trên GAITracker, hãy đặt thuộc tính thành 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]];

Tìm hiểu thêm về cách Thiết lập dữ liệu trong phiên bản 3