Konfigurasi Lanjutan - iOS SDK

Dokumen ini memberikan ringkasan tentang beberapa fitur konfigurasi lanjutan Google Analytics SDK for iOS v3.

Ringkasan

Google Analytics SDK untuk iOS menyediakan class GAITracker untuk menetapkan dan mengirim data ke Google Analytics, dan singleton GAI yang berfungsi sebagai antarmuka ke nilai konfigurasi global dari penerapan Anda.

Inisialisasi

Sebelum data dapat diukur, Anda harus menginisialisasi setidaknya satu pelacak melalui singleton GoogleAnalytics dengan memberikan nama untuk pelacak dan ID properti Google Analytics:

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

Sekarang pelacak ini dapat digunakan untuk menetapkan dan mengirim data ke Google Analytics.

Menetapkan dan Mengirim Data

Data dikirim ke Google Analytics dengan menetapkan peta pasangan parameter value di pelacak dan mengirimkannya melalui metode set dan 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];

Class GAIDictionaryBuilder menyederhanakan proses pembuatan hit dan direkomendasikan untuk sebagian besar kasus penggunaan. Di sini kita dapat mengirimkan tampilan layar yang sama dengan baris kode yang lebih sedikit:

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

Sintaksis ampersand Measurement Protocol

Nilai juga dapat ditetapkan pada satu hit, dengan menetapkan nilai pada Builder, atau pada semua hit berikutnya, dengan menetapkannya pada objek pelacak itu sendiri, menggunakan sintaksis ampersand dan 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]];

Untuk mengetahui daftar lengkap parameter Measurement Protocol yang tersedia, lihat Referensi Parameter Measurement Protocol.

Menerapkan Nilai ke Beberapa Klik

Setiap nilai yang ditetapkan di pelacak secara langsung akan dipertahankan dan diterapkan ke beberapa hit, seperti dalam contoh ini:

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

Hanya nilai yang ingin Anda pertahankan di beberapa hit yang harus ditetapkan langsung di pelacak. Penetapan nama layar pada pelacak adalah hal yang masuk akal, karena nilai yang sama dapat diterapkan ke tampilan layar dan hit peristiwa berikutnya. Namun, sebaiknya jangan menetapkan kolom seperti jenis hit di pelacak, karena kemungkinan akan berubah dengan setiap hit.

Menggunakan Beberapa Pelacak

Beberapa pelacak dapat digunakan dalam satu implementasi, yang dapat berguna untuk mengirim data ke beberapa properti:

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.

Fitur pengukuran otomatis, seperti pengukuran otomatis layar dan pengecualian yang tidak tertangkap, hanya akan menggunakan satu pelacak untuk mengirim data ke Google Analytics. Jika Anda menggunakan fitur ini dan ingin mengirim data menggunakan pelacak lain, Anda harus melakukannya secara manual.

Untuk referensi, pengukuran layar otomatis menggunakan pelacak yang ditentukan dalam properti tracker dari GAITrackedViewController tertentu. Pengukuran pengecualian yang tidak tertangkap menggunakan pelacak default yang ditentukan dalam instance GAI Anda.

Menggunakan Pelacak Default

Google Analytics mengelola pelacak default. Pelacak pertama yang diinisialisasi akan menjadi pelacak default, tetapi mungkin diganti:

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

Pengambilan Sampel

Anda dapat mengaktifkan pengambilan sampel sisi klien untuk membatasi jumlah hit yang dikirim ke Google Analytics. Jika aplikasi Anda memiliki pengguna dalam jumlah besar atau akan mengirimkan volume data yang besar ke Google Analytics, mengaktifkan pengambilan sampel akan membantu memastikan pelaporan yang tidak terganggu.

Misalnya, untuk menerapkan pengambilan sampel sisi klien pada rasio 50%, gunakan kode berikut:

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

Untuk menghindari inkonsistensi laporan, setiap tampilan (profil) aplikasi Anda harus berisi data yang dikumpulkan pada frekuensi sampling yang sama. Jika versi aplikasi yang berbeda menggunakan frekuensi sampling yang berbeda, Anda harus mengonfigurasi filter tampilan (profil) menggunakan dimensi versi aplikasi agar data dari setiap versi aplikasi tetap terpisah.

Pilihan Tidak Ikut Tingkat Aplikasi

Anda dapat mengaktifkan tanda pilihan tidak ikut tingkat aplikasi yang akan menonaktifkan Google Analytics di seluruh aplikasi. Perhatikan bahwa tanda ini harus ditetapkan setiap kali aplikasi dimulai dan akan ditetapkan secara default ke NO.

Untuk mendapatkan setelan pilihan tidak ikut tingkat aplikasi, gunakan:

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

Untuk menetapkan pilihan tidak ikut tingkat aplikasi, gunakan:

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

Menghapus data pengguna sisi klien

Jika perlu mereset atau menghapus data sisi klien Google Analytics untuk pengguna akhir, Anda dapat menghapus file Google Analytics atau menetapkan Client ID baru.

Opsi 1: Hapus file Google Analytics

Jika aplikasi Anda tidak secara eksplisit menetapkan Client ID untuk pengguna akhir, Anda dapat memaksa pembuatan Client ID baru dengan menghapus file Google Analytics yang digunakan untuk menyimpan Client ID.

Metode contoh berikut dapat digunakan untuk menghapus file Google Analytics. Metode ini harus dijalankan sebelum melakukan inisialisasi 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.
    }
  }
}

File Google Analytics harus dihapus sebelum [GAI sharedInstance] diinisialisasi.

Opsi 2: Menetapkan Client ID baru

Anda dapat membuat dan menetapkan Client ID unik baru. Semua hit berikutnya akan menggunakan Client ID baru dan data sebelumnya tidak akan dikaitkan dengan Client-ID baru.

Jalankan kode berikut untuk membuat dan menetapkan Client ID baru:

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

Jika Anda memutuskan untuk menetapkan Client ID secara eksplisit, bukan membuat yang acak, pastikan bahwa Client tersebut adalah string UUID (versi 4) yang valid seperti yang dijelaskan di https://goo.gl/0dlrGx.

Jika Anda telah mengaktifkan IDFA (ID untuk Pengiklan), menetapkan Client-ID baru akan menyebabkannya langsung ditimpa oleh Client-ID baru yang dibuat secara acak. Jika Anda perlu menetapkan Client-ID tertentu dan telah mengaktifkan IDFA (ID untuk Pengiklan), opsi ini tidak direkomendasikan. Sebagai gantinya, Anda harus menggunakan Opsi 1: Hapus file Google Analytics untuk mereset Client-ID.

Anonimkan IP

Mengaktifkan fungsi IP anonim akan memberi tahu Google Analytics untuk menganonimkan informasi IP yang dikirim oleh SDK dengan menghapus octet terakhir alamat IP sebelum penyimpanannya.

Contoh berikut menunjukkan cara enable fungsi anonim IP untuk pelacak:

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

Fungsi IP anonimisasi dapat diatur kapan saja.

Pengujian dan Proses Debug

Google Analytics SDK untuk iOS menyediakan alat untuk mempermudah pengujian dan proses debug.

Uji Coba

SDK menyediakan flag dryRun yang jika ditetapkan, akan mencegah data apa pun dikirim ke Google Analytics. Tanda dryRun harus ditetapkan setiap kali Anda menguji atau men-debug penerapan dan tidak ingin data pengujian muncul dalam laporan Google Analytics.

Untuk menetapkan flag uji coba:

[[GAI sharedInstance] setDryRun:YES];

Pencatat

Protokol GAILogger disediakan untuk menangani pesan yang berguna dari SDK pada tingkat panjang ini: error, warning, info, dan verbose.

SDK melakukan inisialisasi implementasi Logger standar, yang secara default hanya akan mencatat pesan peringatan atau error ke konsol. Untuk menetapkan panjang Logger:

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

Implementasi kustom Logger juga dapat digunakan:

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

Contoh Lengkap

Contoh di bawah menunjukkan kode yang diperlukan untuk menginisialisasi penerapan Google Analytics dan mengirim satu tampilan layar.

Selanjutnya, tampilan layar diukur saat layar pertama ditampilkan kepada pengguna:

Biasanya, inisialisasi implementasi dapat dilakukan dari delegasi aplikasi, seperti dalam contoh berikut:

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

Kemudian, untuk mengukur tampilan layar saat tampilan ditampilkan kepada pengguna:

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