הגדרה מתקדמת – Android SDK

במסמך הזה מפורטת סקירה כללית של כמה מתכונות ההגדרות המתקדמות של Google Analytics SDK ל-Android v3.

סקירה

Google Analytics SDK ל-Android מספק מחלקה Tracker להגדרה ולשליחה של נתונים ל-Google Analytics, ו-Singleton של GoogleAnalytics שמשמש כממשק לערכי התצורה הגלובליים של ההטמעה.

אתחול

כדי שניתן יהיה למדוד נתונים כלשהם, צריך להפעיל לפחות מכשיר מעקב אחד באמצעות SSO של GoogleAnalytics. לשם כך, צריך לציין Context ומזהה נכס ב-Google Analytics:

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

עכשיו מכשיר המעקב הזה יכול לשמש להגדרה ולשליחה של נתונים אל Google Analytics.

הגדרה ושליחה של נתונים

הנתונים נשלחים ל-Google Analytics על ידי הגדרת מפות של צמדי פרמטר-ערך בכלי המעקב ושולחים אותם בשיטות 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()
);

תחביר Ampersand של 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 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 ל-Android יש כלים שמאפשרים לבצע בדיקות וניפוי באגים בקלות רבה יותר.

הרצה יבשה

ערכת ה-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());
  }
}