الإصدار 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" و"إحصاءات 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-sample في المشروع.

مكتبة EasyTracker

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

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

يمكنك الحصول على الأداة الفردية للتتبُّع من خلال طلب 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 الواردة في قسم عمليات التنزيل من مشروع analytics-api-sample.

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

تتبّع مرات مشاهدة الصفحة والأحداث أمر بسيط: ما عليك سوى استدعاء 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 في كائن التتبع في أي وقت تريد فيه تقديم طلب مجمّع، ويمكنك إجراء ذلك يدويًا أو على فترات زمنية محددة.

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

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

    تتوافق حزمة تطوير البرامج (SDK) مع نوعَين من تتبُّع الحملات.

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

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

    يتيح الإصدار 1.6 من نظام التشغيل Android استخدام معلمة عنوان 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" من خلال Google Play، استخدِم أداة إنشاء عناوين URL أدناه لإنشاء رابط إحالة. استخدِم الرابط لتوجيه المستخدمين إلى تطبيقك. ستحلّل حزمة تطوير البرامج (SDK) لخدمة "إحصاءات Google" معلومات الإحالة وتسجِّلها تلقائيًا وتعبئها في تقرير "إحصاءات Google".

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

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

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