SDK Google Analytics для iOS: переход на версию 3

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

Что нового появилось в версии 3

API в версии 3 были реорганизованы для большей согласованности между "родными" и веб-платформами. Пользователи второй версии должны учитывать следующие изменения:

  • Обращения теперь отправляются с помощью одного метода send:(NSDictionary *)params.
  • Было устранено автоматическое управление сеансами на стороне клиента. Теперь тайм-аут сеанса настраивается в административном интерфейсе. Подробнее…
  • Вместо режима отладки был реализован инструмент Logger.
  • Добавлен флаг dryRun, блокирующий занесение данных в отчеты.
  • Добавлена поддержка местных валют для iOS.

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

Подготовка к работе

Для перехода на третью версию вам понадобятся:

Варианты перехода

Выберите вариант перехода, применимый к вашей ситуации:

С первой версии на третью

Если вы используете SDK Google Analytics для iOS версии 1.x, следуйте этому руководству.

Со второй версии на третью

Если вы пользуетесь второй версией, выполните следующие действия:

  1. Замените все методы send<hit-type> новым методом send:, как показано ниже.
    // 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. В третьей версии было упразднено автоматическое управление сеансами на стороне клиента. Тайм-аут сеанса теперь настраивается в административном интерфейсе и по умолчанию составляет 30 минут. Чтобы вручную начать или завершить сеанс, используйте параметр sessionControl. Подробнее об управлении сеансами в третьей версии...

  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 (протокол по умолчанию), задайте параметр kGAIUseSecure в каждом объекте 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]];
    
    }
    
  6. В третьей версии SDK новый сеанс больше не начинается автоматически при запуске приложения. Вам нужно будет реализовать собственную логику управления сеансами, когда пользователь открывает ваше приложение:
  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 (нет). Подробнее об отказе на уровне приложения…

Справочные материалы

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

Отправка данных с помощью словарей в версии 3

В третьей версии используется только один метод send:, который в качестве аргумента принимает поля и значения NSDictionary Google Analytics. Служебный класс 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

Подробнее об отправке данных в третьей версии…

Установка значений в трекере в версии 3

Значения также можно задавать непосредственно в GAITracker, используя метод set:value:forKey. Они будут применяться ко всем последующим обращениям от этого трекера:

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

Подробнее о настройке данных в третьей версии...