Google Analytics SDK ל-Android: מעבר לגרסה 3

במדריך הזה מוסבר איך לשדרג לגרסה 3 של ה-SDK של Google Analytics ל-Android.

'בקצרה': מה חדש ב-V3

ממשקי ה-API ב-V3 הוגדר מחדש כדי להיות עקביים יותר בין פלטפורמות מקוריות ואינטרנט. כל משתמשי V2 צריכים לשים לב לשינויים הבאים:

  • היטים נשלחים עכשיו באמצעות שיטת send(Map<String, String> parameters) אחת.
  • מצב ניפוי הבאגים הוחלף במצב Logger
  • EasyMonitor משנה עכשיו את מחלקות המשנה Tracker, וכתוצאה מכך בוצעו שינויים בממשק.
  • חדש: הדגל dryRun נוסף כדי למנוע הופעה של נתונים שנשלחו בדוחות.

רשימת השינויים המלאה מופיעה ב יומן השינויים של Android.

לפני שתתחיל

לפני התחלת השדרוג לגרסה 3, יש צורך בדברים הבאים:

שדרוג נתיבים

כדי להתחיל, עליך לבחור נתיב שדרוג ל-v3 מההטמעה הנוכחית שלך:

Easytracker: v1.x עד v3

מומלץ למשתמשי Easytracker v1.x לפעול לפי המדריך לתחילת העבודה בגרסה 3 כדי להתחיל להשתמש ב-v3 עם EasyMonitor.

Easytracker: v2.x עד v3

משתמשי Easytracker בגרסה v2.x צריכים לבצע את השלבים הבאים כדי להשלים את השדרוג לגרסה v3:

  1. צריך לעדכן את השיחות אל EasyTracker.getInstance() כדי לספק Context: 
    // v2 (Old)
// EasyTracker.getInstance().activityStart(this);

    // v3:
EasyTracker.getInstance(this).activityStart(this);
  2. EasyTracker הוא עכשיו מחלקה משנית Tracker -- הסרת השיחות אל EasyTracker.getTracker(): 
    // v2 (Old)
Tracker v2Tracker = EasyTracker.getInstance().getTracker();

    // v3
Tracker v3Tracker = EasyTracker.getInstance(this);
  3. מחליפים את כל שיטות הנוחות של send<hit-type> בשיטה החדשה send(Map<String, String> parameters): 
    // v2 (Old)
Tracker v2EasyTracker = EasyTracker.getInstance().getTracker(this);
v2EasyTracker.sendView("Home Screen");

    // v3
Tracker v3EasyTracker = EasyTracker.getInstance(this);

// Set the screen name on the tracker so that it is used in all hits sent from this screen.
v3EasyTracker.set(Fields.SCREEN_NAME, "Home Screen");

// Send a screenview.
v3EasyTracker.send(MapBuilder
  .createAppView()
  .build()
);
    מידע נוסף על שליחת נתונים בגרסה 3.


  4. מחליפים את הפרמטר ga_debug Easytracker ב-ga_logLevel, ואחד מערכי דרגת המלל הבאים: verbose, info, warning, error: 
    <!-- res/values/analytics.xml -->

<?xml version="1.0" encoding="utf-8"?>
<resources>
  <string name="ga_trackingId">UA-XXXX-Y</string>
  <!-- REMOVE: <bool name="ga_debug">true</bool> -->
  <string name="ga_logLevel">verbose</string>
</resources>
    ניתן לעיין בחומר העזר בנושא פרמטרים של EasyMonitor לקבלת פרטים נוספים.


  5. המדיניות GoogleAnalytics.requestAppOptOut() הוצאה משימוש, יש להשתמש ב-GoogleAnalytics.getAppOptOut() במקום זאת: 
    // v2 (Old)
GoogleAnalytics.getInstance(this).requestAppOptOut(new AppOptOutCallback() {
   @Override
   public void reportAppOptOut(boolean optOut) {
     if (optOut) {
     ... // Alert the user that they've opted out.
     }
   });
}

    // v3
boolean optOutPreference = GoogleAnalytics.getInstance(this).getAppOptOut();
  6. (אופציונלי) הוסף את הפרמטר ga_dryRun Easytracker ולהגדיר ל-true בעת בדיקת היישום, כדי למנוע הופעה של נתוני בדיקה בדוחות הייצור שלך:
    7. <!-- res/values/analytics.xml -->

<?xml version="1.0" encoding="utf-8"?>

<resources>
  <string name="ga_trackingId">UA-XXXX-Y</string>
  <string name="ga_logLevel">verbose</string>

  <!-- Prevent data from appearing in reports. Useful for testing. -->
  <bool name="ga_dryRun">true</bool>

</resources>

הטמעה מותאמת אישית: גרסה 1.x עד v3

משתמשי v1.x שלא משתמשים ב-EasyTracker צריכים לפעול לפי המדריך לתחילת העבודה של V3 ולהתייעץ במדריך למפתחים בנושא הגדרות מתקדמות, לפי הצורך.

הטמעה מותאמת אישית: גרסה v2.x עד v3

משתמשי גרסה 2.x שלא משתמשים ב-EasyTracker צריכים לבצע את ההוראות שבהמשך כדי להשלים את השדרוג לגרסה 3:

  1. מחליפים את כל שיטות הנוחות 'send<hit-type>' בשיטה send(Map<String, String> parameters) החדשה: 
    // v2 (Old)
Tracker v2Tracker = GoogleAnaytics.getInstance(this).getTracker("UA-XXXX-Y");
v2Tracker.sendView("Home Screen");

    // v3
Tracker v3Tracker = GoogleAnaytics.getInstance(this).getTracker("UA-XXXX-Y");

// This screen name value will remain set on the tracker and sent with
// hits until it is set to a new value or to null.
v3Tracker.set(Fields.SCREEN_NAME, "Home Screen");

v3Tracker.send(MapBuilder
  .createAppView()
  .build()
);
  2. הסרת שיחות אל GoogleAnalytics.setDebug() והחלפה שלהן ב-GoogleAnalytics.getLogger().setLogLevel(): 
    // V2 (Old)
GoogleAnalytics.getInstance(this).setDebug(true);

    // V3
GoogleAnalytics.getInstance(this)
    .getLogger()
    .setLogLevel(LogLevel.VERBOSE);  // VERBOSE | INFO | DEBUG | WARNING
    מידע נוסף על Logger

  3. v3 SDK כבר לא מתחיל סשן חדש באופן אוטומטי כשהאפליקציה נפתחת (אלא אם משתמשים ב-EasyMonitor). אם ברצונך לשמר את ההתנהגות הזו מהטמעה מותאמת אישית של גרסה 2, עליך להטמיע לוגיקה משלך לבקרה על סשנים כשמשתמש מפעיל את האפליקציה:
    4. package com.example.app;

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

import android.app.Application;

public class MyApp extends Application {

  private static Tracker mTracker;
  private static final String GA_PROPERTY_ID = "UA-XXXX-Y";

  @Override
  public void onCreate() {
    super.onCreate();
    mTracker = GoogleAnalytics.getInstance(this).getTracker(GA_PROPERTY_ID);

    // CAUTION: Setting session control directly on the tracker persists the
    // value across all subsequent hits, until it is manually set to null.
    // This should never be done in normal operation.
    //
    // mTracker.set(Fields.SESSION_CONTROL, "start");

    // Instead, send a single hit with session control to start the new session.
    mTracker.send(MapBuilder
      .createEvent("UX", "appstart", null, null)
      .set(Fields.SESSION_CONTROL, "start")
      .build()
    );
  }
}
  4. (אופציונלי) מגדירים את הדגל dryRun במהלך הבדיקה כדי למנוע עיבוד של נתוני הבדיקה בדוחות הייצור:
    5. // When true, dryRun flag prevents data from being processed with reports.
GoogleAnalytics.getInstance(this).setDryRun(true);

חומרי עזר

בקטעים הבאים מובאות דוגמאות שממחישות איך להגדיר ולשלוח נתונים באמצעות V3 SDK.

שליחת נתונים באמצעות מפות Google בגרסה 3

בגרסה 3, הנתונים נשלחים בשיטת send() אחת, שלוקחת כארגומנט Map מהשדות והערכים של Google Analytics. רמת השירות MapBuilder מסופקת כדי לפשט את התהליך של יצירת היטים:

// Sending a screenview in v3 using MapBuilder.
Tracker tracker = GoogleAnalytics.getInstance(this).getTracker("UA-XXXX-Y");
tracker.set(Fields.SCREEN_NAME, "Home Screen");

tracker.send(MapBuilder
  .createAppView()                           // Creates a Map of hit type 'AppView' (screenview).
  .set(Fields.customDimension(1), "Premium") // Set any additional fields for this hit.
  .build()                                   // Build and return the Map to the send method.
);

המחלקה MapBuilder יכולה לשמש כדי ליצור כל אחד מסוגי ההיטים הנתמכים, כמו אירועים:

// Sending an event in v3 using MapBuilder.createEvent()
tracker.send(MapBuilder
    .createEvent("UX", "touch", "menuButton", null)
    .build()
);

מידע נוסף על שליחת נתונים בגרסה 3

הגדרת נתונים במכשיר המעקב בגרסה 3

אפשר גם להגדיר את הערכים ישירות ב- Tracker באמצעות השיטה set(). הערכים שמוגדרים באופן ישיר חלים על כל ההיטים הבאים מאותו Tracker : 

// Values set directly on a tracker apply to all subsequent hits.
tracker.set(Fields.SCREEN_NAME, "Home Screen");

// This screenview hit will include the screen name "Home Screen".
tracker.send(MapBuilder.createAppView().build());

// And so will this event hit.
tracker.send(MapBuilder
  .createEvent("UX", "touch", "menuButton", null)
  .build()
);

כדי לנקות ערך שהוגדר ב-Tracker , מגדירים את המאפיין כ-null:

// Clear the previously-set screen name value.
tracker.set(Fields.SCREEN_NAME, null);

// Now this event hit will not include a screen name value.
tracker.send(MapBuilder
  .createEvent("UX", "touch", "menuButton", null)
  .build()
);

מידע נוסף על הגדרת הנתונים בגרסה 3