Erweiterte Konfiguration – iOS SDK

Dieses Dokument bietet einen Überblick über einige der erweiterten Konfigurationsfunktionen des Google Analytics SDK for iOS Version 3.

Überblick

Das Google Analytics SDK für iOS bietet eine GAITracker-Klasse zum Festlegen und Senden von Daten an Google Analytics sowie einen GAI-Singleton, der als Schnittstelle zu den globalen Konfigurationswerten Ihrer Implementierung dient.

Initialisierung

Bevor Daten gemessen werden können, müssen Sie mindestens einen Tracker über das Singleton GoogleAnalytics initialisieren. Geben Sie dazu einen Namen für den Tracker und eine Google Analytics-Property-ID an:

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

Jetzt können mit diesem Tracker Daten festgelegt und an Google Analytics gesendet werden.

Daten festlegen und senden

Daten werden an Google Analytics gesendet, indem Zuordnung von Parameter/Wert-Paaren auf dem Tracker festgelegt und über die Methoden set und send gesendet wird:

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

Die Klasse GAIDictionaryBuilder vereinfacht das Erstellen von Treffern und wird für die meisten Anwendungsfälle empfohlen. Hier können wir dieselbe Bildschirmansicht mit weniger Codezeilen senden:

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

kaufmännisches Und-Zeichen (Measurement Protocol)

Werte können auch für einen einzelnen Treffer oder durch Festlegen des Werts für einen Builder oder für alle nachfolgenden Treffer festgelegt werden, indem Sie ihn mithilfe des Et-Zeichens des Measurement Protocol im Tracker-Objekt selbst festlegen:

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

Eine vollständige Liste der verfügbaren Measurement Protocol-Parameter finden Sie in der Referenz zu Measurement Protocol-Parametern.

Werte auf mehrere Treffer anwenden

Alle Werte, die direkt im Tracker festgelegt werden, werden beibehalten und auf mehrere Treffer angewendet, wie in diesem Beispiel:

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

Nur Werte, die für mehrere Treffer beibehalten werden sollen, sollten direkt im Tracker festgelegt werden. Es wäre sinnvoll, einen Bildschirmnamen für einen Tracker festzulegen, da derselbe Wert auf nachfolgende Bildschirmaufrufe und Ereignistreffer angewendet werden kann. Es wird jedoch nicht empfohlen, auf dem Tracker ein Feld wie den Treffertyp festzulegen, da es sich wahrscheinlich mit jedem Treffer ändert.

Mehrere Tracker verwenden

In einer einzelnen Implementierung können mehrere Tracker verwendet werden, was beim Senden von Daten an mehrere Properties nützlich sein kann:

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.

Bei automatischen Messfunktionen wie der automatischen Filterung und der Messung nicht erfasster Ausnahmen wird nur ein Tracker verwendet, um Daten an Google Analytics zu senden. Wenn du diese Funktionen verwendest und Daten mit anderen Trackern senden möchtest, musst du dies manuell tun.

Bei der automatischen Bildschirmmessung wird als Referenz der Tracker verwendet, der in der Eigenschaft tracker eines bestimmten GAITrackedViewController angegeben ist. Die Messung einer nicht abgefangenen Ausnahme verwendet den in der GAI-Instanz angegebenen Standardtracker.

Verwenden des Standard-Trackers

In Google Analytics wird ein Standard-Tracker verwendet. Der erste initialisierte Tracker wird zum Standard-Tracker, kann aber überschrieben werden:

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

Probenahme

Sie können die clientseitige Stichprobenerhebung aktivieren, um die Anzahl der Treffer zu begrenzen, die an Google Analytics gesendet werden. Wenn Ihre Anwendung eine große Anzahl von Nutzern hat oder anderweitig ein großes Datenvolumen an Google Analytics sendet, können Sie durch Aktivieren der Stichprobenerhebung eine unterbrechungsfreie Berichterstellung gewährleisten.

Wenn Sie beispielsweise die clientseitige Stichprobennahme mit einer Rate von 50 % implementieren möchten, verwenden Sie den folgenden Code:

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

Deaktivierung auf App-Ebene

Sie können ein Deaktivierungs-Flag auf App-Ebene aktivieren, durch das Google Analytics für die gesamte App deaktiviert wird. Dieses Flag muss bei jedem Start der App gesetzt werden und wird standardmäßig auf NO gesetzt.

So rufen Sie die Deaktivierungseinstellung auf App-Ebene ab:

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

So legen Sie die Deaktivierung auf App-Ebene fest:

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

Clientseitige Nutzerdaten löschen

Wenn Sie clientseitige Google Analytics-Daten für Ihre Endnutzer zurücksetzen oder löschen müssen, können Sie die Google Analytics-Dateien löschen oder eine neue Client-ID festlegen.

Option 1: Google Analytics-Dateien löschen

Wenn in Ihrer App die Client-ID für einen Endnutzer nicht explizit festgelegt wird, können Sie die Generierung einer neuen Client-ID erzwingen, indem Sie die Google Analytics-Dateien löschen, in denen die Client-ID gespeichert wurde.

Mit der folgenden Beispielmethode können die Google Analytics-Dateien gelöscht werden. Die Methode muss vor der Initialisierung von Google Analytics ausgeführt werden:

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

Option 2: Neue Client-ID festlegen

Du kannst eine neue eindeutige Client-ID generieren und festlegen. Für alle nachfolgenden Treffer wird die neue Client-ID verwendet. Bisherige Daten werden nicht mit der neuen Client-ID verknüpft.

Führen Sie den folgenden Code aus, um eine neue Client-ID zu generieren und festzulegen:

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

IP-Anonymisierung

Wenn Sie die Funktion zur Anonymisierung von IP-Adressen aktivieren, werden die vom SDK gesendeten IP-Informationen in Google Analytics anonymisiert, indem das letzte Oktett der IP-Adresse vor dem Speichern entfernt wird.

Das folgende Beispiel zeigt, wie die Anonymisierungs-IP-Funktion für einen Tracker enable wird:

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

Die Funktion zur Anonymisierung der IP-Adresse kann jederzeit festgelegt werden.

Testen und Fehler beheben

Das Google Analytics SDK for iOS bietet Tools, die das Testen und die Fehlerbehebung erleichtern.

Probelauf

Im SDK wird das Flag dryRun bereitgestellt, das verhindert, dass Daten an Google Analytics gesendet werden. Das Flag dryRun sollte immer dann gesetzt werden, wenn Sie eine Implementierung testen oder Fehler beheben und die Testdaten nicht in Ihren Google Analytics-Berichten erscheinen sollen.

So legen Sie das Probelauf-Flag fest:

[[GAI sharedInstance] setDryRun:YES];

Logger

Das GAILogger-Protokoll wird zur Verarbeitung nützlicher Meldungen vom SDK mit folgenden Ausführlichkeitsstufen bereitgestellt: error, warning, info und verbose.

Das SDK initialisiert eine Logger-Standardimplementierung, die standardmäßig nur Warnungen oder Fehlermeldungen in der Console protokolliert. So legen Sie die Ausführlichkeit von Logger fest:

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

Benutzerdefinierte Implementierungen von Logger können auch verwendet werden:

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

Vollständiges Beispiel

Im folgenden Beispiel sehen Sie den Code, der zum Initialisieren einer Google Analytics-Implementierung und zum Senden eines einzelnen Bildschirmaufrufs erforderlich ist.

Als Nächstes wird ein Bildschirmaufruf gemessen, wenn einem Nutzer der erste Bildschirm angezeigt wird:

In der Regel kann die Initialisierung einer Implementierung über den Anwendungsdelegat erfolgen, wie in diesem Beispiel:

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

So messen Sie dann einen Bildschirmaufruf, wenn einem Nutzer eine Ansicht angezeigt wird:

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