حزمة تطوير البرامج (SDK) لخدمة "إحصاءات Google" لنظام التشغيل Android: نقل البيانات إلى الإصدار 3

يشرح هذا الدليل طريقة الترقية إلى الإصدار 3 من حزمة تطوير البرامج (SDK) لخدمة "إحصاءات Google" لنظام التشغيل Android.

نظرة سريعة: الميزات الجديدة في الإصدار 3

تمت إعادة هيكلة واجهات برمجة التطبيقات في الإصدار الثالث لتصبح أكثر اتساقًا على مستوى الأنظمة الأساسية الأصلية ومنصات الويب. يجب على جميع مستخدمي الإصدار 2 ملاحظة هذه التغييرات:

  • يتم الآن إرسال النتائج باستخدام طريقة send(Map<String, String> parameters) واحدة.
  • تم استبدال وضع تصحيح الأخطاء بـ Logger
  • أصبحت أداة EasyTracker الآن تصنيفًا فرعيًا للفئة Tracker، ما أدى إلى إجراء بعض التغييرات على الواجهة.
  • جديد: تمت إضافة العلامة dryRun لمنع ظهور البيانات المُرسلة في التقارير.

للحصول على القائمة الكاملة للتغييرات، يُرجى الاطّلاع على سجلّ تغييرات Android.

قبل البدء

قبل البدء في الترقية إلى الإصدار 3، ستحتاج إلى ما يلي:

مسارات الترقية

للبدء، اختَر مسار ترقية إلى الإصدار 3 من عملية التنفيذ الحالية:

EasyTracker: من الإصدار 1.x إلى الإصدار 3

ننصح مستخدمي الإصدار 1.x من EasyTracker باتّباع دليل البدء الخاص بالإصدار v3 لبدء استخدام الإصدار الثالث مع أداة EasyTracker.

EasyTracker: من الإصدار 2.x إلى الإصدار 3

على مستخدمي v2.x EasyTracker اتّباع الخطوات التالية لإكمال الترقية إلى الإصدار 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>

التنفيذ المخصّص: الإصدار 1.x إلى الإصدار 3

على مستخدمي الإصدار 1.x الذين لا يستخدمون EasyTracker اتّباع دليل البدء الخاص بالإصدار 3 من Google والاطّلاع على دليل مطوّر الإعدادات المتقدّمة حسب الحاجة.

التنفيذ المخصّص: الإصدار 2.x إلى الإصدار 3

على مستخدمي الإصدار 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
    مزيد من المعلومات حول "المسجّل"

  3. لم تعد حزمة SDK ذات الإصدار 3 تبدأ جلسة جديدة تلقائيًا عند فتح التطبيق (إلا عند استخدام EasyTracker). وإذا أردت الحفاظ على هذا السلوك الناتج عن عملية التنفيذ المخصّصة للإصدار 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);

مَراجع

تقدم الأقسام التالية أمثلة مرجعية حول كيفية تعيين البيانات وإرسالها باستخدام الإصدار 3 من حزمة تطوير البرامج (SDK).

إرسال البيانات باستخدام "خرائط Google" في الإصدار 3

في الإصدار 3، يتم إرسال البيانات باستخدام طريقة send() واحدة تستخدم Map من حقول وقيم "إحصاءات Google" كوسيطة. يتم توفير فئة المرافق 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