Расширенная настройка: SDK для iOS

В этом документе представлен краткий обзор расширенных настроек в SDK Google Analytics для iOS версии 3.

Обзор

SDK Google Analytics для iOS предоставляет класс GAITracker для установки и отправки значений в Google Analytics, а также синглтон GAI, который служит интерфейсом для глобальных значений конфигурации вашего приложения.

Инициализация отслеживания

Прежде чем вы сможете получать аналитические данные, необходимо инициализировать хотя бы один трекер через синглтон GoogleAnalytics, предоставив название трекера и идентификатор ресурса Google Analytics:

// Initialize a tracker using a Google Analytics property ID.
[[GAI sharedInstance] trackerWithTrackingId:@"UA-XXXX-Y"];

Теперь этот трекер можно использовать для настройки и отправки данных в Google Analytics.

Настройка и отправка данных

Для отправки данных в Google Analytics необходимо задать в счетчике пары "параметр-значение" с помощью метода set и затем передать их с помощью метода send, как показано ниже.

/*
 * Send a screen view to Google Analytics by setting a map of parameter
 * values on the tracker and calling send.
 */

// Retrieve tracker with placeholder property ID.
id<GAITracker> tracker = [[GAI sharedInstance] trackerWithTrackingId:@"UA-XXXX-Y"];

NSDictionary *params = [NSDictionary dictionaryWithObjectsAndKeys:
                            @"appview", kGAIHitType, @"Home Screen", kGAIScreenName, nil];
[tracker send:params];

Класс GAIDictionaryBuilder упрощает создание обращений и рекомендуется к использованию в большинстве случаев. Чтобы отправить тот же просмотр экрана, вам потребуется меньше строк кода:

// Previous V3 SDK versions.
// Sending the same screen view hit using [GAIDictionaryBuilder createAppView]
// [tracker send:[[[GAIDictionaryBuilder createAppView] set:@"Home Screen"
//                                                   forKey:kGAIScreenName] build]];

// SDK Version 3.08 and up.
// Sending the same screen view hit using [GAIDictionaryBuilder createScreenView]
[tracker send:[[[GAIDictionaryBuilder createScreenView] set:@"Home Screen"
                                                     forKey:kGAIScreenName] build]];

Амперсанд-синтаксис протокола передачи статистических данных

Если обращение единственное, его значение можно задать в Builder, а всех последующих – в самом трекере, используя амперсанд-синтаксис протокола Measurement Protocol:

// Sending the same screen view hit using ampersand syntax.
// Previous V3 SDK versions.
// [tracker send:[[[GAIDictionaryBuilder createAppView] set:@"Home Screen"
//                                                   forKey:kGAIScreenName] build]];

// SDK Version 3.08 and up.
[tracker send:[[[GAIDictionaryBuilder createScreenView] set:@"Home Screen"
                                                     forKey:kGAIScreenName] build]];

Ознакомьтесь с полным списком всех параметров, которые можно отправлять с помощью Measurement Protocol.

Применение значений к нескольким обращениям

Все значения, которые вы задаете в самом трекере, сохраняются и применяются к нескольким обращениям, как в этом примере:

// May return nil if a tracker has not yet been initialized with
// a property ID.
id<GAITracker> tracker = [[GAI sharedInstance] defaultTracker];

// Set screen name on the tracker to be sent with all hits.
[tracker set:kGAIScreenName
       value:@"Home Screen"];

// Send a screen view for "Home Screen".
// [tracker send:[[GAIDictionaryBuilder createAppView] build]];   // Previous V3 SDK versions.
[tracker send:[[GAIDictionaryBuilder createScreenView] build]];   // SDK Version 3.08 and up.

// This event will also be sent with &cd=Home%20Screen.
[tracker send:[[GAIDictionaryBuilder createEventWithCategory:@"UX"
                                                      action:@"touch"
                                                       label:@"menuButton"
                                                       value:nil] build]];

// Clear the screen name field when we're done.
[tracker set:kGAIScreenName
       value:nil];

В счетчике следует задавать только те значения, которые вы хотите использовать в нескольких обращениях, например название экрана, поскольку оно останется тем же для последующих просмотров и событий. Однако напрямую не рекомендуется устанавливать такие поля, как тип обращения, так как он может каждый раз меняться.

Использование нескольких счетчиков

Вы можете реализовать в приложении несколько трекеров, отправляющих данные на разные ресурсы:

id<GAITracker> t1 = [[GAI sharedInstance] trackerWithTrackingId:@"UA-XXXX-1"];

// Trackers may be named. By default, name is set to the property ID.
id<GAITracker> t2 = [[GAI sharedInstance] trackerWithName:@"altTracker"
                                                     trackingId:@"UA-XXXX-2"];

[t1 set:kGAIScreenName
        value:@"Home Screen"];

[t2 set:kGAIScreenName
        value:NSStringFromClass([self class])];

// Send a screenview to UA-XXXX-1.
// [t1 send:[[GAIDictionaryBuilder createAppView] build]];   // Previous V3 SDK versions.
[t1 send:[[GAIDictionaryBuilder createScreenView] build]];   // SDK Version 3.08 and up.

// Send a screenview to UA-XXXX-2.
// [t2 send:[[GAIDictionaryBuilder createAppView] build]];   // Previous V3 SDK versions.
[t2 send:[[GAIDictionaryBuilder createScreenView] build]];   // SDK Version 3.08 and up.

Если вы настроили автоматическое отслеживание (например, экранов и неперехваченных исключений), для отправки данных в Google Analytics будет использоваться только один счетчик. В этом случае передавать информацию с нескольких трекеров вам придется вручную.

Для справки: при автоматическом отслеживании экранов используется трекер, указанный в свойстве tracker данного контроллера представления GAITrackedViewController, а при автоматическом отслеживании неперехваченных исключений – трекер, заданный в экземпляре GAI.

Счетчик по умолчанию

В Google Analytics по умолчанию используется первый инициализированный счетчик, однако при желании вы можете указать вместо него другой:

// t1 becomes the default tracker because it is the first tracker initialized.
id<GAITracker> t1 = [[GAI sharedInstance] trackerWithTrackingId:@"UA-XXXX-1"];

id<GAITracker> t2 = [[GAI sharedInstance] trackerWithTrackingId:@"UA-XXXX-2"];

// Returns t1.
id<GAITracker> defaultTracker = [[GAI sharedInstance] defaultTracker];

// Hit sent to UA-XXXX-1.
// Previous V3 SDK versions.
// [defaultTracker send:[[[GAIDictionaryBuilder createAppView]
//                 set:@"Home Screen" forKey:kGAIScreenName] build]];

// SDK Version 3.08 and up.
[defaultTracker send:[[[GAIDictionaryBuilder createScreenView]
                set:@"Home Screen" forKey:kGAIScreenName] build]];

// Override the default tracker.
[[GAI sharedInstance] setDefaultTracker:t2];

// Returns t2.
defaultTracker = [[GAI sharedInstance] defaultTracker];

// Hit sent to UA-XXXX-2.
// Previous V3 SDK versions.
// [defaultTracker send:[[[GAIDictionaryBuilder createAppView]
//                        set:NSStringFromClass([self class])
//                     forKey:kGAIScreenName] build]];

// SDK Version 3.08 and up.
[defaultTracker send:[[[GAIDictionaryBuilder createScreenView]
                       set:NSStringFromClass([self class])
                    forKey:kGAIScreenName] build]];

Выборка

Чтобы сократить количество обращений в Google Analytics, можно настроить выборку данных на стороне клиента. Если у вашего приложения много пользователей или оно отправляет в Google Analytics большой объем информации, выборка поможет избежать перебоев в отчетности.

Например, следующий код задает выборку 50%:

// Assumes a tracker has already been initialized with a property ID, otherwise
// getDefaultTracker returns nil.
id<GAITracker> tracker = [[GAI sharedInstance] defaultTracker];

// Set a sample rate of 50%.
[tracker set:kGAISampleRate value:@"50.0"];

Отказ от отслеживания на уровне приложения

Вы можете добавить пометку, позволяющую отключить сбор данных Google Analytics на уровне приложения. Учтите, что она должна устанавливаться при каждом запуске приложения, а ее значение по умолчанию – NO.

Чтобы реализовать отказ от отслеживания на уровне приложения, используйте следующий код:

// Get the app-level opt out preference.
if ([GAI sharedInstance].optOut) {
  ... // Alert the user they have opted out.
}

Задать отказ от отслеживания на уровне приложения можно так:

// Set the app-level opt out preference.
[[GAI sharedInstance] setOptOut:YES];

Анонимизация IP

Если эта функция включена, Google Analytics скрывает сведения об IP-адресах, отправляемые SDK, удаляя последний октет из адреса перед его сохранением.

В следующем коде включается анонимизация IP для трекера:

[tracker set:kGAIAnonymizeIp value:@"1"];

Эту функцию можно активировать в любое время.

Тестирование и отладка

В помощь разработчикам SDK Google Analytics для iOS предоставляет следующие инструменты для тестирования и отладки.

Флаг dryRun

Флаг dryRun позволяет запретить отправку данных в Google Analytics. Используйте его при тестировании и отладке, чтобы не засорять отчеты Google Analytics.

Вот как установить этот флаг:

[[GAI sharedInstance] setDryRun:YES];

Интерфейс Logger

Для журналирования служит протокол GAILogger. Он позволяет обрабатывать сообщения от SDK на следующих уровнях детализации: error (ошибка), warning (предупреждение), info (информация) и verbose (подробности).

SDK инициализирует стандартную реализацию логгера, при которой по умолчанию на консоли регистрируются только предупреждения и сообщения об ошибках. Вот как задать уровень детализации для интерфейса Logger:

// Set the log level to verbose.
[[GAI sharedInstance].logger setLogLevel:kGAILogLevelVerbose];

Также возможна пользовательская реализация логгера:

// Provide a custom logger.
[[GAI sharedInstance].logger = [[CustomLogger alloc] init];

Полный пример

Далее приведен пример кода, который инициализирует отслеживание Google Analytics и сообщает о просмотре экрана.

Просмотр экрана учитывается, когда пользователь видит первый экран приложения.

Обычно инициализацию можно выполнить из делегата приложения, как в этом примере:

//
//  AppDelegate.h
//
#import <UIKit/UIKit.h>
#import "GAI.h"

@interface AppDelegate : UIResponder <UIApplicationDelegate>

@property (strong, nonatomic) UIWindow *window;
@property (strong, nonatomic) id<GAITracker> tracker;

@end

//
//  AppDelegate.m
//
#import "AppDelegate.h"

/** Google Analytics configuration constants **/
static NSString *const kGaPropertyId = @"UA-XXXX-Y"; // Placeholder property ID.
static NSString *const kTrackingPreferenceKey = @"allowTracking";
static BOOL const kGaDryRun = NO;
static int const kGaDispatchPeriod = 30;

@interface AppDelegate ()

- (void)initializeGoogleAnalytics;

@end

@implementation AppDelegate
- (void)applicationDidBecomeActive:(UIApplication *)application {
    [GAI sharedInstance].optOut =
    ![[NSUserDefaults standardUserDefaults] boolForKey:kTrackingPreferenceKey];
}

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    // Do other work for customization after application launch
    // then initialize Google Analytics.
    [self initializeGoogleAnalytics];

    return YES;
}

- (void)initializeGoogleAnalytics {

    [[GAI sharedInstance] setDispatchInterval:kGaDispatchPeriod];
    [[GAI sharedInstance] setDryRun:kGaDryRun];
    self.tracker = [[GAI sharedInstance] trackerWithTrackingId:kGaPropertyId];
}

// The rest of the app delegate code omitted.

@end

Затем учитывается просмотр экрана:

//
// MyViewController.m
//
#import "MyViewController.h"
#import "AppDelegate.h"
#import "GAI.h"
#import "GAIFields.h"
#import "GAITracker.h"
#import "GAIDictionaryBuilder.h"

@implementation MyViewController

- (void)viewDidAppear:(BOOL)animated {
    [super viewDidAppear:animated];

    // This screen name value will remain set on the tracker and sent with
    // hits until it is set to a new value or to nil.
    [[GAI sharedInstance].defaultTracker set:kGAIScreenName
                                       value:@"Home Screen"];

    // Send the screen view.
    // Previous V3 SDK versions.
    // [[GAI sharedInstance].defaultTracker
    //     send:[[GAIDictionaryBuilder createAppView] build]];

    // SDK Version 3.08 and up.
    [[GAI sharedInstance].defaultTracker
        send:[[GAIDictionaryBuilder createScreenView] build]];
}