پیکربندی پیشرفته - Android SDK

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

بررسی اجمالی

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

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

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

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

اکنون می توان از این ردیاب برای تنظیم و ارسال داده به Google Analytics استفاده کرد.

تنظیم و ارسال داده ها

داده ها با تنظیم نقشه های جفت پارامتر-مقدار در ردیاب و ارسال آنها از طریق روش های set و send به Google Analytics ارسال می شود:

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

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

همچنین می‌توان مقادیر را روی یک ضربه، با تنظیم مقدار در Builder ، یا در تمام بازدیدهای بعدی، با تنظیم آن بر روی شی ردیاب، با استفاده از آمپر و نحو پروتکل اندازه‌گیری تنظیم کرد:

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

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

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

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

// 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 Analytics استفاده می‌کنند. اگر از این ویژگی‌ها استفاده می‌کنید و می‌خواهید با استفاده از ردیاب‌های دیگر داده ارسال کنید، باید این کار را به صورت دستی انجام دهید.

با استفاده از ردیاب پیش فرض

Google Analytics یک ردیاب پیش فرض دارد. اولین ردیاب اولیه به ردیاب پیش فرض تبدیل می شود اما ممکن است لغو شود:

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

به عنوان مثال، برای فعال کردن نمونه برداری سمت مشتری با نرخ 50٪ از طریق EasyTracker و XML، از پارامتر زیر در فایل analytics.xml خود استفاده کنید:

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

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

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

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

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

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

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 SDK برای اندروید ابزارهایی را برای آسان‌تر کردن تست و اشکال‌زدایی ارائه می‌کند.

اجرای خشک

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

متمرکز ساز

رابط 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 Analytics و ارسال یک نمای صفحه نمایش را نشان می دهد.

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