پیکربندی پیشرفته

این سند نمای کلی برخی از ویژگی‌های پیکربندی پیشرفته Google Analytics SDK v4 برای Android را ارائه می‌کند.

بررسی اجمالی

Google Analytics SDK v4 برای Android یک کلاس Tracker برای تنظیم و ارسال داده ها به Google Analytics و یک GoogleAnalytics تکی را ارائه می دهد که به عنوان رابطی برای مقادیر پیکربندی جهانی پیاده سازی شما عمل می کند.

مقداردهی اولیه

قبل از اندازه‌گیری داده‌ها، باید حداقل یک ردیاب را از طریق GoogleAnalytics singleton با ارائه یک شی Context و یک شناسه ویژگی Google Analytics مقداردهی اولیه کنید. برای جزئیات، به مرجع GoogleAnalytics مراجعه کنید.

با استفاده از یک فایل پیکربندی

همچنین می توان یک ردیاب را با استفاده از یک فایل پیکربندی مقداردهی اولیه کرد. مثلا:

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 Analytics ارسال می‌شوند تا جفت‌های پارامتر-مقدار را تنظیم کنند و آنها را از طریق روش send ردیاب ارسال کنند.

مثال زیر نحوه ارسال نمای صفحه نمایش به Google Analytics را با ایجاد نمای برنامه و فراخوانی روش ارسال ردیاب نشان می دهد:

// 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());

پروتکل اندازه گیری آمپرس و نحو

می‌توانید از دستور و دستور پروتکل اندازه‌گیری برای تنظیم مقادیر روی یک ضربه با HitBuilders.ScreenViewBuilder استفاده کنید. برای تنظیم مقادیر در تمام بازدیدهای بعدی، از خود شی ردیاب استفاده کنید.

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

برای لیست کامل پارامترهای پروتکل اندازه گیری موجود، به مرجع پارامتر پروتکل اندازه گیری مراجعه کنید.

اعمال مقادیر برای بازدیدهای متعدد

هر مقداری که مستقیماً روی ردیاب تنظیم شده باشد، باقی می ماند و برای چندین بازدید اعمال می شود، مانند این مثال:

// 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 Analytics، می‌توانید نمونه‌گیری سمت مشتری را فعال کنید. اگر برنامه شما تعداد زیادی کاربر دارد یا حجم زیادی از داده ها را به Google Analytics ارسال می کند، فعال کردن نمونه گیری به اطمینان از گزارش بدون وقفه کمک می کند.

به عنوان مثال، برای فعال کردن نمونه گیری سمت مشتری با نرخ 50٪، از پارامتر زیر در فایل پیکربندی خود استفاده کنید:

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

برای فعال کردن نمونه‌برداری سمت کلاینت به صورت برنامه‌ای برای یک ردیاب:

mTracker.setSampleRate(50.0d);

انصراف در سطح برنامه

می‌توانید یک پرچم انصراف در سطح برنامه را فعال کنید که Google Analytics را در کل برنامه غیرفعال می‌کند. توجه داشته باشید که این پرچم باید هر بار که برنامه راه اندازی می شود تنظیم شود و به طور پیش فرض روی false خواهد بود.

برای دریافت تنظیمات انصراف در سطح برنامه، از:

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

برای تنظیم انصراف در سطح برنامه، از موارد زیر استفاده کنید:

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

در یک پیاده سازی معمولی، یک برنامه ممکن است به تغییر در SharedPreferences گوش دهد و تنظیمات انصراف Google Analytics را بر این اساس به روز کند:

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 برای کاربران نهایی دارید، می‌توانید فایل Client ID را حذف کنید.

حذف فایل gaClientId باعث ایجاد یک Client Id جدید می شود و تمام بازدیدهای بعدی از شناسه مشتری جدید استفاده می کنند. داده های قبلی با شناسه مشتری جدید مرتبط نمی شوند.

برای حذف فایل gaClientId از روش Context.deleteFile استفاده کنید:

context.deleteFile("gaClientId");

ناشناس کردن IP

فعال کردن عملکرد ناشناس IP به Google Analytics می‌گوید که اطلاعات IP ارسال شده توسط SDK را با حذف آخرین اکتت آدرس IP قبل از ذخیره‌سازی آن، ناشناس کند.

برای فعال کردن عملکرد ناشناس IP، از پارامتر زیر در فایل پیکربندی خود استفاده کنید:

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

برای فعال کردن عملکرد ناشناس IP به صورت برنامه‌ریزی برای یک ردیاب از روش setAnonymizeIp استفاده کنید:

mTracker.setAnonymizeIp(true)

متد setAnonymizeIp را می توان در هر زمان فراخوانی کرد.

تست و اشکال زدایی

Google Analytics SDK v4 برای اندروید ابزارهایی را برای آسان‌تر کردن تست و اشکال‌زدایی ارائه می‌کند.

اجرای خشک

SDK یک پرچم dryRun ارائه می دهد که با تنظیم، از ارسال هرگونه داده به Google Analytics جلوگیری می کند. پرچم dryRun باید هر زمان که یک پیاده سازی را آزمایش یا اشکال زدایی می کنید تنظیم شود و نمی خواهید داده های آزمایش در گزارش های Google Analytics شما ظاهر شود.

برای تنظیم پرچم خشک اجرا:

// 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 Analytics با استفاده از سیستم Android Log به logcat تحت تگ GAv4 وارد می شود. به طور پیش فرض فقط سطوح ERROR، WARN و INFO فعال هستند. برای فعال کردن سطح DEBUG دستور adb زیر را در دستگاه یا شبیه ساز خود اجرا کنید:

adb shell setprop log.tag.GAv4 DEBUG

برای مشاهده فقط پیام های Google Analytics از logcat از دستور زیر استفاده کنید:

adb logcat -v time -s GAv4

برای اطلاعات بیشتر، به مرجع GoogleAnalytics Logger مراجعه کنید.