حزمة تطوير البرامج (SDK) لخدمة "إحصاءات Google" لنظام التشغيل iOS - نقل البيانات إلى الإصدار 3

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

نظرة سريعة: الميزات الجديدة في الإصدار 3

تمت إعادة هيكلة واجهات برمجة التطبيقات في الإصدار الثالث لتصبح أكثر اتساقًا على مستوى الأنظمة الأساسية الأصلية ومنصات الويب. يجب على جميع مستخدمي الإصدار 2 ملاحظة هذه التغييرات:

  • يتم الآن إرسال النتائج باستخدام طريقة send:(NSDictionary *)params واحدة.
  • تمت إزالة ميزة إدارة الجلسات التلقائية من جهة العميل. يمكن ضبط مهلة الجلسة في واجهة الإدارة بدلاً من ذلك. مزيد من المعلومات
  • تم استبدال وضع تصحيح الأخطاء بـ Logger
  • جديد: تمت إضافة العلامة dryRun لمنع ظهور البيانات المُرسلة في التقارير.
  • جديد: تمت إضافة إتاحة استخدام العملات المحلية لنظام التشغيل iOS.

للحصول على القائمة الكاملة للتغييرات، يُرجى الاطّلاع على سجلّ التغييرات.

قبل البدء

قبل البدء في الترقية إلى الإصدار 3، ستحتاج إلى ما يلي:

مسارات الترقية

للبدء، اختَر مسار ترقية إلى الإصدار 3 من عملية التنفيذ الحالية:

من الإصدار 1.x إلى الإصدار 3

ننصح مستخدمي الإصدار 1.x من حزمة تطوير البرامج (SDK) لنظام التشغيل iOS من "إحصاءات Google" باتّباع دليل البدء للإصدار v3 لبدء استخدام الإصدار 3.

من الإصدار 2.x إلى الإصدار 3

على مستخدمي الإصدار 2.x اتّباع الخطوات التالية للترقية إلى الإصدار 3:

  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. لم تعد حزمة SDK ذات الإصدار 3 تبدأ جلسة جديدة تلقائيًا عند فتح التطبيق. وإذا كنت تريد الحفاظ على هذا السلوك من الإصدار 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). مزيد من المعلومات حول ضبط خيار الإيقاف على مستوى التطبيق

مَراجع

تقدم الأقسام التالية أمثلة مرجعية حول كيفية تعيين البيانات وإرسالها باستخدام الإصدار 3 من حزمة تطوير البرامج (SDK).

إرسال البيانات باستخدام القواميس في الإصدار 3

وفي الإصدار 3، يتم إرسال البيانات باستخدام طريقة send: واحدة تستخدم NSDictionary من حقول وقيم "إحصاءات Google" كوسيطة. يتم توفير فئة المرافق 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