الإعداد المتقدّم - الإصدار 2 من حزمة تطوير البرامج (SDK) لنظام التشغيل Android (الإصدار القديم)

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

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

نظرة عامة

تستخدم حزمة تطوير البرامج (SDK) لخدمة "إحصاءات Google" لنظام التشغيل Android فئتَين لإدارة الحالة العامة للتنفيذ وإرسال البيانات إلى خوادم "إحصاءات Google". يضم تطبيق EasyTracker هذه الفئات لتقديم تهيئة مبسطة وإدارة الجلسة:

• GoogleAnalytics: هي عبارة عن طن واحد يعالج الحالة العامة لعملية التنفيذ، بما في ذلك الحصول على عناصر Tracker.
• Tracker – الفئة التي ترسل إليها البيانات إلى "إحصاءات Google".

على سبيل المثال، لقياس عرض Activity بسيط:

import android.app.Activity

import com.google.analytics.tracking.android.GoogleAnalytics
import com.google.analytics.tracking.android.Tracker

/**
 * A simple Activity that sends a screen view to Google Analytics
 * when it is displayed to the user.
 */
public class HomeScreen extends Activity {

  private Tracker mGaTracker;
  private GoogleAnalytics mGaInstance;

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

    // Get the GoogleAnalytics singleton. Note that the SDK uses
    // the application context to avoid leaking the current context.
    mGaInstance = GoogleAnalytics.getInstance(this);

    // Use the GoogleAnalytics singleton to get a Tracker.
    mGaTracker = mGaInstance.getTracker("UA-XXXX-Y"); // Placeholder tracking ID.
    ... // The rest of your onCreate() code.
  }

  @Override
  public void onStart() {
    super.onStart();

    // Send a screen view when the Activity is displayed to the user.
    mGaTracker.sendView("/HomeScreen");
  }
}

استخدام أجهزة تتبُّع متعددة

بدءًا من الإصدار 2 من حزمة SDK، يمكنك استخدام أدوات تتبع متعددة في عملية تنفيذ واحدة، واحدة لكل رقم تعريف تتبع فريد. تشترك جميع أجهزة التتبُّع في الولاية العالمية نفسها التي تحتفظ بها شركة GoogleAnalytics المفردة.

في المثال التالي، يتم إرسال مشاهدة الشاشة إلى موقعَين منفصلَين باستخدام أداتَي تتبُّع، لكلّ منهما رقم تعريف موقع فريد:

import android.app.Activity

import com.google.analytics.tracking.android.GoogleAnalytics
import com.google.analytics.tracking.android.Tracker

/**
 * A simple Activity that sends a screen view to Google Analytics
 * when it is displayed to the user.
 */
public class HomeScreen extends Activity {

  private GoogleAnalytics mGaInstance;
  private Tracker mGaTracker1;
  private Tracker mGaTracker2;

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

    // Get the GoogleAnalytics singleton.
    mGaInstance = GoogleAnalytics.getInstance(this);

    // Use the GoogleAnalytics singleton to get two Trackers with
    // unique property IDs.
    mGaTracker1 = mGaInstance.getTracker("UA-XXXX-Y");
    mGaTracker2 = mGaInstance.getTracker("UA-XXXX-Z");

    ... // The rest of your onCreate() code.
  }

  @Override
  public void onStart() {
    super.onStart();

    // Send a screen view to "UA-XXXX-Y" the Activity is displayed to the user.
    mGaTracker1.sendView("/HomeScreen");

    // Send another screen view to the second property, "UA-XXXX-Z".
    mGaTracker2.sendView("/Home");
  }
}

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

أداة التتبُّع التلقائية

على الرغم من أنّ عملية التنفيذ قد تستخدم أدوات تتبّع متعدّدة، إلّا أنّها تتضمّن أداة تتبُّع تلقائية واحدة في جميع أنحاء العالم. يصبح أوّل Tracker تم استرداده هو جهاز التتبُّع التلقائي.

للحصول على جهاز التتبُّع التلقائي، استخدِم:

// Get singleton.
GoogleAnalytics myInstance = GoogleAnalytics.getInstance(this);

// Get default tracker.
Tracker myDefault = myInstance.getDefaultTracker();

لضبط جهاز التتبُّع التلقائي، استخدِم:

// First get a tracker using a new property ID.
Tracker newTracker = myInstance.getTracker("UA-XXXX-2");

// Then make newTracker the default tracker globally.
myInstance.setDefaultTracker(newTracker);

الإرسال

تتم إدارة إعدادات الإرسال من خلال GAServiceManager سينغلتون. لضبط فترة الإرسال:

// Set dispatch period to 30 seconds.
GAServiceManager.getInstance().setDispatchPeriod(30);

للإرسال يدويًا خارج الفاصل الزمني المجدوَل:

// Manually dispatch any queued hits.
GAServiceManager.getInstance().dispatch();

أخذ العينات

يمكنك تفعيل أخذ العينات من جهة العميل للحدّ من عدد النتائج المرسَلة إلى "إحصاءات Google". إذا كان تطبيقك يضم عددًا كبيرًا من المستخدمين أو يرسل كمية كبيرة من البيانات إلى "إحصاءات Google"، سيساعد تفعيل أخذ العينات على ضمان إعداد التقارير بدون انقطاع.

على سبيل المثال، لتفعيل أخذ العينات من جهة العميل بمعدل 50% عبر EasyTracker وXML، استخدِم المعلمة التالية في ملف analytics.xml:

<string name="ga_sampleFrequency">50.0</string>

يمكنك أيضًا تفعيل أخذ العينات من جهة العميل آليًا:

// Get tracker from singleton.
GoogleAnalytics gaInstance = GoogleAnalytics.getInstance(this);
Tracker tracker = gaInstance.getTracker("UA-XXXX-Y"); // Placeholder property ID.

// Set a sample rate of 50%.
tracker.setSampleRate(50.0d);

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

الإيقاف على مستوى التطبيق

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

للحصول على إعداد الإيقاف على مستوى التطبيق، استخدِم:

// Get singleton.
GoogleAnalytics myInstance = GoogleAnalytics.getInstance(this);

// Get the app opt out preference using an AppOptOutCallback.
myInstance.requestAppOptOut(new AppOptOutCallback() {
   @Override
   public void reportAppOptOut(boolean optOut) {
     if (optOut) {
     ... // Alert the user that they've opted out.
     }
   });
}

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

myInstance.setAppOptOut(appPreferences.userOptOut);

الاختبار وتصحيح الأخطاء

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

لتفعيل وضع تصحيح الأخطاء باستخدام EasyTracker، أضِف ما يلي إلى ملف موارد analytics.xml:

<bool name="ga_debug">true</bool>

لتفعيل وضع تصحيح الأخطاء آليًا، استخدِم:

// Get singleton using application context.
GoogleAnalytics myInstance = GoogleAnalytics.getInstance(this);

// Enable debug mode.
myInstance.setDebug(true);

ستتم طباعة الناتج إلى logcat باستخدام العلامة GAV2.