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

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

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

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

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

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

البدء

المتطلّبات

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

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

  • أضِف "libGoogleAnalytics.jar" إلى دليل /libs لمشروعك.
  • أضِف الأذونات التالية إلى ملف بيان AndroidManifest.xml لمشروعك:
    • <uses-permission android:name="android.permission.INTERNET" />
    • <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

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

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

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

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

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

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

مكتبة EasyTracker

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

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

احصل على جهاز التتبُّع المفرد من خلال الاتصال بـ GoogleAnalyticsTracker.getInstance(). استدعِ بعد ذلك طريقة startNewSession، لتمرير رقم تعريف الموقع الإلكتروني والنشاط الذي يتم تتبّعه. يمكنك استدعاء هذه الطريقة مباشرةً في طريقة "onCreate" ضمن "نشاطك" إذا كان تطبيقك يتضمّن "نشاطًا واحدًا فقط". مثال:

package com.google.android.apps.analytics.sample;

import com.google.android.apps.analytics.GoogleAnalyticsTracker;

import android.app.Activity;
import android.os.Bundle;
import android.view.View;
import android.view.View.OnClickListener;
import android.widget.Button;

public class TestActivity extends Activity {

  GoogleAnalyticsTracker tracker;

  @Override
  protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);

    tracker = GoogleAnalyticsTracker.getInstance();

    // Start the tracker in manual dispatch mode...
    tracker.startNewSession("UA-YOUR-ACCOUNT-HERE", this);

    // ...alternatively, the tracker can be started with a dispatch interval (in seconds).
    //tracker.startNewSession("UA-YOUR-ACCOUNT-HERE", 20, this);

    setContentView(R.layout.main);
    Button createEventButton = (Button)findViewById(R.id.NewEventButton);
    createEventButton.setOnClickListener(new OnClickListener() {
      @Override
      public void onClick(View v) {
        tracker.trackEvent(
            "Clicks",  // Category
            "Button",  // Action
            "clicked", // Label
            77);       // Value
      }
    });

    Button createPageButton = (Button)findViewById(R.id.NewPageButton);
    createPageButton.setOnClickListener(new OnClickListener() {
      @Override
      public void onClick(View v) {
        // Add a Custom Variable to this pageview, with name of "Medium" and value "MobileApp" and
        // scope of session-level.
        tracker.setCustomVar(1, "Navigation Type", "Button click", 2);
        // Track a page view. This is probably the best way to track which parts of your application
        // are being used.
        // E.g.
        // tracker.trackPageView("/help"); to track someone looking at the help screen.
        // tracker.trackPageView("/level2"); to track someone reaching level 2 in a game.
        // tracker.trackPageView("/uploadScreen"); to track someone using an upload screen.
        tracker.trackPageView("/testApplicationHomeScreen");
      }
    });

    Button quitButton = (Button)findViewById(R.id.QuitButton);
    quitButton.setOnClickListener(new OnClickListener() {
      @Override
      public void onClick(View v) {
        finish();
      }
    });

    Button dispatchButton = (Button)findViewById(R.id.DispatchButton);
    dispatchButton.setOnClickListener(new OnClickListener() {
      @Override
      public void onClick(View v) {
        // Manually start a dispatch, not needed if the tracker was started with a dispatch
        // interval.
        tracker.dispatch();
      }
    });
  }

  @Override
  protected void onDestroy() {
    super.onDestroy();
    // Stop the tracker when it is no longer needed.
    tracker.stopSession();
  }
}

إذا كانت لديك أنشطة متعدّدة في تطبيقك، يمكنك استخدام مكتبة EasyTracker Library المتوفرة في قسم عمليات التنزيل في مشروع analytics-api-عيّنات.

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

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

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

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

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

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

  • addTransaction
  • addItem
  • trackTransactions
  • clearTransactions

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

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

يمكنك البدء باستخدام الرمز النموذجي التالي. نفترض أنّه يتم استدعاء طريقة onPurchaseCompleted عند تأكيد عملية الشراء أو رفضها. 

  /**
   * The purchase was processed.  We will track the transaction and its associated line items
   * now, but only if the purchase has been confirmed.
   *
   * @param purchase A PurchaseObject containing all of the transaction information needed to
   *     send the ecommerce hit to Google Analytics.
   */
  public void onPurchaseCompleted(PurchaseObject purchase) {
    tracker.addTransaction(new Transaction.Builder(
        purchase.getTransactionId(),
        purchase.getTotal())
        .setStoreName(purchase.getStoreName())
        .setTotalTax(purchase.getTotalTax())
        .setShippingCost(purchase.getShippingCost())
        .build());
    for (PurchaseLineItem lineItem : purchase.getLineItems()) {
        tracker.addItem(new Item.Builder(
            purchase.getTransactionId(),
            lineItem.getItemSKU(),
            lineItem.getItemCost(),
            lineItem.getQuantity())
            .setItemName(lineItem.getItemName())
            .setItemCategory(lineItem.getItemCategory())
            .build());
    }
    if (purchase.isConfirmed()) {
      tracker.trackTransactions();
    } 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.
      tracker.clearTransactions();
    }
  }

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

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

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

يمكنك الاتصال بـ "setAnonymizeIp" في أي وقت.

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

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

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

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

أغانٍ مجمّعة

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

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

  • قد يؤدي استدعاء طرق GoogleAnalyticsTracker على سلاسل محادثات مختلفة إلى حدوث أخطاء غامضة. تأكَّد من إجراء جميع المكالمات من سلسلة المحادثات نفسها.

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

    تدعم حزمة SDK نوعين من تتبع الحملات.

    - تتبُّع حملات Google Play: يتيح لك هذا الخيار تتبُّع إحالات التثبيت من خلال Google Play.
    - التتبّع العام للحملات: يسمح لك هذا الخيار بتتبُّع أي حملة تحيل المستخدِمين إلى تطبيقك.

    تتبُّع حملات Google Play

    يتيح إصدار نظام التشغيل Android 1.6 استخدام مَعلمة عنوان URL referrer في روابط تنزيل الروابط إلى Google Play. تستخدم حزمة تطوير البرامج (SDK) لخدمة "إحصاءات Google" لنظام التشغيل Android هذه المَعلمة لتعبئة معلومات الحملة تلقائيًا في "إحصاءات Google" لتطبيقك. ويتيح ذلك تسجيل مصدر تثبيت التطبيق وربطه بمشاهدات الصفحة على الويب والأحداث المستقبلية، ما يمكن أن يكون مفيدًا في قياس فعالية إعلان معيّن لتطبيقك على سبيل المثال.

    يجب إضافة مقتطف الرمز التالي إلى ملف بيان AndroidManifest.xml الخاص بمشروعك من أجل تفعيل ميزة تتبُّع الإحالات:

    <!-- Used for install referrer tracking -->
<receiver android:name="com.google.android.apps.analytics.AnalyticsReceiver" android:exported="true">
  <intent-filter>
    <action android:name="com.android.vending.INSTALL_REFERRER" />
  </intent-filter>
</receiver>

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

    لإنشاء رابط الإحالة، يمكنك استخدام أداة إنشاء عناوين URL للحملات على Google Play. اسم الحزمة، ومصدر الحملة، ووسيط الحملة، واسم الحملة مطلوبة. للحصول على وصف تفصيلي لكل مَعلمة، يُرجى الاطّلاع على الجدول أدناه.

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

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

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

      tracker.setReferrer(referrer);

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

    يتمثل القيد الثاني في أن سلسلة الإحالة التي تم تمريرها إلى 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