Расширенная конфигурация — iOS SDK

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

Обзор

Google Analytics SDK для 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 , или для всех последующих обращений, установив его в самом объекте отслеживания, используя синтаксис амперсанда протокола измерений:

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

Полный список доступных параметров протокола измерений см. в Справочнике параметров протокола измерений .

Применение значений к множественным обращениям

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

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

Удаление пользовательских данных на стороне клиента

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

Вариант 1. Удалите файлы Google Analytics.

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

Следующий пример метода можно использовать для удаления файлов Google Analytics. Метод должен быть выполнен до инициализации Google Analytics:

/* Execute this before [GAI sharedInstance] is initialized. */
static void DeleteGAFiles(void) {
  NSArray *paths = NSSearchPathForDirectoriesInDomains(NSLibraryDirectory, NSUserDomainMask, YES);
  NSFileManager *fileManager = [NSFileManager defaultManager];
  NSArray *libraryFiles = [fileManager contentsOfDirectoryAtPath:paths.firstObject error:nil];

  NSPredicate *predicate =
      [NSPredicate predicateWithFormat:@"self BEGINSWITH 'googleanalytics'"];
  NSArray *matchingFileNames = [libraryFiles filteredArrayUsingPredicate:predicate];

  for (NSString *fileName in matchingFileNames) {
    NSError *error;
    NSString *filePath = [paths.firstObject stringByAppendingPathComponent:fileName];
    if (![fileManager removeItemAtPath:filePath error:&error]) {
      // Log error.
    }
  }
}

Файлы Google Analytics необходимо удалить до инициализации [GAI sharedInstance] .

Вариант 2. Установите новый идентификатор клиента

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

Выполните следующий код, чтобы сгенерировать и установить новый идентификатор клиента:

[GAI sharedInstance].optOut = YES;

// This Id should be a valid UUID (version 4) string as described in https://goo.gl/0dlrGx.
NSString *newClientID = [NSUUID UUID].UUIDString.lowercaseString;
id dispatcher = [[GAI sharedInstance] performSelector:@selector(dispatcher)];
id dataStore = [dispatcher performSelector:@selector(dataStore)];
if ([dataStore respondsToSelector:@selector(setClientId:)]) {
  [dataStore performSelector:@selector(setClientId:) withObject:newClientID];
}

[GAI sharedInstance].optOut = NO;

Если вы решите явно установить идентификатор клиента вместо генерации случайного идентификатора, убедитесь, что это действительная строка UUID (версия 4), как описано в https://goo.gl/0dlrGx .

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

Анонимизировать IP

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

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

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

Функцию анонимизации IP можно настроить в любое время.

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

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

Пробный прогон

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

Чтобы установить флаг пробного запуска:

[[GAI sharedInstance] setDryRun:YES];

Регистратор

Протокол GAILogger предназначен для обработки полезных сообщений из SDK на следующих уровнях детализации: error , warning , info и verbose .

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

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

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

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