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

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

نظرة عامة على حزمة تطوير البرامج (SDK)

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

استخدِم حزمة تطوير البرامج (SDK) لتتبُّع الأجهزة الجوّالة لتتبُّع تطبيقات هاتفك باستخدام أنواع تفاعلات "إحصاءات Google" التالية:

تتبع مشاهدة الصفحة على الويب
مشاهدة الصفحة على الويب هي وسيلة عادية لقياس عدد الزيارات إلى موقع إلكتروني تقليدي. ولأنّ التطبيقات المتوافقة مع الأجهزة الجوّالة لا تحتوي على صفحات HTML، عليك تحديد وقت (وعدد مرات) تشغيل طلب مشاهدة الصفحة على الويب. وبما أنّ طلبات مشاهدات الصفحة على الويب مصمّمة لإعداد تقارير عن بُنى الأدلة، عليك تقديم أسماء وصفية للطلبات للاستفادة من تسمية مسارات الصفحة في تقارير المحتوى ضمن "إحصاءات Google". ستتم تعبئة الأسماء التي تختارها في تقارير "إحصاءات Google" كمسارات للصفحات على الرغم من أنّها ليست صفحات HTML في الواقع، ولكن يمكنك الاستفادة من ذلك لصالحك من خلال تنظيم المسارات لتوفير مجموعات إضافية لطلباتك.
تتبع الأحداث
في "إحصاءات Google"، يتم تصميم الأحداث لتتبُّع تفاعل المستخدمين مع عناصر صفحة الويب بشكل مختلف عن طلبات مشاهدات الصفحة على الويب. يمكنك استخدام ميزة "تتبُّع الأحداث" في "إحصاءات Google" لإجراء مكالمات إضافية سيتم إعداد تقارير عنها في قسم "تتبُّع الأحداث" في واجهة تقرير "إحصاءات Google". يتم تجميع الأحداث باستخدام الفئات، ويمكن أن تستخدم أيضًا تصنيفات كل فعالية، ما يوفّر المرونة في إعداد التقارير. على سبيل المثال، يمكن أن يتضمّن تطبيق وسائط متعددة الإجراءات تشغيل/إيقاف/إيقاف مؤقت لفئة الفيديو مع تخصيص تصنيف لكل اسم فيديو. بعد ذلك، ستجمّع تقارير "إحصاءات Google" الأحداث لجميع الأحداث التي تم وضع علامة عليها باستخدام فئة الفيديو. لمزيد من المعلومات عن "تتبُّع الأحداث"، اطّلِع على دليل تتبُّع الأحداث
.
تتبّع التجارة الإلكترونية
يمكنك استخدام ميزة تتبُّع التجارة الإلكترونية لتتبُّع معاملات سلة التسوّق وعمليات الشراء داخل التطبيق. لتتبُّع معاملة، يجب استدعاء طريقة addTransaction لإنشاء معاملة عامة، بالإضافة إلى طريقة addItem لكل منتج في سلة التسوق. وبعد جمع البيانات، يمكن عرضها في قسم "إعداد تقارير التجارة الإلكترونية" من واجهة "إحصاءات Google". لمزيد من المعلومات عن تتبُّع التجارة الإلكترونية، اطّلِع على دليل تتبُّع التجارة الإلكترونية.
المتغيرات المخصّصة
المتغيّرات المخصّصة هي علامات أزواج من الاسم والقيمة يمكنك إدراجها في رمز التتبّع لتحسين تتبُّع "إحصاءات Google". للحصول على مزيد من المعلومات عن كيفية استخدام المتغيّرات المخصّصة، اقرأ دليل المتغيّرات المخصّصة.
عدم التوافق مع NoThumb
تُوفّر حزمة تطوير البرامج (SDK) لهاتف iPhone حاليًا إصدار NoThumb مع تطبيق Library (المكتبة) بالإضافة إلى إصدار Thumb العادي. لاستخدام إصدار NoThumb من المكتبة، استخدِم الملف libGoogleAnalytics_NoThumb.a بدلاً من الملف libGoogleAnalytics.a.

البدء

المتطلّبات

لدمج إمكانات التتبّع في "إحصاءات Google" مع تطبيقك المتوافق مع iOS، ستحتاج إلى ما يلي:

ضبط إعدادات الجهاز

  • افتح Xcode وأنشئ مشروعًا جديدًا لنظام التشغيل iPhone.
  • اسحب GANTracker.h وlibGoogleAnalytics.a من دليل مكتبة حزمة تطوير البرامج (SDK) إلى مشروعك الجديد.
  • أدرج إطار عمل CFNetwork في مشروعك واربطه بـ libsqlite3.0.dylib.

يجب أن تعمل حزمة تطوير البرامج (SDK) لخدمة "إحصاءات Google" لتطبيقات الأجهزة الجوّالة مع أيّ جهاز iPhone أو iPod Touch يعمل بنظام التشغيل iOS 2.0 أو إصدار أحدث -- المكتبة متوافقة مع جميع إصدارات iOS التي تتوافق مع التطبيقات الأصلية.

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

استخدام حزمة تطوير البرامج (SDK)

قبل البدء في استخدام حزمة تطوير البرامج (SDK)، يجب أولاً إنشاء حساب مجاني على www.google.com/analytics وإنشاء موقع إلكتروني جديد في ذلك الحساب باستخدام عنوان URL مزيّف ولكن وصفي للموقع الإلكتروني (مثل http://mymobileapp.mywebsite.com). بعد إنشاء الموقع، يُرجى تدوين رقم تعريف الموقع الإلكتروني الذي تمّ إنشاؤه للموقع الذي تمّ إنشاؤه حديثًا أو الاحتفاظ بنسخة منه.

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

النماذج وأفضل الممارسات

يمكنك العثور على رمز نموذجي وأفضل الممارسات على code.google.com ضمن المشروع analytics-api-عيّنات.

مكتبة EasyTracker

تتوفر مكتبة EasyTracker. وهي توفّر إمكانية التتبّع على مستوى UIViewController والتطبيقات بدون أيّ جهد تقريبًا في التطوير. ويمكنك العثور عليه في القسم عمليات التنزيل ضمن مشروع analytics-api-عيّنات.

جارٍ بدء جهاز التتبُّع

شغِّل جهاز التتبُّع عن طريق استدعاء طريقة startTrackerWithAccountID على جهاز التتبُّع المفرد الذي تم الحصول عليه من خلال [GANTracker sharedTracker]. يكون من المريح غالبًا طلب هذه الطريقة مباشرةً من خلال طريقة applicationDidFinishLaunching الخاصة بتفويض تطبيقك. اجتياز معرّف الموقع الإلكتروني وفترة الإرسال المطلوبة والتفويض الاختياري. مثال:

#import "BasicExampleAppDelegate.h"

#import "GANTracker.h"

// Dispatch period in seconds
static const NSInteger kGANDispatchPeriodSec = 10;

@implementation BasicExampleAppDelegate

@synthesize window = window_;

- (void)applicationDidFinishLaunching:(UIApplication *)application {
  // **************************************************************************
  // PLEASE REPLACE WITH YOUR ACCOUNT DETAILS.
  // **************************************************************************
  [[GANTracker sharedTracker] startTrackerWithAccountID:@"UA-0000000-1"
                                        dispatchPeriod:kGANDispatchPeriodSec
                                              delegate:nil];

  NSError *error;
  if (![[GANTracker sharedTracker] setCustomVariableAtIndex:1
                                                       name:@"iPhone1"
                                                      value:@"iv1"
                                                  withError:&error]) {
    // Handle error here
  }

  if (![[GANTracker sharedTracker] trackEvent:@"my_category"
                                       action:@"my_action"
                                        label:@"my_label"
                                        value:-1
                                   withError:&error]) {
    // Handle error here
  }

  if (![[GANTracker sharedTracker] trackPageview:@"/app_entry_point"
                                   withError:&error]) {
    // Handle error here
  }

  [window_ makeKeyAndVisible];
}

- (void)dealloc {
  [[GANTracker sharedTracker] stopTracker];
  [window_ release];
  [super dealloc];
}

@end

تتبع مرات مشاهدة الصفحة على الويب والأحداث

يُعدّ تتبُّع مرّات مشاهدة الصفحة على الويب والأحداث أمرًا بسيطًا، فما عليك سوى استدعاء trackPageView من عنصر التتبُّع في كلّ مرّة تريد فيها تفعيل مشاهدة صفحة على الويب. يمكنك الاتصال بالرقم trackEvent لتسجيل حدث. لمزيد من المعلومات عن مرات مشاهدة الصفحة على الويب والأحداث، اطّلِع على مقالة نظرة عامة على حزمة تطوير البرامج (SDK) أعلاه.

استخدام المتغيرات المخصّصة

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

استخدام تتبّع التجارة الإلكترونية

هناك 4 طرق يمكنك استخدامها لتفعيل تتبُّع التجارة الإلكترونية في تطبيقك:

  • addTransaction
  • addItem
  • trackTransactions
  • clearTransactions

يؤدي طلب البيانات إلى addTransaction وaddItem إلى إضافة المعاملة أو العنصر إلى مخزن داخلي للتجارة الإلكترونية داخلي يمكن إضافة المزيد من العناصر والمعاملات إليه. عند الاتصال بـ trackTransactions فقط، سيتم إرسال المعاملات والعناصر إلى المرسِل وسيتم وضعها في قائمة انتظار لإرسالها إلى "إحصاءات Google".

لمحو المخزن المؤقت، يمكنك استدعاء الطريقة clearTransactions. ملاحظة: لا تذكر أي معاملات تم إرسالها سابقًا إلى المُرسل ولا أي معاملات جمعتها "إحصاءات Google".

يمكنك البدء باستخدام الرمز النموذجي التالي. 

  /**
   * The purchase was processed.  We will track the transaction and its associated line items
   * now, but only if the purchase has been confirmed.
   */
- (void) processPurchase:Purchase purchase {
  [[GANTracker sharedTracker] addTransaction:[purchase transactionId]
                                  totalPrice:[purchase totalPrice]
                                   storeName:[purchase store]
                                    totalTax:[purchase tax]
                                shippingCost:[purchase shipping]
                                   withError:&error];
  if (error) {
    // Handle error
  }
  for (PurchaseItem item in [purchase items]) {
    [[GANTracker sharedTracker] addItem:[purchase transactionId]
                                itemSKU:[item itemSKU]
                              itemPrice:[item price]
                              itemCount:[item count]
                           itemCategory:[item category]
                              withError:&error];
    if (error) {
      // Handle error
    }
  }

  if ([purchase isConfirmed]) {
    [[GANTracker sharedTracker] trackTransactions:&error];
  } else {
    // The purchase was denied or failed in some way.  We need to clear out
    // any data we've already put in the Ecommerce buffer.
    [[GANTracker sharedTracker] clearTransactions:&error];
  }
}

لمزيد من المعلومات عن التجارة الإلكترونية، يُرجى الاطّلاع على دليل تتبُّع التجارة الإلكترونية.

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

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

فيما يلي مثال على كيفية ضبطها:

 [[GANTracker sharedTracker] setAnonymizeIp:YES];

ويمكنك ضبط anonymizeIp في أي وقت.

إعداد معدّل البيانات في الملف الصوتي

يمكنك ضبط معدّل البيانات في الملف الصوتي باستخدام السمة sampleRate. إذا كان تطبيقك يحقِّق عددًا كبيرًا من زيارات "إحصاءات Google"، قد يؤدي ضبط معدّل العيّنة إلى منع إنشاء تقاريرك باستخدام عيّنات البيانات. يحدث أخذ العينات باستمرار على مستوى المستخدمين الفريدين، بحيث يكون هناك نزاهة في المؤشرات وإعداد التقارير عند تفعيل معدل العينات. المعلمة sampleRate هي عدد NSUInteger، ويمكن أن تتراوح قيمتها بين 0 و100، بشكل شامل. في ما يلي مثال يقلل من قيمة sampleRate إلى %95:

 [[GANTracker sharedTracker] setSampleRate:95];

يوقف المعدل 0 إنشاء النتائج، بينما يرسل المعدل 100 جميع البيانات إلى "إحصاءات Google". ومن الأفضل ضبط sampleRate قبل استدعاء أي طرق تتبُّع.

يمكنك الاطّلاع على مزيد من المعلومات عن أخذ العينات في دليل مفاهيم أخذ العينات.

أغانٍ مجمّعة

للتوفير في الاتصال واستهلاك البطارية، ننصحك بتجميع طلبات التتبّع في مجموعات. يمكنك استدعاء dispatch على عنصر التتبّع في أي وقت تريد فيه إجراء طلب مجمّع، ويمكنك إجراء ذلك يدويًا أو على فترات زمنية محدّدة.

المشاكل المعروفة

  • الإحالات/مصادر الزيارات: لا يمكن حاليًا تتبع مصدر الحملة/الإحالة لتنزيل تطبيق على جهاز iOS.
  • ننصح بشدة بعدم الاتصال بالرقم dispatch في الحالات التالية:
    • في طريقة applicationWillTerminate
    • في applicationDidEnterBackground
    • قبل الاتصال بـ stopTracker
    يمكن أن يؤدي ذلك إلى إرسال النتائج مرّتَين. بدلاً من ذلك، استخدِم طريقة dispatchSynchronous:.
  • قد يؤدي استدعاء طرق GANTracker على سلاسل محادثات مختلفة إلى حدوث أخطاء SQLite غامضة. تأكَّد من إجراء جميع المكالمات من سلسلة المحادثات نفسها.

    • تتبُّع الحملات

    التتبّع العام للحملة

    مع الإصدار 1.3 من حزمة Google Analytics SDK لنظام التشغيل iOS، يمكنك الآن تتبع إحالات الحملات. على سبيل المثال، إذا نفّذ تطبيقك مخطط عنوان URL مخصصًا، يمكنك إنشاء عنوان URL يحتوي على معلمات طلب البحث للحملة. عندما يتم تشغيل تطبيقك استجابةً لعنوان URL كهذا، يمكنك استرداد معلمات طلب البحث وتمريرها إلى setReferrer بحيث يتم تخزين المعلومات في "إحصاءات Google".

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

      [[GANTracker sharedTracker] setReferrer:referrer withError:&error];

    هناك قيدان لاستخدام هذه الميزة. أولاً، يجب الاتصال برقم startTrackerWithAccountID قبل الاتصال بـ setReferrer. عليك إجراء ذلك لأنّ قاعدة بيانات SQLite التي تستخدمها "إحصاءات Google" لم يتم إعدادها قبل طلب البيانات startTrackerWithAccountID وsetReferrer تحتاج إلى قاعدة البيانات تلك. إذا لم يتم الاتصال برقم startTrackerWithAccountID، سيظهر خطأ.

    يتمثل القيد الثاني في أن سلسلة الإحالة التي تم تمريرها إلى setReferrer تحتاج إلى أن تتبع تنسيقًا محددًا. ويجب أن يأخذ شكل مجموعة من معلمات عناوين URL، ويجب أن يتضمن معلمة gclid على الأقل أو واحدة من كل من utm_campaign وutm_medium وutm_source. وفي الحالة الثانية، يمكن أن تتضمّن أيضًا مَعلمتَي utm_term وutm_content.

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

    referrer = @“gclid=gclidValue”;

    قد تبدو سلسلة الإحالة اليدوية للحملة على النحو التالي:

    referrer = @“utm_campaign=campaign&utm_source=source&utm_medium=medium&utm_term=term&utm_content=content”;

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

    لاحظ أيضًا أنه ستبدأ جلسة جديدة عندما تقوم باستدعاء setReferrer وترجع إلى القيمة "true".

    المَعلمة مطلوبة الوصف أمثلة
    utm_campaign نعم اسم الحملة؛ يُستخدم لتحليل الكلمات الرئيسية لتحديد ترويج منتج معين أو حملة إستراتيجية معينة utm_campaign=spring_sale
    utm_source نعم مصدر الحملة؛ يُستخدم لتحديد محرك بحث أو نشرة إخبارية أو مصدر آخر utm_source=google
    utm_medium نعم وسيط الحملة؛ يُستخدم لتحديد وسيط مثل البريد الإلكتروني أو تكلفة النقرة. utm_medium=cpc
    utm_term لا عبارة الحملة؛ تُستخدم مع نتائج البحث المدفوعة لتوفير الكلمات الرئيسية للإعلانات utm_term=running+shoes
    utm_content لا محتوى الحملة؛ يُستخدم لاختبار A/B والإعلانات التي تستهدف المحتوى للتمييز بين الإعلانات أو الروابط التي تشير إلى عنوان URL نفسه. utm_content=logolink
    utm_content=textlink