إعداد متقدم

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

نظرة عامة

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

الإعداد

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

استخدام ملف إعداد

من الممكن أيضًا إعداد جهاز تتبع باستخدام ملف إعداد. مثال:

package com.google.android.apps.mobileplayground;

import android.app.Application;
import com.google.android.gms.analytics.GoogleAnalytics;
import com.google.android.gms.analytics.Tracker;
import java.util.HashMap;

/**
 * An extension to Application class to provide tracker for analytics purposes. Having the tracker
 * instances here allows all the activities to access the same tracker instances. The trackers can
 * be initialised on startup or when they are required based on performance requirements.
 */
public class AnalyticsSampleApp extends Application {

  // The following line should be changed to include the correct property id.
  private static final String PROPERTY_ID = "UA-XXXXX-Y";

  /**
   * Enum used to identify the tracker that needs to be used for tracking.
   *
   * A single tracker is usually enough for most purposes. In case you do need multiple trackers,
   * storing them all in Application object helps ensure that they are created only once per
   * application instance.
   */
  public enum TrackerName {
    APP_TRACKER, // Tracker used only in this app.
    GLOBAL_TRACKER, // Tracker used by all the apps from a company. eg: roll-up tracking.
    ECOMMERCE_TRACKER, // Tracker used by all ecommerce transactions from a company.
  }

  HashMap<TrackerName, Tracker> mTrackers = new HashMap<TrackerName, Tracker>();

  public AnalyticsSampleApp() {
    super();
  }
  synchronized Tracker getTracker(TrackerName trackerId) {
    if (!mTrackers.containsKey(trackerId)) {

      GoogleAnalytics analytics = GoogleAnalytics.getInstance(this);
      Tracker t = (trackerId == TrackerName.APP_TRACKER) ? analytics.newTracker(PROPERTY_ID)
          : (trackerId == TrackerName.GLOBAL_TRACKER) ? analytics.newTracker(R.xml.global_tracker)
              : analytics.newTracker(R.xml.ecommerce_tracker);
      mTrackers.put(trackerId, t);

    }
    return mTrackers.get(trackerId);
  }
}

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

يتم إرسال البيانات إلى "إحصاءات Google" باستخدام أدوات الإنشاء لضبط أزواج القيَم/المَعلمات من خلال طريقة التتبُّع send.

يوضِّح المثال التالي كيفية إرسال مشاهدة شاشة إلى "إحصاءات Google" من خلال إنشاء عرض للتطبيق واستدعاء طريقة الإرسال في أداة التتبُّع:

// Get tracker.
Tracker t = ((AnalyticsSampleApp) getActivity().getApplication()).getTracker(
    TrackerName.APP_TRACKER);

// Set screen name.
t.setScreenName(screenName);

// Send a screen view.
t.send(new HitBuilders.ScreenViewBuilder().build());

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

يمكنك استخدام بنية علامة العطف في Measurement Protocol لضبط القيم على نتيجة واحدة باستخدام HitBuilders.ScreenViewBuilder. لتعيين القيم على جميع النتائج اللاحقة، استخدم كائن المتتبع نفسه.

// Setting the content description field on a single hit using ampersand syntax.
tracker.send(new HitBuilders.ScreenViewBuilder()
  .set("&cd", "Home Screen")
  .build()
);

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

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

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

// Get tracker.
Tracker t = ((AnalyticsSampleApp) getActivity().getApplication()).getTracker(
    TrackerName.APP_TRACKER);

// Set screen name.
t.setScreenName(screenName);

// Send a screen view.
t.send(new HitBuilders.ScreenViewBuilder().build());

// This event will also be sent with the most recently set screen name.
// Build and send an Event.
t.send(new HitBuilders.EventBuilder()
    .setCategory(getString(categoryId))
    .setAction(getString(actionId))
    .setLabel(getString(labelId))
    .build());

// Clear the screen name field when we're done.
t.setScreenName(null);

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

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

في تطبيق الجوّال، يمكنك استخدام أدوات تتبع متعددة لإرسال البيانات إلى مواقع مختلفة:


public class MyApp extends Application {

  public void initTrackers() {
    GoogleAnalytics analytics = GoogleAnalytics.getInstance(this);

    globalTracker = analytics.newTracker(R.xml.global_tracker);
    ecommerceTracker = analytics.newTracker(R.xml.ecommerce_tracker);
  }

  public static Tracker globalTracker;
  public static Tracker ecommerceTracker;

  ...
}

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

أخذ العينات

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

على سبيل المثال، لتفعيل أخذ العينات من جهة العميل بمعدل %50، استخدِم المَعلمة التالية في ملف الإعداد:

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

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

mTracker.setSampleRate(50.0d);

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

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

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

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" من جهة العميل أو حذفها للمستخدمين النهائيين، يمكنك حذف ملف Client ID.

سيؤدي حذف ملف gaClientId إلى فرض إنشاء رقم تعريف عميل جديد وستستخدم جميع النتائج اللاحقة رقم تعريف العميل الجديد. لن يتم ربط البيانات السابقة بمعرّف العميل الجديد.

لحذف ملف gaClientId، استخدِم الإجراء Context.deleteFile:

context.deleteFile("gaClientId");

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

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

لتفعيل وظيفة إخفاء الهوية، استخدِم المَعلمة التالية في ملف الإعداد:

<string name="ga_anonymizeIp">true</string>

لتفعيل وظيفة إخفاء الهوية آليًا في جهاز التتبُّع، استخدِم طريقة setAnonymizeIp على النحو التالي: 

mTracker.setAnonymizeIp(true)

يمكن استدعاء طريقة setAnonymizeIp في أي وقت.

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

يوفّر الإصدار 4 من حزمة تطوير البرامج (SDK) لخدمة "إحصاءات Google" لنظام التشغيل 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);

مسجّل

ستعمل "إحصاءات Google" على تسجيل السجلّ ضمن علامة GAv4 باستخدام نظام Android Log. ويتم تفعيل مستويَي WARN وINFO فقط تلقائيًا. لتفعيل مستوى "تصحيح الأخطاء"، شغِّل أمر adb التالي على جهازك أو برنامج المحاكاة:

adb shell setprop log.tag.GAv4 DEBUG

لعرض رسائل "إحصاءات Google" فقط من logcat، يمكنك استخدام الأمر التالي:

adb logcat -v time -s GAv4

لمزيد من المعلومات، اطّلِع على مرجع مسجّل سجلّ "إحصاءات Google".