يشرح هذا الدليل طريقة الترقية إلى الإصدار 3 من حزمة تطوير البرامج (SDK) لخدمة "إحصاءات Google" لنظام التشغيل Android.
نظرة سريعة: الميزات الجديدة في الإصدار 3
تمت إعادة هيكلة واجهات برمجة التطبيقات في الإصدار الثالث لتصبح أكثر اتساقًا على مستوى الأنظمة الأساسية الأصلية ومنصات الويب. يجب على جميع مستخدمي الإصدار 2 ملاحظة هذه التغييرات:
- يتم الآن إرسال النتائج باستخدام طريقة
send(Map<String, String> parameters)
واحدة. - تم استبدال وضع تصحيح الأخطاء بـ
Logger
- أصبحت أداة EasyTracker الآن تصنيفًا فرعيًا للفئة
Tracker
، ما أدى إلى إجراء بعض التغييرات على الواجهة. - جديد: تمت إضافة العلامة
dryRun
لمنع ظهور البيانات المُرسلة في التقارير.
للحصول على القائمة الكاملة للتغييرات، يُرجى الاطّلاع على سجلّ تغييرات Android.
قبل البدء
قبل البدء في الترقية إلى الإصدار 3، ستحتاج إلى ما يلي:
- موقع تم تفعيل Universal Analytics وملف شخصي للتطبيق عليه
- الإصدار الثالث من حزمة تطوير البرامج (SDK) لخدمة "إحصاءات Google" لنظام التشغيل Android
مسارات الترقية
للبدء، اختَر مسار ترقية إلى الإصدار 3 من عملية التنفيذ الحالية:
- سهولة تتبُّع: الإصدار 1.x من الإصدار 3 إلى الإصدار 3
- EasyTracker: استخدام الإصدار 2.x من الإصدار v3 إلى الإصدار 3
- التنفيذ المخصّص: الإصدار 1.x إلى الإصدار 3
- التنفيذ المخصّص: الإصدار 2.x حتى الإصدار 3
EasyTracker: من الإصدار 1.x إلى الإصدار 3
ننصح مستخدمي الإصدار 1.x من EasyTracker باتّباع دليل البدء الخاص بالإصدار v3 لبدء استخدام الإصدار الثالث مع أداة EasyTracker.
EasyTracker: من الإصدار 2.x إلى الإصدار 3
على مستخدمي v2.x EasyTracker اتّباع الخطوات التالية لإكمال الترقية إلى الإصدار v3:
- يجب تعديل المكالمات إلى
EasyTracker.getInstance()
لتوفيرContext:
// v2 (Old) // EasyTracker.getInstance().activityStart(this);
// v3: EasyTracker.getInstance(this).activityStart(this);
- أصبحت
EasyTracker
الآن ضمن الفئات الفرعيةTracker
-- إزالة طلبات البيانات إلىEasyTracker.getTracker()
:// v2 (Old) Tracker v2Tracker = EasyTracker.getInstance().getTracker();
// v3 Tracker v3Tracker = EasyTracker.getInstance(this);
- استبدِل كل طرق
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. - استبدِل مَعلمة
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 لمزيد من التفاصيل. - تم إيقاف
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();
- (اختياري) أضِف مَعلمة
ga_dryRun
EasyTracker وضبطها علىtrue
عند اختبار عملية التنفيذ لمنع ظهور بيانات الاختبار في تقارير الإنتاج:
<!-- 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:
- استبدِل كل طرق الإرسال الملائمة '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() );
- إزالة الطلبات الموجّهة إلى
GoogleAnalytics.setDebug()
واستبدالها بـGoogleAnalytics.getLogger().setLogLevel()
:// V2 (Old) GoogleAnalytics.getInstance(this).setDebug(true);
// V3 GoogleAnalytics.getInstance(this) .getLogger() .setLogLevel(LogLevel.VERBOSE); // VERBOSE | INFO | DEBUG | WARNING
مزيد من المعلومات حول "المسجّل" - لم تعد حزمة SDK ذات الإصدار 3 تبدأ جلسة جديدة تلقائيًا عند فتح التطبيق (إلا عند استخدام EasyTracker). وإذا أردت الحفاظ على هذا السلوك الناتج عن عملية التنفيذ المخصّصة للإصدار 2، عليك تنفيذ منطق تحكّم في الجلسة عندما يبدأ المستخدم تشغيل التطبيق:
- (اختياري) يمكنك ضبط العلامة
dryRun
أثناء الاختبار لمنع معالجة بيانات الاختبار في تقارير الإنتاج:
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() ); } }
// 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() );