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

تُسهِّل حزمة تطوير البرامج (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 من"المكتبة"بالإضافة إلى إصدار Thumb. لاستخدام إصدار No التنقل من المكتبة، استخدِم الملف libGoogleAnalytics_NoThumb.a بدلاً من الملف libGoogleAnalytics.a.

البدء

المتطلّبات

لدمج "إحصاءات Google"&#39؛ إمكانيات التتبُّع مع تطبيق 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-sample في المشروع.

مكتبة EasyTracker

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

بدء أداة التتبُّع

يمكنك بدء أداة التتبّع من خلال طلب الإجراء 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 من حزمة تطوير البرامج (SDK) لخدمة "إحصاءات Google" لنظام التشغيل 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، لن يتم تغيير معلومات المُحيل وستظهر لك قيمة خطأ. تشير قيمة العرض true إلى أنه تم تعديل المُحيل وستتم إضافته إلى كل نتيجة من الآن فصاعدًا. ستظهر لك أيضًا رسالة خطأ تفيد بأنه يمكنك فحصها للحصول على تفاصيل بشأن المشكلة التي حدثت في حال تعذّر الاتصال.

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

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