إرسال أحداث التطبيقات إلى "إحصاءات 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 > إنشاء.

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

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

جمع app_instance_id

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

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

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

استخدام BigQuery Export

إذا كانت ميزة BigQuery Export مفعّلة، يمكنك اتّباع الخطوات التالية:

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

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

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

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

إذا تم إنشاء تطبيقك باستخدام 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".

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

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

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

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

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

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

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

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

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

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

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

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

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

بالرجوع إلى "أداة إنشاء الأحداث" في "إحصاءات 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" سوى البيانات المرتبطة بمعرّف المعلِنين (IDFA) أو معرّفات الأجهزة التي تم جمعها من Firebase SDK في Firebase خلال آخر 60 يومًا. يُرجى العِلم أنّ هذه الواجهة لا تزال في مرحلة الإصدار الأوّلي، ويجب الاطّلاع على القيود الواردة هنا والتي يجب حلّها قبل الإطلاق الكامل.

لقد تعلّمت

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

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