تتبُّع الأحداث في WebView باستخدام "إحصاءات Google لبرنامج Firebase"

1. مقدمة

تاريخ آخر تعديل: 2022-02-25

ما ستنشئه

في هذا الدرس التطبيقي حول الترميز، ستتعرّف على كيفية إعادة توجيه الأحداث من صفحة ويب ضِمن WebView إلى رمز برمجي أصلي لكي تتمكّن "إحصاءات Google لـ Firebase"‏ (GA4F) من تتبُّع الأحداث.

سنستخدم نموذج تطبيق Android المختلط الذي يستدعي صفحة ويب باستخدام WebView.

ما ستتعلمه

• كيفية إعداد "إحصاءات Google لبرنامج Firebase"‏ (GA4F) في تطبيق مختلط
• كيفية إنشاء أحداث ومَعلمات مخصّصة في صفحة ويب
• كيفية إعادة توجيه الأحداث على صفحة ويب ضمن WebView إلى رمز برمجي أصلي
• كيفية تصحيح الأخطاء
• كيفية استيراد الأحداث واستخدامها في "حملات تحثّ على اتّخاذ إجراء"

المتطلبات

• الإصدار 3.6 من "استوديو Android" أو إصدار أحدث
• حساب Firebase

2. الإعداد

الحصول على الرمز

يوفّر الدليل الرسمي لـ Firebase رمزًا نموذجيًا على GitHub. نحتاج إليها في هذا المشروع.

للبدء، عليك تنزيل الرمز وفتحه في بيئة التطوير المفضّلة لديك. سنستخدم دليلَين : android وweb. دليل "android" مخصّص لتطبيق Android، ودليل "web" مخصّص لصفحة ويب سيتم استدعاؤها من خلال التطبيق باستخدام WebView.

3- إنشاء مشروع Firebase وإعداده

لبدء استخدام Firebase، عليك إنشاء مشروع على Firebase وإعداده.

إنشاء مشروع Firebase

1. سجِّل الدخول إلى Firebase.

في وحدة تحكّم Firebase، انقر على إضافة مشروع (Add Project) أو إنشاء مشروع (Create a project)، وأطلِق على مشروعك في Firebase اسم Webview-test-codelab أو أي اسم آخر تريده.

2. انقر على خيارات إنشاء المشروع. اقبَل بنود Firebase إذا طُلب منك ذلك. عليك تفعيل "إحصاءات Google" لهذا المشروع، لأنّك تحتاج إلى أحداث "إحصاءات Google" لتتبُّع أحداث الإجراءات وتحليل الإحالات الناجحة.

لمزيد من المعلومات عن مشاريع Firebase، اطّلِع على مقالة التعرّف على مشاريع Firebase.

4. إعداد Firebase على Android

ضبط إعدادات Android في وحدة تحكّم Firebase

1. في الصفحة الرئيسية لوحدة تحكّم Firebase، يمكنك النقر على رمز Android كما هو موضّح أدناه.

أو يمكنك الانتقال إلى نظرة عامة على المشروع في شريط التنقّل الأيمن، والنقر على الزر Android ضِمن "بدء الاستخدام من خلال إضافة Firebase إلى تطبيقك".

بعد ذلك، ستظهر لك شاشة "إضافة Firebase إلى تطبيق Android" كما هو موضّح أدناه.

2. يمكنك العثور على اسم حزمة Android (مثلاً com.xxxx.myproject) في android/app/src/main/AndroidManifest.xml في دليل تطبيقك.

package="com.xxxx.myproject"

3. لا يلزم استخدام مفتاح SHA-1 هنا. لا تحتاج إلى هذا المفتاح إلا إذا كنت تريد استخدام تسجيل الدخول باستخدام حساب Google أو روابط Firebase الديناميكية أو استيراد بيانات عمليات الشراء داخل التطبيق من Google Play، وهو ما لا يندرج ضمن نطاق هذا الدرس التطبيقي حول الترميز.
4. انقر على تسجيل التطبيق.
5. نزِّل ملف الإعداد google-services.json في وحدة تحكّم Firebase، ثم انسخ هذا الملف والصقه في الدليل android/app في مشروع تطبيقك.
6. في وحدة تحكّم Firebase، تخطَّ الخطوات المتبقية وارجع إلى الصفحة الرئيسية لوحدة تحكّم Firebase.
7. أخيرًا، تحتاج إلى المكوّن الإضافي في خدمات Google لأداة Gradle لقراءة ملف google-services.json الذي أنشأته Firebase.
8. في بيئة التطوير المتكاملة (IDE) أو المحرّر، افتح android/app/build.gradle، ثم أضِف السطر التالي كسطر أخير في الملف:

apply plugin: 'com.google.gms.google-services'

13. فتح "android/build.gradle" بعد ذلك، أضِف اعتمادية جديدة داخل العلامة buildscript.

buildscript { 
   repositories {
      // ...
   }
   dependencies {
      // ...
      Classpath 'com.google.gms:google-services:4.3.3'
   }
}

14. إذا كان تطبيقك لا يزال قيد التشغيل، أغلقه وأعِد إنشائه للسماح لـ Gradle بتثبيت التبعيات.

لقد انتهيت من إعداد تطبيقك على Android.

5- تطوير واجهة ويب لخدمة "إحصاءات Google" على الويب وتسجيل الأحداث المخصّصة

لتتبُّع الأحداث في WebView باستخدام "إحصاءات Google"، عليك إدراج الرمز في كلّ من الويب وتطبيق Android.

في هذا الجزء، سنلقي نظرة على الرمز الذي عليك وضعه في صفحة الويب.

أولاً، أنشِئ ملف جافا سكريبت لاستخدامه في ملف HTML. في الرمز النموذجي، تتم تسمية ملف js باسم index.js. عليك إنشاء الدالة "logEvent" لاستدعاء "AnayticsWebInterface" على Android و "messageHander" على iOS كما هو موضّح في الرمز البرمجي أدناه.

واستدعِ هذه الدالة في المكان الذي تريد تتبُّع الحدث فيه في ملف HTML كما هو موضّح أدناه.

عندما يتم تشغيل حدث في WebView في تطبيق Android، سيتم استدعاء "window.AnalyticsWebInterface" وسيتم إعادة توجيه الحدث إلى رمز WebInterface في التطبيق.

6. استضافة دليل الويب للحصول على عنوان URL لصفحة الويب

قبل طلب صفحة ويب ضمن WebView في تطبيقك، تحتاج إلى عنوان URL لصفحة الويب. ستتوفّر العديد من الطرق لاستضافة صفحات الويب. في هذا الدرس التطبيقي حول الترميز، سنستخدم خدمة استضافة Firebase لتسهيل العملية.

• في نافذة الأوامر، أدخِل دليل الويب (مثلاً cd web) ونفِّذ الأوامر التالية:
• npm install -g firebase-tools

سيؤدي ذلك إلى تثبيت Firebase CLI.

• firebase login
• firebase init
• اختَر "الاستضافة" عندما يُطلب منك تحديد الميزة التي تريد إعدادها.
• اختَر المشروع الذي أعددته لتطبيق Android.
• اقبل الإعدادات التلقائية لجميع الطلبات المتبقية.
• firebase deploy --only hosting - النشر على Firebase Hosting

• بعد الحصول على عنوان URL لصفحة الويب، انتقِل إلى مشروع تطبيقك في "استوديو Android" وأدرِج عنوان URL لصفحة الويب الذي تم إنشاؤه في هذه الخطوة ضِمن WebView على النحو التالي.

7. تطوير رمز الواجهة في تطبيق Android

لتتبُّع الأحداث في WebView باستخدام "إحصاءات Google لـ Firebase"، عليك إدراج الرمز في كلّ من الويب وAndroid. في هذا الجزء، لنلقِ نظرة على الرمز الذي عليك وضعه في تطبيق Android لتلقّي الأحداث من صفحة الويب في WebView.

أنشئ ملف "AnalyticsWebInterface.java" لإنشاء فئة "AnalyticsWebInterface". في هذه الفئة، عليك ترميز ‎ @JavascriptInterface لربط الدالة logEvent في ملف js على الويب كما هو موضّح أدناه.

بعد ذلك، عليك إضافة واجهة JavaScript في النشاط الذي يستدعي WebView على النحو التالي.

للاطّلاع على الرمز الكامل، يُرجى الرجوع إلى الرمز النموذجي الذي نزّلته من GitHub في خطوة "الإعداد".

8. التحقّق من الأحداث وتصحيح أخطائها

لتصحيح أخطاء الأحداث، يمكنك استخدام الرمز التالي في نافذة Terminal في استوديو Android بعد ربط الجهاز الاختباري أو تشغيل المحاكي.

‎> adb shell setprop debug.firebase.analytics.app [اسم حزمة التطبيق]

‎> adb shell setprop log.tag.FA VERBOSE

> adb shell setprop log.tag.FA-SVC VERBOSE

> adb logcat -v time -s FA FA-SVC

انقر على "تسجيل الحدث 1" (LOG EVENT 1) في تطبيقك، وإذا كانت التعليمات البرمجية تعمل بشكل جيد، سيظهر لك السجلّ كما هو موضّح أدناه.

إذا كنت تريد التحقّق من ذلك في وحدة تحكّم Firebase، يمكنك أيضًا استخدام علامة التبويب "الوقت الفعلي". انتقِل إلى "وحدة تحكّم Firebase" وانقر على علامة التبويب "في الوقت الفعلي" كما هو موضّح أدناه.

بعد ذلك، يمكنك فلترة حدث نظام Android الأساسي باستخدام وظيفة "إضافة مقارنة".

ستظهر لك الأحداث من تطبيق Android في علامة التبويب "الوقت الفعلي" إذا تم تنفيذ الرمز بشكلٍ صحيح.

بعد بضع ساعات، يمكنك الاطّلاع على الأحداث المسجَّلة في علامة التبويب "الأحداث" في وحدة تحكّم Firebase. ما عليك سوى النقر على علامة التبويب الأحداث من قسم "إحصاءات Google" في "وحدة تحكّم Firebase". يمكنك أيضًا التحقّق من القيم داخل الحدث event1 من خلال النقر على الحدث.

لاستيراد event1 كإحالة ناجحة في "إعلانات Google"، ضَع علامة عليها كإحالة ناجحة من خلال تحريك مفتاح التبديل وضع علامة كإحالة ناجحة إلى اليسار.

إذا كان الحدث في علامة التبويب "الإحالات الناجحة"، يعني ذلك أنّه تمّ تصنيف الحدث بنجاح كإحالة ناجحة. ستتمكّن "إعلانات Google" الآن من استيراد هذا الحدث من Firebase.

لأغراض تصحيح الأخطاء، استخدِم أداة DebugView في Firebase. لمزيد من التفاصيل، راجِع مقالة تصحيح خطأ حدث.

9- استيراد أحداث الإحصاءات في "إعلانات Google"

بعد اكتمال عملية الإعداد في Firebase، تكون جاهزًا لإطلاق "حملات التطبيقات" التي تتضمّن أحداث الإجراءات. ابدأ بربط Firebase بحساب "إعلانات Google". من خلال ربط Firebase بحساب "إعلانات Google"، يمكن لحملات التطبيقات استيراد أحداث Firebase. تساعد هذه العملية أيضًا "إعلانات Google" في تعزيز "حملات التطبيقات" من خلال السماح لها بالتعرّف على المزيد من المعلومات عن شرائح الجمهور.

1. انتقِل إلى إعدادات Firebase من خلال النقر على الزرّ بجانب نظرة عامة على المشروع.
2. في علامة التبويب عمليات الدمج، ستظهر إعلانات Google وزر ربط. انقر على ربط، ثمّ انقر على متابعة.

3. اختَر حسابًا على "إعلانات Google".

تنبيه: إذا لم يتم تصنيف الحدث المستهدَف على أنّه حدث إحالة ناجحة، لن تتمكّن "إعلانات Google" من استيراده. تأكَّد من وضع علامة الإحالة الناجحة على الحدث بشكلٍ صحيح.

انتهى الآن الجزء المتعلّق بـ Firebase.

انتقِل إلى إعلانات Google.

1. سجِّل الدخول، وانتقِل إلى الأدوات والإعدادات > القياس > الإحالات الناجحة لاستيراد الأحداث المخصّصة كإحالات ناجحة.
2. انقر على الزرّ + لإضافة إجراءات إحالات ناجحة جديدة.

3. اختَر مواقع "إحصاءات Google‏ 4" (Firebase) وانقر على متابعة.

4. يمكنك الاطّلاع على جميع أحداث "إحصاءات Google" التي تمّ تصنيفها كإحالات ناجحة. ابحث عن حدث event1 الذي نفّذناه سابقًا.

5. ضَع علامة في المربّع بجانب الإجراء، ثمّ انقر على استيراد، ثمّ انقر على متابعة.

بعد ضبط event1 كإجراء إحالة ناجحة، يمكنك إطلاق "حملات تحثّ على اتّخاذ إجراء داخل التطبيق" باستخدام حدث event1.

10. إطلاق "حملات تحثّ على اتّخاذ إجراء داخل التطبيق" باستخدام الأحداث المستورَدة

ملاحظة مهمة: لإطلاق "حملة تطبيقات" بنجاح، عليك الحصول على تطبيق بمستوى إصدار علني في Google Play. ومع ذلك، إذا لم تكن مستعدًا للنشر بعد، يمكنك تخطّي هذه الخطوة في الوقت الحالي.

6. انتقِل إلى علامة تبويب الحملة في حسابك الحالي، وابدأ حملة جديدة بالنقر على الزر +. انقر على [حملة جديدة]، ثمّ انقر على متابعة.
7. أطلِق "حملة ترويج للتطبيقات" باستخدام الخيار عمليات تثبيت التطبيق.

8. ابحث عن تطبيقك عن طريق كتابة اسم التطبيق أو اسم الحزمة أو الناشر.
9. في قسم عروض الأسعار، اختَر الإجراءات داخل التطبيق من القائمة المنسدلة.
10. ابحث عن الحدث المخصّص في القائمة المتوفّرة. حدِّد سقف التكلفة المحدد لكل إجراء، وأكمِل أي خيارات إضافية.

11. أكمِل إعدادات حملتك.

11. تهانينا

تهانينا، لقد نجحت في دمج حسابك على Firebase مع حسابك على "إعلانات Google". سيساعدك ذلك في تعزيز أداء حملتك باستخدام أحداث Firebase المستورَدة.

لقد تعلّمت

• كيفية إعداد "إحصاءات Google لبرنامج Firebase"‏ (GA4F) في تطبيق مختلط
• كيفية إنشاء أحداث ومَعلمات مخصّصة في صفحة ويب
• كيفية إعادة توجيه الأحداث على صفحة ويب ضمن WebView إلى رمز برمجي أصلي
• كيفية تصحيح الأخطاء
• كيفية استيراد الأحداث واستخدامها في "حملات تحثّ على اتّخاذ إجراء"

12. المراجع

الدليل الرسمي

• استخدام "إحصاءات Google" في WebView - Firebase - Google

إعداد Firebase و"إعلانات Google"

• استخدام "إعلانات Google" مع الأحداث المخصّصة في "إحصاءات Google لـ Firebase" على Android
• إطلاق حملات على "إعلانات Google" باستخدام الأحداث المخصّصة في "إحصاءات Google" وFlutter