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

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

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

نظرة عامة

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

الإعداد

قبل قياس أي بيانات، يجب إعداد جهاز تتبُّع واحد على الأقل باستخدام GoogleAnalytics طن واحد من خلال توفير Context ورقم تعريف موقع على "إحصاءات Google":

// Initialize a tracker using a Google Analytics property ID.
GoogleAnalytics.getInstance(this).getTracker("UA-XXXX-Y")

يمكن الآن استخدام جهاز التتبُّع هذا لضبط البيانات وإرسالها إلى "إحصاءات Google".

إعداد البيانات وإرسالها

يتم إرسال البيانات إلى "إحصاءات Google" عن طريق إعداد خرائط لأزواج المَعلمات في أداة التتبُّع وإرسالها عبر طريقتَي set وsend:

/*
 * Send a screen view to Google Analytics by setting a map of parameter
 * values on the tracker and calling send.
 */
Tracker tracker = GoogleAnalytics.getInstance(this).getTracker("UA-XXXX-Y");

HashMap<String, String> hitParameters = new HashMap<String, String>();
hitParameters.put(Fields.HIT_TYPE, "appview");
hitParameters.put(Fields.SCREEN_NAME, "Home Screen");

tracker.send(hitParameters);

تبسّط الفئة MapBuilder عملية إنشاء النتائج، ويُنصح بها في معظم حالات الاستخدام. يمكننا هنا إرسال نفس مشاهدة الشاشة مع عدد أقل من الأسطر من الرمز:

// Sending the same screen view hit using MapBuilder.createAppView()
tracker.send(MapBuilder
  .createAppView()
  .set(Fields.SCREEN_NAME, "Home Screen")
  .build()
);

بنية علامة العطف في Measurement Protocol

يمكن أيضًا ضبط القيم على نتيجة واحدة، عن طريق ضبط القيمة على Builder، أو على جميع النتائج اللاحقة، من خلال ضبطها على كائن المتتبّع نفسه، باستخدام بنية علامة العطف في Measurement Protocol:

// Setting the content description field on a single hit using ampersand syntax.
tracker.send(MapBuilder
  .createAppView()
  .set(Fields.SCREEN_NAME, "Home Screen")
  .build()
);

للاطّلاع على القائمة الكاملة لمَعلمات Measurement Protocol المتوفّرة، اطّلِع على مرجع مَعلمات Measurement Protocol.

تطبيق القيم على نتائج متعددة

وفي حال تحديد أي قيم في أداة التتبُّع مباشرةً، سيستمر تطبيقها على نتائج متعددة، كما في هذا المثال:

// Set screen name on the tracker to be sent with all hits.
tracker.set(Fields.SCREEN_NAME, "Home Screen");

// Send a screen view for "Home Screen"
tracker.send(MapBuilder
    .createAppView()
    .build()
);

// This event will also be sent with &cd=Home%20Screen.
tracker.send(MapBuilder
    .createEvent("UX", "touch", "menuButton", null)
    .build()
);

// Clear the screen name field when we're done.
tracker.set(Fields.SCREEN_NAME, null);

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

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

يمكن استخدام أدوات تتبُّع متعدّدة في عملية تنفيذ واحدة، ما قد يكون مفيدًا لإرسال البيانات إلى مواقع متعدّدة على النحو التالي:

Tracker t1 = GoogleAnalytics.getInstance(this).getTracker("UA-XXXX-1");

// Trackers may be named. By default, name is set to the property ID.
Tracker t2 = GoogleAnalytics.getInstance(this).getTracker("altTracker", "UA-XXXX-2";

t1.set(Fields.SCREEN_NAME, "Home Screen");
t2.set(Fields.SCREEN_NAME, getClass().toString());

// Send screen view to UA-XXXX-1.
t1.send(MapBuilder
   .createAppView()
   .build()
);

// Send screen view to UA-XXXX-2.
t2.send(MapBuilder
   .createAppView()
   .build()
);

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

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

تحتفظ "إحصاءات Google" بأداة تتبُّع تلقائية. جهاز التتبُّع الأول الذي تم إعداده يصبح جهاز التتبُّع التلقائي ولكن قد يتم تجاهله:

// Tracker t1 becomes the default tracker because it is initialized first.
Tracker t1 = GoogleAnalytics.getInstance(this).getTracker("UA-XXXX-1");
Tracker t2 = GoogleAnalytics.getInstance(this).getTracker("UA-XXXX-2");


// Returns tracker t1.
Tracker defaultTracker = GoogleAnalytics.getInstance(this).getDefaultTracker();

// Hit sent to UA-XXXX-1.
defaultTracker.send(MapBuilder
    .createAppView()
    .set(Fields.SCREEN_NAME, "Home Screen")
    .build()
);

// Override the default tracker.
GoogleAnalytics.getInstance(this).setDefaultTracker(t2);

// Now this call returns tracker t2.
defaultTracker = GoogleAnalytics.getInstance(this).getDefaultTracker();

// Hit sent to UA-XXXX-2.
defaultTracker.send(MapBuilder
    .createAppView()
    .set(Fields.SCREEN_NAME, getClass().toString())
    .build()
);

أخذ العينات

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

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

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

لتفعيل طريقة أخذ العيّنات من جهة العميل آليًا لجهاز التتبُّع:

mTracker.set(Fields.SAMPLE_RATE, 50.0d);

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

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

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

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

boolean isOptedOut = GoogleAnalytics.getInstance(this).getAppOptOut();

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

GoogleAnalytics.getInstance(this).setAppOptOut(true);

في عملية التنفيذ النموذجية، قد يتحقّق التطبيق من حدوث تغيير في SharedPreferences، ويعدِّل إعداد إيقاف "إحصاءات Google" وفقًا لذلك:

SharedPreferences userPrefs = PreferenceManager.getDefaultSharedPreferences(this);

userPrefs.registerOnSharedPreferenceChangeListener(new SharedPreferences.OnSharedPreferenceChangeListener () {

  @Override
  public void onSharedPreferenceChanged(SharedPreferences sharedPreferences,
      String key) {

    if (key.equals(TRACKING_PREF_KEY)) {
      GoogleAnalytics.getInstance(getApplicationContext()).setAppOptOut(sharedPreferences.getBoolean(key, false));
    } else {
    // Any additional changed preference handling.
    }
  }
});

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

توفر حزمة Google Analytics SDK لنظام التشغيل Android أدوات لتسهيل الاختبار وتصحيح الأخطاء.

تشغيل اختباري

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

لضبط علامة التشغيل التجريبي:

// When dry run is set, hits will not be dispatched, but will still be logged as
// though they were dispatched.
GoogleAnalytics.getInstance(this).setDryRun(true);

مسجّل

يتم توفير واجهة Logger لمعالجة الرسائل المفيدة من حزمة تطوير البرامج (SDK) بالمستويات التالية: error وwarning وinfo وverbose.

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

// Set the log level to verbose.
GoogleAnalytics.getInstance(this).getLogger()
    .setLogLevel(LogLevel.VERBOSE);

يمكن أيضًا استخدام عمليات التنفيذ المخصّصة للسمة Logger:

// Provide a custom logger.
GoogleAnalytics.getInstance(this).setLogger(new CustomLogger ());

مثال كامل

يوضّح المثال أدناه الرمز المطلوب لإعداد عملية تنفيذ "إحصاءات Google" وإرسال مشاهدة شاشة واحدة.

package com.example.app;

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

import android.app.Application;
import android.content.SharedPreferences;
import android.preference.PreferenceManager;


/*
 * An advanced Google Analytics implementation may be initialized
 * in a subclass of Application. Note that this example assumes data
 * only needs to be sent to a single Google Analytics property ID.
 */
public class MyApp extends Application {

  private static GoogleAnalytics mGa;
  private static Tracker mTracker;

  /*
   * Google Analytics configuration values.
   */
  // Placeholder property ID.
  private static final String GA_PROPERTY_ID = "UA-XXXX-Y";

  // Dispatch period in seconds.
  private static final int GA_DISPATCH_PERIOD = 30;

  // Prevent hits from being sent to reports, i.e. during testing.
  private static final boolean GA_IS_DRY_RUN = false;

  // GA Logger verbosity.
  private static final LogLevel GA_LOG_VERBOSITY = LogLevel.INFO;

  // Key used to store a user's tracking preferences in SharedPreferences.
  private static final String TRACKING_PREF_KEY = "trackingPreference";


  /*
   * Method to handle basic Google Analytics initialization. This call will not
   * block as all Google Analytics work occurs off the main thread.
   */
  private void initializeGa() {
    mGa = GoogleAnalytics.getInstance(this);
    mTracker = mGa.getTracker(GA_PROPERTY_ID);

    // Set dispatch period.
    GAServiceManager.getInstance().setLocalDispatchPeriod(GA_DISPATCH_PERIOD);

    // Set dryRun flag.
    mGa.setDryRun(GA_IS_DRY_RUN);

    // Set Logger verbosity.
    mGa.getLogger().setLogLevel(GA_LOG_VERBOSITY);

    // Set the opt out flag when user updates a tracking preference.
    SharedPreferences userPrefs = PreferenceManager.getDefaultSharedPreferences(this);
    userPrefs.registerOnSharedPreferenceChangeListener(new SharedPreferences.OnSharedPreferenceChangeListener () {
      @Override
      public void onSharedPreferenceChanged(SharedPreferences sharedPreferences,
          String key) {
        if (key.equals(TRACKING_PREF_KEY)) {
          GoogleAnalytics.getInstance(getApplicationContext()).setAppOptOut(sharedPreferences.getBoolean(key, false));
        }
      }
    });
  }

  @Override
  public void onCreate() {
    super.onCreate();
    initializeGa();
  }

  /*
   * Returns the Google Analytics tracker.
   */
  public static Tracker getGaTracker() {
    return mTracker;
  }

  /*
   * Returns the Google Analytics instance.
   */
  public static GoogleAnalytics getGaInstance() {
    return mGa;
  }
}

بعد ذلك، يتم قياس مشاهدة الشاشة عند عرض الشاشة الأولى للمستخدم:

package com.example.app

import android.app.Activity

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

  private static final String SCREEN_LABEL = "Home Screen";

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

    // Fields set on a tracker persist for all hits, until they are
    // overridden or cleared by assignment to null.
    MyApp.getGaTracker().set(Fields.SCREEN_NAME, SCREEN_LABEL);
  }

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

    // Send a screen view when the Activity is displayed to the user.
    MyApp.getGaTracker().send(MapBuilder
        .createAppView.build());
  }
}