إرسال أحداث التطبيقات إلى "إحصاءات Google 4" باستخدام Measurement Protocol

1. مقدمة

تاريخ آخر تعديل: 2021-06-08

ما ستنشئه

في هذا الدرس التطبيقي حول الترميز، ستتعلّم كيفية إرسال أحداث خارجية إلى "إحصاءات Google‏ 4" باستخدام Measurement Protocol.

يفترض هذا الدرس العملي أنّ لديك تطبيقًا تمّ تنفيذ "إحصاءات Google لبرنامج Firebase" فيه. إذا أردت معرفة كيفية الدمج مع "إحصاءات Google لبرنامج Firebase"، يُرجى الرجوع إلى هذا الدرس العملي أولاً. إذا أردت التعرّف على كيفية إنشاء تطبيق باستخدام Firebase، يُرجى الرجوع إلى Codelab-Build Friendly Chat على Firebase لنظام التشغيل Android.

ما ستتعلمه

  • خطوات إرسال الطلب الأول عبر Measurement Protocol
  • فهم المعلَمات اللازمة لإرسال الطلب
  • إرسال طلب تجريبي والتحقق من صلاحيته
  • إنشاء نموذج نص برمجي في Python لإجراء المكالمة

المتطلبات

  • تطبيق Android أو iOS
  • أي بيئة تطوير متكاملة لإجراء تغييرات
  • حساب "إحصاءات Google‏ 4"
  • اختياري - بيئة تطوير Python (أو Colab)

2. جمع الحقول الإلزامية

إنشاء سرّ واجهة برمجة التطبيقات في "إحصاءات Google‏ 4"

انتقِل إلى "إحصاءات Google‏ 4" وأنشِئ واجهة سرّية جديدة لواجهة برمجة التطبيقات من خلال الانتقال إلى المشرف > مصادر البيانات > اختَر مصدر بياناتك > Measurement Protocol > إنشاء.

6e4afca63054d291.png

c9e9ccd2ffba98eb.png

e714cd969fca4a4d.png

يمكنك تقديم أي اسم مستعار، وسيتم عرض قيمة المفتاح السرّي التي يمكنك استخدامها في مكالمتك

في حال عدم معرفة كيفية الوصول إلى "إحصاءات Google‏ 4"، يمكنك الانتقال إلى مشروعك على Firebase، والاطّلاع على إعدادات المشروع > عمليات الدمج > "إحصاءات Google"، ثم النقر على "إدارة". من المفترض أن يظهر الربط بحساب "إحصاءات Google"، ويمكنك الانتقال مباشرةً من هناك أيضًا.

73b4d77a57eddfba.png

جمع app_instance_id

يمكنك استخدام أيّ من الطرق أدناه لجمع app_instance_id.

  1. استخدام BigQuery Export
  2. جلب البيانات بشكل أصلي في رمز المصدر لتطبيقك

يتم توضيح كلّ منهما بالتفصيل أدناه

  1. استخدام BigQuery Export

إذا كانت ميزة التصدير إلى BigQuery مفعّلة، يمكنك اتّباع الخطوات التالية

  • تسجيل الدخول إلى Firebase
  • انتقِل إلى "إعدادات المشروع" > "عمليات الدمج" > BigQuery
  • انقر على "عرض في BigQuery" بجانب مجموعة البيانات

ملاحظة : لن تتوفّر مجموعة البيانات إلا بعد تفعيل زر التبديل لمدة تتراوح بين 24 و48 ساعة تقريبًا.

63d061088b622961.png

  • في BigQuery، يمكنك البحث عن user_pseudo_id في الجدول. هذا هو app_instance_id الذي يمكنك استخدامه في مكالمتك

4b1b80bdc2884581.png

  1. استرجاع البيانات بشكلٍ أصلي في رمز مصدر تطبيقك

إذا تم إنشاء تطبيقك باستخدام Java، يمكنك استخدام ما يلي لاسترداد app_instance_id

 FirebaseAnalytics.getInstance(this).getAppInstanceId().addOnCompleteListener(new OnCompleteListener<String>() {
        @Override
        public void onComplete(@NonNull Task<String> task) {
            if (task.isSuccessful()) {
                String user_pseudo_id = task.getResult();
            }
        }
    });

بالنسبة إلى Kotlin، يمكنك تجربة ما يلي

Thread {
   Firebase.analytics.appInstanceId.addOnSuccessListener { user_pseudo_id ->
       Log.d("Firebase", "user_pseudo_id using appInstanceId is $user_pseudo_id")
       /*
       Store the value to your server or do something with the retrieved id
        */
   }
}.start()

إذا كان لديك تطبيق iOS، يمكنك استخدام ما يلي في Swift

let user_pseudo_id = Analytics.appInstanceID()
print("user_pseudo_id = \(user_pseudo_id)")
/*
Store the value to your server or do something with the retrieved id
*/

في ما يلي المزيد من الروابط حسب البنية الأساسية التي تستخدمها

3- إنشاء المكالمة

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

fd78d961f3e48238.png

يجب ملء الحقول التالية

  • api_secret - تم إنشاؤه سابقًا في "إحصاءات Google‏ 4"
  • ‫firebase_app_id: للحصول على هذا المعرّف، يمكنك الانتقال إلى المشرف > مصادر البيانات > اختيار مصدر البيانات . يجب أن يظهر على النحو التالي

19801c8e5cb29222.png

  • app_instance_id - سبق لك استرداد هذه القيمة
  • ‫user_id ليس حقلًا إلزاميًا. يمكنك ترك هذا الحقل فارغًا في الوقت الحالي
  • الفئة: غيِّر هذه القيمة إلى "مخصّص" من القائمة المنسدلة، وأدخِل أي اسم حدث من اختيارك (لا تستخدِم أي حدث مجمّع تلقائيًا). نستخدم هنا "test_from_codelab"

54cce53df64d697.png

يمكنك أيضًا اختيار تقديم مَعلمات الأحداث و/أو خصائص المستخدِمين من خلال النقر على الأزرار أدناه

16a8f531a3894021.png

بعد ملء كل المعلومات، من المفترض أن يظهر لك ما يلي، مع زر "تأكيد الحدث"

475801f25c3caf26.png

بعد الوصول إلى هذه الصفحة، انقر على "التحقّق من صحة الحدث" (VALIDATE EVENT)، وهو الزرّ المميّز باللون البرتقالي. من المفترض أن تظهر الرسالة أدناه، موضّحةً أنّ الحدث صالح، وسيظهر لك زرّ "الإرسال إلى "إحصاءات Google"". في هذه المرحلة، إذا ظهرت الفعالية على أنّها غير صالحة، ستخبرك الأداة بالحقل الذي يتضمّن مشكلة بالتحديد، ويمكنك إصلاحها وإعادة المحاولة.

23e4e6800705b4aa.png

يمكنك الآن النقر على الزر، ومن المفترض أن يرسل حدثًا تجريبيًا إلى "إحصاءات Google‏ 4".

4. التحقّق من صحة الأحداث في "إحصاءات Google‏ 4"

بعد إرسال الحدث، يمكنك الانتقال إلى حسابك على "إحصاءات Google‏ 4" والتحقّق من تقرير "الوقت الفعلي". من المفترض أن يظهر لك الحدث

994b51ca46bb1973.png

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

إذا كنت تواجه مشاكل أو تفاوتات، قد يكون من المفيد الاطّلاع على القيود المعروفة في Measurement Protocol هنا.

5- إنشاء نص برمجي بلغة Python

بعد أن جرّبت ذلك، يمكنك فحص طلب البيانات من واجهة برمجة التطبيقات وحِزمة بيانات الحدث لإنشاء بنية مشابهة في Python (أو أي لغة تختارها) يمكنها إجراء هذا الطلب. يمكنك بعد ذلك جدولة هذا التقرير بمعدّل التكرار الذي تريده وتفعيله. في هذه المرحلة، يمكنك استخدام أي بيئة تطوير متكاملة (IDE) من اختيارك تتوافق مع Python أو استخدام ملف Google Colab notebook الذي لا يتطلب أي تثبيت على جهازك.

بالرجوع إلى "أداة إنشاء الأحداث" في "إحصاءات Google‏ 4"، ستلاحظ أنّ نقطة النهاية هي كما يلي

POST /mp/collect?firebase_app_id=XXXX&api_secret=XXXX 
HTTP/1.1
Host: www.google-analytics.com

كانت حمولة الحدث كما يلي

{
  "app_instance_id": XXXX,
  "non_personalized_ads": false,
  "events": [
    {
      "name": "test_from_codelab",
      "params": {
        "test_param": "test_123"
      }
    }
  ]
}

يمكنك ترجمة ذلك إلى Python باستخدام ما يلي

import requests
import json
url = "https://www.google-analytics.com/mp/collect?firebase_app_id=XXXX&api_secret=XXXX"
payload = {
  "app_instance_id": XXXX,
  "non_personalized_ads": False,
  "events": [
    {
      "name": "test_from_codelab",
      "params": {
        "test_param": "test_123"
      }
    }
  ]
}
r = requests.post(url,data=json.dumps(payload),verify=True)
print(r.status_code)

بعد تنفيذ ذلك بالقيم الصحيحة، من المفترض أن يظهر الحدث بشكل مشابه في الوقت الفعلي في "إحصاءات Google‏ 4".

6. تهانينا

تهانينا، لقد استخدمت Measurement Protocol بنجاح في "إحصاءات Google‏ 4". يمكنك الآن إنشاء تصميمات حلول فعّالة لإرسال بيانات أكثر دلالة إلى "إحصاءات Google" وتحسين تحليلات التسويق والأنشطة التجارية. للاستفادة إلى أقصى حدّ من هذه الميزة، نقترح عليك أيضًا الربط بحساب "إعلانات Google" واستيراد هذه الأحداث كإحالات ناجحة. يمكنك الرجوع إلى الخطوة 6 في هذا الدرس التطبيقي حول الترميز للحصول على تعليمات تفصيلية حول ذلك. لأغراض تتبُّع الإحالات الناجحة، لن تعرض "إعلانات Google" سوى البيانات المرتبطة بمعرّف المعلِن على الأجهزة الجوّالة أو معرّفات الأجهزة التي تم جمعها من حزمة تطوير البرامج (SDK) في Firebase خلال آخر 60 يومًا. يُرجى العِلم أنّ هذه الواجهة لا تزال في مرحلة الإصدار الأوّلي، ويجب الاطّلاع على القيود الواردة هنا والتي سيتم حلّها قبل الإطلاق الكامل.

لقد تعلّمت

  • كيفية جمع المتغيّرات المناسبة لإجراء طلبات قياس
  • كيفية إرسال أحداث اختبارية والتحقّق من صحتها
  • كيفية إنشاء برنامج نصي لإرسال طلبات بحث عن "المنتجات في المتجر"