بدء استخدام "إحصاءات Google"


يوضّح لك دليل البدء السريع هذا كيفية إضافة Google Analytics إلى تطبيقك و بدء تسجيل الأحداث.

تجمع Google Analytics بيانات الاستخدام والسلوك لتطبيقك. تسجِّل حزمة SDK نوعَين أساسيَين من المعلومات:

  • الأحداث: ما يحدث في تطبيقك، مثل إجراءات المستخدمين أو أحداث النظام أو الأخطاء
  • خصائص المستخدِمين: هي السمات التي تحدّدها لوصف شرائح قاعدة المستخدِمين، مثل اللغة المفضّلة أو الموقع الجغرافي.

تسجِّل Analytics تلقائيًا بعض الأحداث وخصائص المستخدم، ولن تحتاج إلى إضافة أي رمز لتفعيلها.

قبل البدء

أضِف Firebase إلى مشروع JavaScript وتأكَّد من تفعيل Google Analytics في مشروع Firebase:

  • إذا كنت بصدد إنشاء مشروع جديد على Firebase، فعِّل Google Analytics أثناء سير عمل إنشاء المشروع.

  • إذا كنت تستخدم مشروعًا حاليًا في Firebase لم يتم تفعيل "Google Analytics" فيه، انتقِل إلى علامة التبويب عمليات الدمج ضمن > إعدادات المشروع لتفعيله.

عند تفعيل Google Analytics في مشروعك، يتم ربط تطبيقات الويب في Firebase بمصادر بيانات Google Analytics المرتبطة بأحد مواقع التطبيقات + المواقع الإلكترونية.

إضافة حزمة تطوير البرامج (SDK) لمنصّة Analytics إلى تطبيقك

استنادًا إلى طريقة استضافة تطبيق الويب، قد تتم معالجة الإعدادات تلقائيًا أو قد تحتاج إلى تعديل عنصر إعدادات Firebase. إذا كان تطبيقك على الويب يستخدِم "إحصاءات Google"، قد تحتاج إلى إجراء عملية إعداد إضافية описанَة في مقالة استخدام Firebase مع وضع العلامات الحالي باستخدام مقتطف gtag.js.

  1. تأكَّد من أنّ عنصر إعدادات Firebase في الرمز البرمجي يحتوي على measurementId. يتم إنشاء هذا المعرّف تلقائيًا عند تفعيل Analytics في مشروعك على Firebase وتسجيل تطبيق ويب، وهو مطلوب لاستخدام Analytics.

    • إذا كان تطبيقك يستخدم Firebase Hosting و يستخدم عناوين URL محجوزة لحِزم تطوير البرامج (SDK) لمنصّة Firebase:

      تتولى Firebase تلقائيًا ضبط إعدادات تطبيقك. لإكمال عملية الإعداد، أضِف النصوص البرمجية من بطاقة تطبيقاتك في إعدادات المشروع إلى علامة <body> في تطبيقك، إذا لم يسبق لك إجراء ذلك.

    • إذا كان تطبيقك لا يستخدم عناوين URL محجوزة: إذا كنت تعمل مع تطبيق ويب حالي، عدِّل عنصر إعدادات Firebase في الرمز البرمجي لضمان توفّر الحقل measurementId. من المفترض أن يبدو كائن الضبط مشابهًا للمثال التالي:

      // For Firebase JavaScript SDK v7.20.0 and later, `measurementId` is an optional field
const firebaseConfig = {
  apiKey: "AIzaSyCGQ0tYppWFJkuSxBhOpkH0xVDmX245Vdc",
  authDomain: "project-id.firebaseapp.com",
  databaseURL: "https://project-id.firebaseio.com",
  projectId: "project-id",
  storageBucket: "project-id.appspot.com",
  messagingSenderId: "637908496727",
  appId: "2:637908496727:web:a4284b4c99e329d5",
  measurementId: "G-9VP01NDSXJ"
};

  2. ثبِّت حزمة تطوير البرامج (SDK) لـ Firebase JS وفعِّل Firebase، إذا لم يسبق لك إجراء ذلك.

  3. أضِف حزمة تطوير البرامج (SDK) لـ Analytics JS وفعِّل Analytics:

Web 

import { initializeApp } from "firebase/app";
import { getAnalytics } from "firebase/analytics";

// TODO: Replace the following with your app's Firebase project configuration
// See: https://firebase.google.com/docs/web/learn-more#config-object
const firebaseConfig = {
  // ...
};

// Initialize Firebase
const app = initializeApp(firebaseConfig);


// Initialize Analytics and get a reference to the service
const analytics = getAnalytics(app);

Web 

import firebase from "firebase/compat/app";
import "firebase/compat/analytics";

// TODO: Replace the following with your app's Firebase project configuration
// See: https://firebase.google.com/docs/web/learn-more#config-object
const firebaseConfig = {
  // ...
};

// Initialize Firebase
firebase.initializeApp(firebaseConfig);


// Initialize Analytics and get a reference to the service
const analytics = firebase.analytics();

استخدام Firebase مع وضع علامات gtag.js الحالية

إذا سبق لك تشغيل "إحصاءات Google" في تطبيقك باستخدام مقتطف gtag.js، قد يتطلب تطبيقك إعدادًا إضافيًا إذا كنت تخطط لتنفيذ أحد الإجراءات التالية:

  • أضِف طلبات Google Analytics من Firebase إلى الصفحة، ولكن خطِّط أيضًا ل مواصلة استخدام طلبات gtag() مباشرةً في الصفحة نفسها.
  • تريد استخدام رقم تعريف القياس نفسه بين كلّ من مكالمات gtag() المباشرة وبيانات Google Analytics المُرسَلة إلى Firebase.

لضمان إمكانية استخدام الأحداث من خلال جميع خدمات Firebase، أكمِل خطوات الإعداد الإضافية التالية:

  • أزِل السطر gtag('config', 'GA_MEASUREMENT_ID'); حيث يكون GA_MEASUREMENT_ID هو measurementId لتطبيق الويب Firebase. إذا كانت لديك معرّفات أخرى لمواقع "إحصاءات Google" أخرى في الصفحة، لن تحتاج إلى إزالة سطر الإعداد الخاص بها.
  • احرص على الاتصال بـ firebase.analytics() قبل إرسال أي أحداث مع gtag().

بخلاف ذلك، لن تكون الأحداث المُرسَلة إلى هذا المعرّف من خلال طلبات gtag() مرتبطة بـ Firebase ولن تكون متاحة لاستهدافها في خدمات Firebase الأخرى.

بدء تسجيل الأحداث

بعد بدء استخدام خدمة "إحصاءات Google"، يمكنك البدء في تسجيل الأحداث باستخدام الأسلوب logEvent().

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

يوضِّح المثال التالي كيفية تسجيل حدث مقترَح للإشارة إلى أنّ المستخدم قد تلقّى إشعارًا في تطبيقك:

Web

import { getAnalytics, logEvent } from "firebase/analytics";

const analytics = getAnalytics();
logEvent(analytics, 'notification_received');
analytics_log_event.js

Web

firebase.analytics().logEvent('notification_received');
index.js

الخطوات التالية