تُسهِّل حزمة تطوير البرامج (SDK) لأداة "إحصاءات Google للأجهزة الجوّالة" لنظام التشغيل Android عملية "إحصاءات Google" في التطبيقات المستندة إلى Android. يوضّح هذا المستند كيفية دمج حزمة تطوير البرامج (SDK) مع تطبيقاتك.
نظرة عامة على حزمة تطوير البرامج (SDK)
تستخدم حزمة تطوير البرامج (SDK) هذه نموذج تتبّع مصمّم لتتبّع المستخدمين إلى مواقع إلكترونية تقليدية وتفاعلهم مع الأدوات في صفحات الويب التقليدية. ولهذا السبب، تعكس البنود المستخدَمة أدناه النموذج التقليدي لتتبُّع الموقع الإلكتروني، كما يتم ربطها لتتبّع التطبيقات المتوافقة مع الأجهزة الجوّالة. ويجب أن تكون على دراية بميزة تتبُّع "إحصاءات Google" لفهم آلية عمل حزمة تطوير البرامج (SDK) هذه.
استخدِم حزمة تطوير البرامج (SDK) لتتبُّع الأجهزة الجوّالة من أجل تتبّع تطبيقات هاتفك باستخدام أنواع التفاعل التالية في "إحصاءات Google":
- تتبُّع مشاهدة الصفحة على الويب
- مشاهدة الصفحة هي طريقة عادية لقياس حجم الزيارات إلى موقع إلكتروني تقليدي. بما أنّ التطبيقات المتوافقة مع الأجهزة الجوّالة لا تحتوي على صفحات HTML، عليك تحديد وقت (وعدد مرات) تشغيل طلب مشاهدة الصفحة. بالإضافة إلى ذلك، بما أنّ طلبات مشاهدة الصفحة مصمّمة للإبلاغ عن بُنى الأدلة، عليك توفير أسماء وصفية للطلبات للاستفادة من تسمية مسار الصفحة في تقارير "المحتوى" ضمن "إحصاءات Google ". ستتم تعبئة الأسماء التي تختارها في تقارير "إحصاءات Google" كمسارات صفحات على الرغم من أنها ليست صفحات HTML في الواقع، ولكن يمكنك استخدام هذه الميزة لصالحك من خلال تنظيم المسارات لتوفير مجموعات إضافية لمكالماتك.
- تتبع الأحداث
- في"إحصاءات Google"، يتم تصميم الأحداث لتتبُّع تفاعل المستخدمين مع عناصر صفحات الويب بشكل مختلف عن طلبات مشاهدة الصفحة على الويب. يمكنك استخدام ميزة "تتبُّع الأحداث" في "إحصاءات Google" لإجراء مكالمات إضافية سيتم الإبلاغ عنها في قسم "تتبُّع الأحداث" من واجهة تقرير "إحصاءات Google". يتم تجميع الأحداث باستخدام الفئات ويمكن أن تستخدِم أيضًا تصنيفات لكل حدث، ما يوفّر مرونة في إعداد التقارير. على سبيل المثال، يمكن أن يتضمّن تطبيق الوسائط المتعددة إجراءات تشغيل/إيقاف/إيقاف مؤقت لفئة الفيديو الخاصة به وتحديد تصنيف لكل اسم فيديو. وبعد ذلك، ستجمع تقارير "إحصاءات Google" الأحداث لجميع الأحداث التي تم وضع علامة عليها بفئة الفيديو. لمزيد من المعلومات حول تتبّع الفعاليات، يُرجى الاطّلاع على دليل تتبّع الفعاليات.
- تتبّع التجارة الإلكترونية
- يمكنك استخدام ميزة تتبُّع التجارة الإلكترونية لتتبُّع معاملات سلة التسوّق وعمليات الشراء داخل التطبيق.
لتتبّع معاملة، استخدِم الفئة
Transaction
لتمثيل معلومات الشراء الإجمالية، بالإضافة إلى الفئةItem
لتمثيل كل منتج في سلة التسوّق. بعد الانتهاء من جمع البيانات، يمكن الاطّلاع عليها في قسم إعداد تقارير التجارة الإلكترونية في واجهة "إحصاءات Google". للحصول على مزيد من المعلومات حول تتبُّع التجارة الإلكترونية، اطّلِع على دليل تتبُّع التجارة الإلكترونية. - المتغيرات المخصّصة
- المتغيّرات المخصّصة هي علامات إقران اسم القيمة التي يمكنك إدراجها في رمز التتبّع لتحسين تتبُّع"إحصاءات Google". ولمزيد من المعلومات حول كيفية استخدام المتغيّرات المخصّصة، اطّلِع على دليل المتغيّرات المخصّصة.
البدء
المتطلّبات
لدمج إمكانيات تتبُّع "إحصاءات Google" و"إحصاءات Google" مع تطبيقك المتوافق مع Android، ستحتاج إلى ما يلي:
- حزمة تطوير البرامج (SDK) لمطوّري برامج Android (متوفّرة لأنظمة التشغيل Windows وMac OS X وLinux)
- حزمة تطوير البرامج (SDK) لخدمة "إحصاءات Google" للتطبيقات المتوافقة مع الأجهزة الجوّالة التي تعمل بنظام التشغيل Android
الإعداد
- أضِف
libGoogleAnalytics.jar
إلى دليل/libs
الخاص بمشروعك. -
أضِف الأذونات التالية إلى ملف البيان
AndroidManifest.xml
في مشروعك:<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
يتم تضمين نموذج تطبيق في حزمة تطوير البرامج (SDK) التي توضح الشكل الذي يجب أن يظهر به مشروعك في حال إعداده بنجاح. ويمكنك استخدامه كنموذج لتطبيقاتك المتكاملة في "إحصاءات Google".
استخدام حزمة تطوير البرامج (SDK)
قبل البدء في استخدام حزمة تطوير البرامج (SDK)، يجب أولاً إنشاء حساب مجاني على www.google.com/analytics وإنشاء موقع إلكتروني جديد في هذا الحساب باستخدام عنوان URL مزيّف ولكنه وصفي للموقع الإلكتروني (مثل http://mymobileapp.mywebsite.com
). وبعد إنشاء الموقع، اكتب أو احتفظ بنسخة من معرّف الموقع الإلكتروني الذي تم إنشاؤه للموقع الإلكتروني الذي تم إنشاؤه مؤخرًا.
يجب أن توضّح للمستخدمين، سواء في التطبيق نفسه أو في بنود الخدمة، أنك تحتفظ بالحق في تتبُّع نشاط المستخدم أثناء تطبيقك والإبلاغ عنه بدون الكشف عن هويته. وفي هذه الحالة، يخضع استخدامك لأداة تطوير البرامج (SDK) لخدمة"إحصاءات Google"أيضًا لبنود خدمة"إحصاءات Google" التي يجب الموافقة عليها عند الاشتراك للحصول على حساب.
النماذج وأفضل الممارسات
يمكنك العثور على نموذج للرمز وأفضل الممارسات على code.google.com ضمن analytics-api-sample في المشروع.
مكتبة EasyTracker
تتوفّر "مكتبة EasyTracker". وتوفّر هذه الميزة تتبُّعًا على مستوى التطبيق والنشاط بدون أي مجهود تقريبًا في عملية التطوير. ويمكنك العثور عليه في قسم عمليات التنزيل من مشروع analytics-api-sample.
بدء أداة التتبُّع
يمكنك الحصول على الأداة الفردية للتتبُّع من خلال طلب GoogleAnalyticsTracker.getInstance()
. بعد ذلك، عليك استدعاء طريقة startNewSession
، مع تمرير رقم تعريف موقع الويب والنشاط الذي يتم تتبعه. يمكنك تسمية هذه الطريقة مباشرةً بطريقة onCreate
"نشاطك"إذا كان تطبيقك يحتوي على نشاط واحد فقط. مثلاً:
package com.google.android.apps.analytics.sample; import com.google.android.apps.analytics.GoogleAnalyticsTracker; import android.app.Activity; import android.os.Bundle; import android.view.View; import android.view.View.OnClickListener; import android.widget.Button; public class TestActivity extends Activity { GoogleAnalyticsTracker tracker; @Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); tracker = GoogleAnalyticsTracker.getInstance(); // Start the tracker in manual dispatch mode... tracker.startNewSession("UA-YOUR-ACCOUNT-HERE", this); // ...alternatively, the tracker can be started with a dispatch interval (in seconds). //tracker.startNewSession("UA-YOUR-ACCOUNT-HERE", 20, this); setContentView(R.layout.main); Button createEventButton = (Button)findViewById(R.id.NewEventButton); createEventButton.setOnClickListener(new OnClickListener() { @Override public void onClick(View v) { tracker.trackEvent( "Clicks", // Category "Button", // Action "clicked", // Label 77); // Value } }); Button createPageButton = (Button)findViewById(R.id.NewPageButton); createPageButton.setOnClickListener(new OnClickListener() { @Override public void onClick(View v) { // Add a Custom Variable to this pageview, with name of "Medium" and value "MobileApp" and // scope of session-level. tracker.setCustomVar(1, "Navigation Type", "Button click", 2); // Track a page view. This is probably the best way to track which parts of your application // are being used. // E.g. // tracker.trackPageView("/help"); to track someone looking at the help screen. // tracker.trackPageView("/level2"); to track someone reaching level 2 in a game. // tracker.trackPageView("/uploadScreen"); to track someone using an upload screen. tracker.trackPageView("/testApplicationHomeScreen"); } }); Button quitButton = (Button)findViewById(R.id.QuitButton); quitButton.setOnClickListener(new OnClickListener() { @Override public void onClick(View v) { finish(); } }); Button dispatchButton = (Button)findViewById(R.id.DispatchButton); dispatchButton.setOnClickListener(new OnClickListener() { @Override public void onClick(View v) { // Manually start a dispatch, not needed if the tracker was started with a dispatch // interval. tracker.dispatch(); } }); } @Override protected void onDestroy() { super.onDestroy(); // Stop the tracker when it is no longer needed. tracker.stopSession(); } }
إذا كانت لديك عدة أنشطة في تطبيقك، يمكنك استخدام مكتبة EasyTracker الواردة في قسم عمليات التنزيل من مشروع analytics-api-sample.
تتبُّع مرات مشاهدة الصفحة والأحداث
تتبّع مرات مشاهدة الصفحة والأحداث أمر بسيط: ما عليك سوى استدعاء trackPageView
من كائن أداة التتبع في كل مرة تريد فيها تشغيل مشاهدة صفحة على الويب. اتصل على trackEvent
لتسجيل حدث. لمزيد من المعلومات حول مرات مشاهدة الصفحة والأحداث، راجع نظرة عامة على حزمة تطوير البرامج (SDK) أعلاه.
استخدام المتغيرات المخصّصة
يمكن أيضًا إضافة متغيّر مخصّص مباشرةً: ما عليك سوى استخدام الطريقة setCustomVar
التي تقدّمها حزمة تطوير البرامج (SDK) للأجهزة الجوّالة. تحتاج إلى التخطيط مسبقًا
الذي يفهرس كل متغيّر مخصَّص مرتبط به، بحيث لا تستبدل أي متغيّر حالي. ولمزيد من المعلومات عن المتغيّرات المخصّصة، اطّلِع على دليل المتغيّرات المخصّصة. يُرجى ملاحظة أن الطريقة setCustomVar
لا ترسل البيانات مباشرةً من نفسها. وبدلاً من ذلك، يتم إرسال البيانات مع مشاهدة الصفحة أو الحدث التالي الذي يتم تتبّعه. يجب طلب setCustomVar
قبل تتبّع مشاهدة صفحة على الويب أو حدث. لاحظ أن النطاق التلقائي للمتغيرات المخصّصة هو على نطاق الصفحة.
استخدام تتبع التجارة الإلكترونية
هناك 4 طرق تستخدمها لتفعيل تتبع التجارة الإلكترونية في تطبيقك:
addTransaction
addItem
trackTransactions
clearTransactions
يؤدي طلب addTransaction
وaddItem
إلى إضافة المعاملة أو العنصر إلى مخزن مؤقت للتجارة الإلكترونية الداخلية، حيث يمكن إضافة المزيد من العناصر والمعاملات. فقط عند استدعاء trackTransactions
، سيتم إرسال المعاملات والعناصر إلى المسؤول وإدراجها في قائمة الانتظار لإرسالها إلى"إحصاءات Google".
لمحو المخزن المؤقت، يمكنك استدعاء طريقة clearTransactions
.
ملاحظة: لا يتذكّر أي معاملات تم إرسالها سابقًا إلى المُرسل أو
أي معاملات سبق أن جمعها "إحصاءات Google".
يمكن أن يبدأ نموذج الرمز التالي في البدء. ونفترض أنّه يتم طلب طريقة onPurchaseCompleted
عند تأكيد عملية الشراء أو رفضها.
/** * The purchase was processed. We will track the transaction and its associated line items * now, but only if the purchase has been confirmed. * * @param purchase A PurchaseObject containing all of the transaction information needed to * send the ecommerce hit to Google Analytics. */ public void onPurchaseCompleted(PurchaseObject purchase) { tracker.addTransaction(new Transaction.Builder( purchase.getTransactionId(), purchase.getTotal()) .setStoreName(purchase.getStoreName()) .setTotalTax(purchase.getTotalTax()) .setShippingCost(purchase.getShippingCost()) .build()); for (PurchaseLineItem lineItem : purchase.getLineItems()) { tracker.addItem(new Item.Builder( purchase.getTransactionId(), lineItem.getItemSKU(), lineItem.getItemCost(), lineItem.getQuantity()) .setItemName(lineItem.getItemName()) .setItemCategory(lineItem.getItemCategory()) .build()); } if (purchase.isConfirmed()) { tracker.trackTransactions(); } else { // The purchase was denied or failed in some way. We need to clear out // any data we've already put in the Ecommerce buffer. tracker.clearTransactions(); } }
لمزيد من المعلومات عن التجارة الإلكترونية، اطّلع على دليل تتبُّع التجارة الإلكترونية.
إخفاء هوية عناوين IP
وإخفاء هوية معلومات IP، استخدِم الطريقة setAnonymizeIp
.
يؤدي ذلك إلى إعلام "إحصاءات Google" بإخفاء المعلومات التي ترسلها حزمة تطوير البرامج (SDK) من خلال إزالة آخر وحدة ثمانيّة البت من عنوان IP قبل تخزينه.
يمكنك الاتصال بـ setAnonymizeIp
في أي وقت.
إعداد معدّل البيانات في الملف الصوتي
ويمكنك ضبط معدل العيّنة باستخدام الطريقة setSampleRate
.
إذا كان تطبيقك يجلب عددًا كبيرًا من زيارات "إحصاءات Google"، قد يؤدي إعداد معدل العينة إلى منع إنشاء تقاريرك باستخدام عينات البيانات. يحدث أخذ العينات بشكل متسق على مستوى المستخدمين الفريدين، لذلك من المفترض أن يتم توفير سلامة في المؤشرات وإعداد التقارير عند تفعيل معدل العينة.
تقبل الطريقة setSampleRate
معلمة int
واحدة. وتكون القيم الصالحة لهذه المعلّمة أي عدد صحيح بين 0 و100، بما يشمل هذين الرقمين.
ويؤدي تفعيل المعدّل على 0 إلى إيقاف إنشاء النتيجة، في حين يؤدي معدّل 100 إلى إرسال جميع البيانات إلى "إحصاءات Google".
من الأفضل الاتصال برقم setSampleRate
قبل الاتصال بأي طرق تتبُّع.
يمكنك معرفة المزيد عن أخذ العينات من دليل مفاهيم أخذ العينات.
نتائج التجميع
لتوفير التكاليف في الاتصال واستهلاك البطارية، ننصحك بتجميع طلبات التتبّع بشكل مجمّع. يمكنك استدعاء dispatch
في كائن التتبع في أي وقت تريد فيه تقديم طلب مجمّع، ويمكنك إجراء ذلك يدويًا أو على فترات زمنية محددة.
المشاكل المعروفة
تتبع الحملات
تتوافق حزمة تطوير البرامج (SDK) مع نوعَين من تتبُّع الحملات.
- تتبُّع حملات Google Play: يسمح لك هذا الإعداد بتتبع إحالات التثبيت من خلال Google Play.
- تتبُّع الحملات العامة: يسمح لك هذا الخيار بتتبُّع أي حملة تُحيل المستخدمين إلى تطبيقك.
تتبُّع حملات Google Play
يتيح الإصدار 1.6 من نظام التشغيل Android استخدام معلمة عنوان URL referrer
في روابط التنزيل إلى Google Play. تستخدم حزمة تطوير البرامج (SDK) لأداة "إحصاءات Google" لنظام التشغيل Android هذه المعلّمة لتعبئة معلومات الحملة تلقائيًا في "إحصاءات Google" لتطبيقك. ويتيح ذلك إمكانية تسجيل مصدر تثبيت التطبيق وربطه بمرات مشاهدة الصفحة والأحداث المستقبلية، ما قد يكون مفيدًا لقياس مدى فعالية إعلان معيّن لتطبيقك.
لكي تعمل ميزة تتبُّع الإحالات، عليك إضافة مقتطف الرمز التالي إلى ملف البيان AndroidManifest.xml
في مشروعك:
<!-- Used for install referrer tracking --> <receiver android:name="com.google.android.apps.analytics.AnalyticsReceiver" android:exported="true"> <intent-filter> <action android:name="com.android.vending.INSTALL_REFERRER" /> </intent-filter> </receiver>
لإعداد ميزة تتبُّع الحملات في "إحصاءات Google" من خلال Google Play، استخدِم أداة إنشاء عناوين URL أدناه لإنشاء رابط إحالة. استخدِم الرابط لتوجيه المستخدمين إلى تطبيقك. ستحلّل حزمة تطوير البرامج (SDK) لخدمة "إحصاءات Google" معلومات الإحالة وتسجِّلها تلقائيًا وتعبئها في تقرير "إحصاءات Google".
لإنشاء رابط الإحالة، يمكنك استخدام أداة إنشاء عناوين URL لحملات Google Play. يجب إدخال اسم الحزمة ومصدر الحملة ووسيط الحملة واسم الحملة. للحصول على وصف تفصيلي لكل معلّمة، اطّلِع على الجدول أدناه.
تتبُّع الحملات العامة
باستخدام الإصدار 1.3 من حزمة تطوير البرامج (SDK) لخدمة "إحصاءات Google" لنظام التشغيل Android، يمكنك الآن تتبُّع الحملات لمصادر أخرى غير Google Play. على سبيل المثال، إذا كنت تريد معرفة أنه تم إطلاق طلبك من خلال رابط في أحد الإعلانات، يمكنك البحث عن معلومات إحالة الحملة بسبب التسبّب في إطلاق تطبيقك، ثم تخزين معلومات الحملة تلك في "إحصاءات Google".
لضبط معلومات الإحالة للحملة، استخدِم الطريقة setReferrer
على النحو التالي:
tracker.setReferrer(referrer);
هناك قيودتان لاستخدام هذه الميزة. أولاً، عليك الاتصال بالرقم startNewSession
قبل الاتصال
setReferrer
. وتحتاج إلى إجراء ذلك لأن قاعدة بيانات SQLite التي تستخدمها "إحصاءات Google" لم يتم إعدادها قبل استدعاء startNewSession
وsetReferrer
تحتاج إلى قاعدة البيانات هذه. إذا لم يتم الاتصال بالنشاط التجاري startNewSession
، ستحصل على IllegalStateException
.
القيد الثاني هو أن سلسلة الإحالة التي يتم تمريرها إلى setReferrer
تحتاج إلى اتباع تنسيق معيّن.
ويجب أن تكون على شكل مجموعة من معلَمات عناوين URL ويجب أن تتضمّن على الأقل معلّمة gclid أو إحدى المعلّمات لكل من utm_campaign وutm_medium وutm_source. وفي الحالة الثانية، يمكن أن تحتوي على المعلّمتَين utm_term وutm_content أيضًا.
تعتبر معلمة gclid جزءًا من ميزة وضع العلامات التلقائي التي تربط "إحصاءات Google" تلقائيًا بحساب "إعلانات Google". قد يبدو أحد نماذج الحملات التي تستخدم وضع العلامات التلقائي ما يلي:
referrer = “gclid=gclidValue”;
قد تبدو سلسلة الإحالة اليدوية للحملة على النحو التالي:
referrer = “utm_campaign=campaign&utm_source=source&utm_medium=medium&utm_term=term&utm_content=content”;
إذا أدخلت سلسلة سلسلة مُحيلة غير صحيحة إلى setReferrer
، لن يتم تغيير معلومات المُحيل وستظهر لك قيمة خطأ. تشير قيمة العرض true إلى أنه تم تعديل المُحيل وستتم إضافته إلى كل نتيجة من الآن فصاعدًا.
لاحظ أيضًا أنه سيتم بدء جلسة جديدة عند استدعاء setReferrer وستعود إلى "صحيح".
معلّمات رابط الإحالة
المعلمة | مطلوب | الوصف | أمثلة |
---|---|---|---|
utm_campaign |
نعم | اسم الحملة، يتم استخدامه لتحليل الكلمات الرئيسية لتحديد منتج ترويجي معيّن أو حملة استراتيجية معيّنة | utm_campaign=spring_sale |
utm_source |
نعم | مصدر الحملة، ويُستخدم لتحديد محرك بحث أو نشرة إخبارية أو مصدر آخر | utm_source=google |
utm_medium |
نعم | وسيط الحملة؛ ويُستخدم لتحديد وسيط، مثل البريد الإلكتروني أو تكلفة النقرة (CPC) | utm_medium=cpc |
utm_term |
لا | عبارة الحملة المستخدمة مع نتائج البحث المدفوعة لتقديم الكلمات الرئيسية للإعلانات | utm_term=running+shoes |
utm_content |
لا | محتوى الحملة: يتم استخدامه لاختبارات أ/ب والإعلانات التي تستهدف المحتوى لتمييز الإعلانات أو الروابط التي تشير إلى عنوان URL نفسه |
utm_content=logolink
utm_content=textlink
|