الإعداد المتقدّم - حزمة تطوير البرامج (SDK) لنظام التشغيل iOS

يقدم هذا المستند نظرة عامة على بعض ميزات التهيئة المتقدمة لحزمة SDK من Google Analytics لنظام التشغيل iOS،

نظرة عامة

توفّر حزمة تطوير البرامج (SDK) لخدمة "إحصاءات Google" لنظام التشغيل iOS فئة GAITracker لضبط البيانات وإرسالها إلى "إحصاءات Google"، بالإضافة إلى فئة GAI مفردة ( GAI) تعمل كواجهة لقيم الإعدادات العامة لعملية التنفيذ.

الإعداد

قبل قياس أي بيانات، يجب إعداد جهاز تتبُّع واحد على الأقل عبر GoogleAnalytics مفرد من خلال توفير اسم لجهاز التتبُّع ورقم تعريف موقع على "إحصاءات Google":

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

يمكن الآن استخدام جهاز التتبُّع هذا لضبط البيانات وإرسالها إلى "إحصاءات Google".

إعداد البيانات وإرسالها

يتم إرسال البيانات إلى "إحصاءات Google" عن طريق إعداد خرائط لأزواج المَعلمات في أداة التتبُّع وإرسالها عبر طريقتَي set و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];

تبسّط الفئة GAIDictionaryBuilder عملية إنشاء النتائج، ويُنصح بها في معظم حالات الاستخدام. يمكننا هنا إرسال نفس مشاهدة الشاشة مع عدد أقل من الأسطر من الرمز:

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

بنية علامة العطف في Measurement Protocol

يمكن أيضًا ضبط القيم على نتيجة واحدة، عن طريق ضبط القيمة على Builder، أو على جميع النتائج اللاحقة، من خلال ضبطها على كائن المتتبّع نفسه، باستخدام بنية علامة العطف في 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]];

للاطّلاع على القائمة الكاملة لمَعلمات Measurement Protocol المتوفّرة، اطّلِع على مرجع مَعلمات Measurement Protocol.

تطبيق القيم على نتائج متعددة

وفي حال تحديد أي قيم في أداة التتبُّع مباشرةً، سيستمر تطبيقها على نتائج متعددة، كما في هذا المثال:

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

يجب ضبط القيم التي تريد الاحتفاظ بها على مستوى نتائج متعدّدة فقط مباشرةً على أداة التتبُّع. قد يكون ضبط اسم الشاشة على أداة التتبُّع أمرًا منطقيًا، لأنّه يمكن تطبيق القيمة نفسها على مشاهدة الشاشة ونتائج الأحداث اللاحقة. ومع ذلك، لا يُنصح بإعداد حقل مثل نوع النتيجة على أداة التتبُّع، لأنّ ذلك من المحتمل أن يتغيّر مع كل نتيجة.

استخدام أجهزة تتبُّع متعددة

يمكن استخدام أدوات تتبُّع متعدّدة في عملية تنفيذ واحدة، ما قد يكون مفيدًا لإرسال البيانات إلى مواقع متعدّدة على النحو التالي:

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.

ستستخدم ميزات القياس التلقائي، مثل قياس الشاشة التلقائي وقياس الاستثناءات غير المرصود، أداة تتبُّع واحدة فقط لإرسال البيانات إلى "إحصاءات Google". إذا كنت تستخدم هذه الميزات وتريد إرسال البيانات باستخدام أجهزة تتبع أخرى، عليك إجراء ذلك يدويًا.

يُرجى العلم أنّ قياس الشاشة التلقائي يستخدم أداة التتبُّع المحدّدة في السمة tracker الخاصة بـ GAITrackedViewController. يستخدم قياس الاستثناء غير المتحدي أداة التتبُّع التلقائية المحدَّدة في مثيل GAI.

استخدام أداة التتبُّع التلقائية

تحتفظ "إحصاءات Google" بأداة تتبُّع تلقائية. جهاز التتبُّع الأول الذي تم إعداده يصبح جهاز التتبُّع التلقائي ولكن قد يتم تجاهله:

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

أخذ العينات

يمكنك تفعيل أخذ العينات من جهة العميل للحدّ من عدد النتائج المرسَلة إلى "إحصاءات Google". إذا كان تطبيقك يضم عددًا كبيرًا من المستخدمين أو يرسل كمية كبيرة من البيانات إلى "إحصاءات Google"، سيساعد تفعيل أخذ العينات على ضمان إعداد التقارير بدون انقطاع.

على سبيل المثال، لتنفيذ أخذ العينات من جهة العميل بمعدل 50%، استخدِم الرمز التالي:

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

لتجنُّب الإبلاغ عن التناقضات، يجب أن يحتوي كل ملف شخصي (ملفات شخصية) للتطبيق على بيانات تم جمعها بمعدل أخذ العينات نفسه. إذا كانت الإصدارات المختلفة من تطبيقك تستخدم معدلات تحليل عيّنات مختلفة، عليك ضبط فلاتر الملف الشخصي (الملف الشخصي) باستخدام سمة إصدار التطبيق للاحتفاظ بالبيانات من كل إصدار من إصدارات تطبيقك بشكل منفصل.

الإيقاف على مستوى التطبيق

يمكنك تفعيل علامة إيقاف على مستوى التطبيق من شأنها إيقاف "إحصاءات Google" في التطبيق بأكمله. تجدر الإشارة إلى أنّه يجب ضبط هذه العلامة في كل مرة يتم فيها بدء تشغيل التطبيق وسيتم ضبطها تلقائيًا على NO.

للحصول على إعداد الإيقاف على مستوى التطبيق، استخدِم:

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

لضبط خيار الإيقاف على مستوى التطبيق، استخدِم:

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

حذف بيانات المستخدمين من جهة العميل

إذا كنت بحاجة إلى إعادة ضبط البيانات من جهة العميل في "إحصاءات Google" أو حذفها للمستخدمين النهائيين، يمكنك حذف ملفات "إحصاءات Google" أو إعداد معرِّف عميل جديد.

الخيار 1: حذف ملفات "إحصاءات Google"

إذا لم يضبط تطبيقك معرّف العميل بشكل صريح للمستخدم النهائي، يمكنك فرض إنشاء معرّف عميل جديد من خلال حذف ملفات "إحصاءات Google" المستخدَمة لتخزين معرّف العميل.

يمكن استخدام الطريقة التالية كمثال لحذف ملفات "إحصاءات Google". يجب تنفيذ الطريقة قبل إعداد "إحصاءات Google":

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

يجب حذف ملفات "إحصاءات Google" قبل إعداد [GAI sharedInstance].

الخيار 2: ضبط رقم تعريف عميل جديد

يمكنك إنشاء معرِّف عميل فريد جديد وضبطه. ستستخدم جميع النتائج اللاحقة معرّف العميل الجديد ولن يتم ربط البيانات السابقة برقم تعريف العميل الجديد.

نفِّذ الرمز التالي لإنشاء معرِّف عميل جديد وإعداده:

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

إذا قرّرت ضبط معرّف عميل بشكل صريح بدلاً من إنشاء معرّف عشوائي، تأكَّد من أنّه سلسلة UUID صالحة (الإصدار 4) كما هو موضّح في https://goo.gl/0dlrGx.

في حال تفعيل IDFA (معرّف المعلِنين)، سيؤدي ضبط معرّف عميل جديد إلى استبداله فورًا بمعرّف عميل جديد يتم إنشاؤه عشوائيًا. إذا كنت تحتاج إلى ضبط معرّف عميل معيّن وتفعيل معرّف المعلِنين (IDFA)، يعني ذلك أنّه لا يُنصح باستخدام هذا الخيار. بدلاً من ذلك، عليك استخدام الخيار 1: حذف ملفات "إحصاءات Google" لإعادة ضبط Client ID.

إخفاء هوية عناوين IP

يؤدي تفعيل وظيفة إخفاء الهوية إلى إعلام "إحصاءات Google" بإخفاء هوية معلومات عنوان IP التي أرسلتها حزمة تطوير البرامج (SDK) عن طريق إزالة آخر ثُماني بتات من عنوان IP قبل توفُّره.

يوضّح المثال التالي كيفية enable وظيفة إخفاء الهوية في جهاز التتبُّع:

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

يمكن ضبط وظيفة إخفاء الهوية لعنوان IP في أي وقت.

الاختبار وتصحيح الأخطاء

توفر حزمة Google Analytics SDK لنظام التشغيل iOS أدوات لتسهيل الاختبار وتصحيح الأخطاء.

تشغيل اختباري

توفِّر حزمة تطوير البرامج (SDK) علامة dryRun، عند ضبطها، تمنع إرسال أي بيانات إلى "إحصاءات Google". يجب ضبط العلامة dryRun كلما تختبر عملية تنفيذ أو تصححها، ولا تريد ظهور بيانات الاختبار في تقارير "إحصاءات Google".

لضبط علامة التشغيل التجريبي:

[[GAI sharedInstance] setDryRun:YES];

مسجّل

يتم توفير بروتوكول GAILogger للتعامل مع الرسائل المفيدة من حزمة تطوير البرامج (SDK) بمستويات الإسهاب التالية: error وwarning وinfo وverbose.

تعمل حزمة تطوير البرامج (SDK) على إعداد عملية تنفيذ علامة Logger عادية، ولن تسجِّل تلقائيًا سوى رسائل التحذير أو رسائل الخطأ إلى وحدة التحكّم. لضبط مستوى الإسهاب في Logger:

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

يمكن أيضًا استخدام عمليات التنفيذ المخصّصة للسمة Logger:

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

مثال كامل

يوضّح المثال أدناه الرمز المطلوب لإعداد عملية تنفيذ "إحصاءات Google" وإرسال مشاهدة شاشة واحدة.

بعد ذلك، يتم قياس مشاهدة الشاشة عند عرض الشاشة الأولى للمستخدم:

يمكن عادةً إعداد عملية التنفيذ من خلال تفويض التطبيق، كما في المثال التالي:

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

وبعد ذلك، لقياس مشاهدة الشاشة عند عرض طريقة عرض للمستخدم:

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