بدء استخدام "إحصاءات Google" لنظام التشغيل iOS+

اختيار المنصة: iOS+ Android الويب Flutter Unity C++‎


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

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

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

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

للحصول على مساعدة مستنِدة إلى الذكاء الاصطناعي، انسخ الطلب أدناه إلى وكيل الترميز بالذكاء الاصطناعي (مثل Antigravity وClaude Code وCodex وCursor). يمكنك تخصيص الطلب وتكراره مع وكيلك. يمكنك الانتقال إلى مهارات وكلاء Firebase للحصول على معلومات مفصّلة عن التثبيت. 

Help me use Firebase in my app.
1. Make sure that **Firebase agent skills** are installed and updated. For Claude Code, Codex, or Cursor agents, help me install the Firebase plugin. For other agents, run `npx skills add firebase/agent-skills`.  Always try to use **Firebase agent skills** for Firebase-related tasks.
2. Help me set up Google Analytics for Firebase and log screen view events in my app.

قبل البدء

  1. أضِف Firebase إلى مشروع Apple الخاص بك، في حال لم يسبق لك إجراء ذلك، وتأكَّد من تفعيل Google Analytics في مشروع Firebase:

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

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

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

  2. (يُنصح به) أضِف إطار عمل AdSupport إلى مشروعك لتفعيل ميزات إضافية، مثل شرائح الجمهور وتحديد المصدر في الحملات.

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

استخدِم Swift Package Manager لتثبيت تبعيات Firebase وإدارتها.

  1. في Xcode، افتح مشروع تطبيقك، ثم انتقِل إلى ملف > إضافة حِزم (File > Add Packages).
  2. عندما يُطلب منك ذلك، أضِف مستودع حزمة تطوير البرامج (SDK) لمنصات Apple من Firebase:
    3.   https://github.com/firebase/firebase-ios-sdk.git
  3. اختَر مكتبة "Analytics".
  4. أضِف العلامة -ObjC إلى قسم علامات الربط الأخرى (Other Linker Flags) في إعدادات إنشاء الهدف.
  5. للحصول على تجربة مثالية مع Analytics، ننصحك بتفعيل Google Analytics في مشروع Firebase وإضافة Firebase SDK لمنصّة إحصاءات Google إلى تطبيقك. يمكنك اختيار المكتبة التي لا تتضمّن ميزة جمع معرّفات المعلِنين (IDFA) أو التي تتضمّنها. يمكنك الاطّلاع على الأسئلة الشائعة حول أحدث تنظيم للوحدات في حزمة تطوير البرامج (SDK) لمنصّة Google Analytics لبرنامج Firebase.
  6. بعد الانتهاء، سيبدأ Xcode تلقائيًا في حلّ التبعيات وتنزيلها في الخلفية.

يمكنك الاطّلاع على مزيد من المعلومات عن معرّف المعلِنين (IDFA)، وهو معرّف الإعلانات على مستوى الجهاز، في مستندات Apple حول خصوصية المستخدم واستخدام البيانات و شفافية تتبُّع التطبيقات.

بعد ذلك، نفِّذ بعض خطوات الضبط:

  1. استورِد وحدة FirebaseCore في UIApplicationDelegate، بالإضافة إلى أي وحدات Firebase أخرى يستخدمها مفوَّض تطبيقك. على سبيل المثال، لاستخدام Cloud Firestore وAuthentication:

    SwiftUI

    import SwiftUI
import FirebaseCore
import FirebaseFirestore
import FirebaseAuth
// ...

    Swift

    import FirebaseCore
import FirebaseFirestore
import FirebaseAuth
// ...

    Objective-C

    @import FirebaseCore;
@import FirebaseFirestore;
@import FirebaseAuth;
// ...
  2. اضبط مثيلاً مشتركًا من النوع FirebaseApp في طريقة application(_:didFinishLaunchingWithOptions:) لمفوَّض تطبيقك:

    SwiftUI

    // Use Firebase library to configure APIs
FirebaseApp.configure()

    Swift

    // Use Firebase library to configure APIs
FirebaseApp.configure()

    Objective-C

    // Use Firebase library to configure APIs
[FIRApp configure];
  3. إذا كنت تستخدم SwiftUI، عليك إنشاء مفوَّض تطبيق وإرفاقه ببنية App من خلال UIApplicationDelegateAdaptor أو NSApplicationDelegateAdaptor. يجب أيضًا إيقاف ميزة "تبديل مفوّض التطبيق". لمزيد من المعلومات، يمكنك الاطّلاع على تعليمات SwiftUI.

    SwiftUI

    @main
struct YourApp: App {
  // register app delegate for Firebase setup
  @UIApplicationDelegateAdaptor(AppDelegate.self) var delegate

  var body: some Scene {
    WindowGroup {
      NavigationView {
        ContentView()
      }
    }
  }
}


(اختياري) إيقاف تسجيل تحديد المصدر في شبكة إعلانات Apple

لتسهيل الأمر عليك، تعمل حزمة تطوير البرامج (SDK) تلقائيًا على تسجيل تطبيقك لدى Apple لتحديد مصدر شبكة الإعلانات باستخدام SKAdNetwork. إذا أردت إيقاف هذه الميزة، اضبط قيمة GOOGLE_ANALYTICS_REGISTRATION_WITH_AD_NETWORK_ENABLED على NO (قيمة منطقية) في ملف info.plist الخاص بتطبيقك.

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

بعد ضبط مثيل FirebaseApp، يمكنك البدء في تسجيل الأحداث باستخدام طريقة logEvent().

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

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

Swift

Analytics.logEvent("share_image", parameters: [
  "name": name,
  "full_text": text,
])

Objective-C

[FIRAnalytics logEventWithName:@"share_image"
                    parameters:@{
                                 @"name": name,
                                 @"full_text": text
                                 }];

للاطّلاع على هذا الحدث في وحدة تحكّم تصحيح الأخطاء في Xcode، فعِّل تصحيح أخطاء "إحصاءات Google":

  1. في Xcode، انقر على المنتج (Product) > المخطّط (Scheme) > تعديل المخطّط… (Edit scheme…‎).
  2. انقر على تشغيل (Run) من القائمة اليمنى.
  3. انقر على علامة التبويب الوسيطات (Arguments).
  4. في قسم المَعلمات التي تم ضبطها عند الإطلاق (Arguments Passed On Launch)، أضِف -FIRAnalyticsDebugEnabled.

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