Konfiguracja zaawansowana – pakiet SDK na iOS

Ten dokument zawiera przegląd niektórych zaawansowanych funkcji konfiguracyjnych pakietu Google Analytics SDK na iOS v3.

Przegląd

Pakiet Google Analytics SDK na iOS zawiera klasę GAITracker służącą do ustawiania i wysyłania danych do Google Analytics oraz klasykę GAI, która służy jako interfejs do globalnych wartości konfiguracyjnych implementacji.

Zdarzenie inicjujące

Zanim będzie można mierzyć dane, musisz zainicjować co najmniej 1 tag śledzenia za pomocą singletonu GoogleAnalytics, podając nazwę i identyfikator usługi w Google Analytics:

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

Teraz można go używać do konfigurowania i wysyłania danych do Google Analytics.

Ustawianie i wysyłanie danych

Dane są wysyłane do Google Analytics przez ustawienie w module śledzenia map par parametr-wartość i wysyłanie ich za pomocą metod set i 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];

Klasa GAIDictionaryBuilder upraszcza proces generowania działań i jest zalecana w większości przypadków. Tutaj możemy wysłać ten sam widok ekranu z mniejszą liczbą linijek kodu:

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

Składnia platformy Measurement Protocol

Wartości można też ustawiać dla pojedynczego działania, ustawiając je w Builder lub dla wszystkich kolejnych działań, ustawiając je w samym obiekcie śledzenia przy użyciu składni ampersand protokołu 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]];

Pełną listę dostępnych parametrów platformy Measurement Protocol znajdziesz w dokumentacji parametrów platformy Measurement Protocol.

Stosowanie wartości do wielu działań

Wszelkie wartości ustawione bezpośrednio w trackerze zostaną zachowane i zastosowane do wielu działań, jak w tym przykładzie:

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

Bezpośrednio w narzędziu do śledzenia należy ustawiać tylko te wartości, które mają być pozostawiane dla wielu działań. Nadanie nazwy ekranu w narzędziu do śledzenia ma sens, ponieważ ta sama wartość może być stosowana do kolejnych wyświetleń ekranu i działań związanych ze zdarzeniem. Nie zalecamy jednak ustawiania w module śledzenia pól takich jak typ trafienia, ponieważ będzie się ono zmieniać z każdym działaniem.

Korzystanie z wielu trackerów

W jednej implementacji można używać wielu skryptów śledzenia, co może być przydatne przy wysyłaniu danych do wielu usług:

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.

Zautomatyzowane funkcje pomiarowe, takie jak automatyczny pomiar niewykrytych wyjątków i pomiar niewykrytych wyjątków, będą używać tylko jednego trackera do wysyłania danych do Google Analytics. Jeśli korzystasz z tych funkcji i chcesz wysyłać dane za pomocą innych trackerów, musisz to zrobić ręcznie.

W celach informacyjnych, automatyczny pomiar ekranu korzysta z lokalizatora określonego we właściwości tracker danej wartości GAITrackedViewController. Pomiar niewykrytych wyjątków używa domyślnego trackera określonego w instancji GAI.

Korzystanie z domyślnego trackera

Google Analytics zachowuje domyślny moduł śledzenia. Pierwszy zainicjowany element śledzący staje się domyślnym modułem śledzącym, ale może zostać zastąpiony:

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

Próbkowanie

Możesz włączyć próbkowanie po stronie klienta, aby ograniczyć liczbę działań wysyłanych do Google Analytics. Jeśli Twoja aplikacja ma dużą liczbę użytkowników lub w inny sposób wysyła do Google Analytics dużą ilość danych, włączenie próbkowania pomoże zapewnić nieprzerwane raportowanie.

Aby np. wdrożyć próbkowanie po stronie klienta z częstotliwością 50%, użyj tego kodu:

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

Aby uniknąć niespójności w raportach,każdy widok aplikacji (profil) powinien zawierać dane zebrane z tą samą częstotliwością próbkowania. Jeśli różne wersje aplikacji korzystają z różnych częstotliwości próbkowania, musisz skonfigurować filtry widoku (profil) za pomocą wymiaru Wersja aplikacji, aby dane z poszczególnych wersji aplikacji były przechowywane oddzielnie.

Rezygnacja na poziomie aplikacji

Możesz włączyć flagę rezygnacji na poziomie aplikacji, która spowoduje wyłączenie Google Analytics w całej aplikacji. Pamiętaj, że tę flagę należy ustawić przy każdym uruchomieniu aplikacji. Domyślna wartość to NO.

Aby uzyskać ustawienie rezygnacji na poziomie aplikacji:

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

Aby ustawić rezygnację na poziomie aplikacji:

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

Usuwanie danych użytkownika po stronie klienta

Jeśli musisz zresetować lub usunąć dane Google Analytics odnoszące się do użytkowników, możesz usunąć pliki Google Analytics lub ustawić nowy identyfikator klienta.

Opcja 1. Usuń pliki Google Analytics

Jeśli Twoja aplikacja nie ustawia wyraźnie identyfikatora klienta dla użytkownika, możesz wymusić wygenerowanie nowego identyfikatora klienta, usuwając pliki Google Analytics służące do jego przechowywania.

Aby usunąć pliki Google Analytics, możesz użyć poniższej przykładowej metody. Tę metodę należy zastosować przed inicjowaniem 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.
    }
  }
}

Pliki Google Analytics należy usunąć przed zainicjowaniem [GAI sharedInstance].

Opcja 2. Ustaw nowy identyfikator klienta

Możesz wygenerować i ustawić nowy unikalny identyfikator klienta. Wszystkie kolejne działania będą korzystać z nowego identyfikatora klienta, a wcześniejsze dane nie będą z nim powiązane.

Uruchom ten kod, aby wygenerować i ustawić nowy identyfikator klienta:

[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;

Jeśli zdecydujesz się na jawne ustawienie identyfikatora klienta, a nie na generowanie losowego identyfikatora, sprawdź, czy jest to prawidłowy ciąg znaków UUID (w wersji 4) zgodnie z opisem na stronie https://goo.gl/0dlrGx.

Jeśli masz włączony identyfikator IDFA (identyfikator dla reklamodawców), ustawienie nowego identyfikatora klienta spowoduje, że zostanie on natychmiast zastąpiony nowym, losowo wygenerowanym identyfikatorem klienta. Jeśli wymagasz skonfigurowania określonego identyfikatora klienta i masz włączone IDFA (identyfikator dla reklamodawców), ta opcja nie jest zalecana. Zamiast tego skorzystaj z opcji 1. Usuń pliki Google Analytics, aby zresetować identyfikator klienta.

Ukryj adres IP

Włączenie funkcji anonimizacji adresów IP informuje Google Analytics o anonimizacji informacji IP wysyłanych przez pakiet SDK przez usunięcie ostatniego oktetu adresu IP przed jego przechowywaniem.

Poniższy przykład pokazuje, jak enable funkcję anonimizacji adresu IP na potrzeby śledzenia:

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

Funkcję anonimizacji adresów IP można skonfigurować w każdej chwili.

Testowanie i debugowanie

Pakiet SDK Google Analytics na iOS udostępnia narzędzia, które ułatwiają testowanie i debugowanie.

Uruchomienie próbne

Pakiet SDK udostępnia flagę dryRun, która po skonfigurowaniu uniemożliwia wysyłanie danych do Google Analytics. Flaga dryRun należy ustawić za każdym razem, gdy testujesz lub debugujesz implementację i nie chcesz, aby dane testowe pojawiały się w raportach Google Analytics.

Aby ustawić flagę uruchomienia próbnego:

[[GAI sharedInstance] setDryRun:YES];

Rejestrator

Protokół GAILogger umożliwia obsługę przydatnych komunikatów z pakietu SDK na tych poziomach szczegółowości: error, warning, info i verbose.

Pakiet SDK inicjuje standardową implementację Logger, która domyślnie rejestruje w konsoli tylko ostrzeżenia lub komunikaty o błędach. Aby ustawić szczegółowość interfejsu Logger:

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

Możesz też użyć niestandardowych implementacji elementu Logger:

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

Pełny przykład

W przykładzie poniżej pokazujemy kod wymagany do zainicjowania implementacji Google Analytics i wysłania wyświetlenia jednego ekranu.

Następnie wyświetlenie ekranu jest mierzone, gdy użytkownik zobaczy pierwszy ekran:

Zwykle inicjowanie implementacji można wykonać z poziomu delegata aplikacji, jak w tym przykładzie:

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

Następnie, aby mierzyć wyświetlenia ekranu, gdy widok zostanie wyświetlony użytkownikowi:

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