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


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

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

  • الأحداث: ما يحدث في تطبيقك، مثل إجراءات المستخدمين أو أحداث النظام أو الأخطاء

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

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

قبل البدء

أضِف 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. يجب أن يبدو كائن config مشابهًا للمثال التالي:

      // For Firebase JavaScript SDK v7.20.0 and later, `measurementId` is an optional field
const firebaseConfig = {
  apiKey: "API_KEY",
  authDomain: "PROJECT_ID.firebaseapp.com",
  databaseURL: "https://PROJECT_ID.firebaseio.com",
  projectId: "PROJECT_ID",
  storageBucket: "PROJECT_ID.firebasestorage.app",
  messagingSenderId: "SENDER_ID",
  appId: "APP_ID",
  measurementId: "G-GA_MEASUREMENT_ID"
};

  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() المباشرة و data 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

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