Google Analytics SDK برای اندروید: مهاجرت به نسخه 3

این راهنما نحوه ارتقا به نسخه 3 Google Analytics SDK برای اندروید را شرح می‌دهد.

در یک نگاه: چه جدید در V3 است

APIها در V3 به گونه‌ای اصلاح شده‌اند که در پلتفرم‌های بومی و وب سازگارتر باشند. همه کاربران V2 باید به این تغییرات توجه داشته باشند:

  • بازدیدها اکنون با استفاده از یک روش send(Map<String, String> parameters) ارسال می‌شوند.
  • حالت اشکال زدایی با Logger جایگزین شده است
  • EasyTracker اکنون Tracker را زیر کلاس قرار می دهد که منجر به تغییراتی در رابط کاربری می شود.
  • جدید: یک پرچم dryRun برای جلوگیری از نمایش داده های ارسال شده در گزارش ها اضافه شده است.

برای فهرست کامل تغییرات، به Changelog Android مراجعه کنید.

قبل از اینکه شروع کنی

قبل از شروع به‌روزرسانی به نسخه 3، به موارد زیر نیاز دارید:

مسیرها را ارتقا دهید

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

EasyTracker: v1.x تا v3

توصیه می شود که کاربران EasyTracker v1.x برای شروع استفاده از نسخه 3 با EasyTracker ، راهنمای شروع نسخه 3 را دنبال کنند.

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>
    برای جزئیات بیشتر به مرجع پارامتر EasyTracker مراجعه کنید.


  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>

پیاده سازی سفارشی: v1.x تا v3

کاربران v1.x که از EasyTracker استفاده نمی‌کنند، باید راهنمای شروع V3 را دنبال کنند و در صورت نیاز از راهنمای برنامه‌نویس تنظیمات پیشرفته استفاده کنند.

پیاده سازی سفارشی: v2.x تا v3

کاربران v2.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 دیگر به طور خودکار جلسه جدیدی را با باز شدن برنامه شروع نمی کند (به جز زمانی که از EasyTracker استفاده می کنید). اگر می‌خواهید این رفتار را از اجرای سفارشی v2 حفظ کنید، باید منطق کنترل جلسه خود را زمانی که کاربر برنامه را راه‌اندازی می‌کند پیاده‌سازی کنید:
    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 ارائه می‌دهند.

ارسال داده با استفاده از Maps در نسخه 3

در V3، داده ها با استفاده از یک متد 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 بیشتر بیاموزید