Google Analytics SDK עבור iOS - מעבר לגרסה 3

במדריך הזה מוסבר איך לשדרג לגרסה 3 של ה-SDK של Google Analytics ל-iOS.

'בקצרה': מה חדש ב-V3

ממשקי ה-API ב-V3 הוגדר מחדש כדי להיות עקביים יותר בין פלטפורמות מקוריות ואינטרנט. כל משתמשי V2 צריכים לשים לב לשינויים הבאים:

  • היטים נשלחים עכשיו באמצעות שיטת send:(NSDictionary *)params אחת.
  • הוסר הניהול האוטומטי של סשנים בצד הלקוח. במקום זאת, אפשר להגדיר את הזמן הקצוב לתפוגה של סשן בממשק הניהול. מידע נוסף
  • מצב ניפוי הבאגים הוחלף במצב Logger
  • חדש: הדגל dryRun נוסף כדי למנוע הצגה של נתונים שנשלחו בדוחות.
  • חדש: נוספה תמיכה במטבעות מקומיים ב-iOS.

רשימת השינויים המלאה מופיעה ב יומן השינויים.

לפני שתתחיל

לפני התחלת השדרוג לגרסה 3, יש צורך בדברים הבאים:

שדרוג נתיבים

כדי להתחיל, עליך לבחור נתיב שדרוג ל-v3 מההטמעה הנוכחית שלך:

v1.x עד v3

מומלץ למשתמשים ב-Google Analytics iOS SDK v1.x לפעול בהתאם להוראות במדריך לתחילת העבודה עם גרסה 3 כדי להתחיל להשתמש ב-v3.

v2.x עד v3

משתמשי v2.x צריכים לבצע את השלבים הבאים כדי לשדרג ל-v3:

  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. ניהול אוטומטי של סשנים בצד הלקוח הוסר בגרסה 3. אפשר להגדיר את פרק הזמן הקצוב לסשן בממשק הניהול וברירת המחדל שלו היא 30 דקות. באמצעות הפרמטר sessionControl אפשר גם להתחיל ולהפסיק סשנים באופן ידני. מידע נוסף על ניהול סשנים בגרסה 3

  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. v3 SDK כבר לא מתחיל סשן חדש באופן אוטומטי עם פתיחת האפליקציה. אם רוצים לשמר את ההתנהגות הזו מגרסה 2, צריך להטמיע לוגיקה משלך לבקרה על סשנים כשמשתמש מפעיל את האפליקציה:
    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]];
  7. הגדרת ביטול ההסכמה ברמת האפליקציה לא נשמרת ב-SDK וצריך להגדיר אותה בכל פעם שמפעילים את האפליקציה (ברירת המחדל היא NO). למידע נוסף על ביטול ההסכמה ברמת האפליקציה.

חומרי עזר

בקטעים הבאים מובאות דוגמאות שממחישות איך להגדיר ולשלוח נתונים באמצעות V3 SDK.

שליחת נתונים באמצעות מילונים בגרסה 3

בגרסה 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

הגדרת נתונים במכשיר המעקב בגרסה 3

אפשר גם להגדיר את הערכים ישירות ב-GAITracker באמצעות השיטה set:value:forKey. הערכים המוגדרים באופן ישיר חלים על כל ההיטים הבאים מאותו GAITracker: 

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

מידע נוסף על הגדרת הנתונים בגרסה 3