شروع به کار با Google Analytics برای iOS+‎

انتخاب پلاتفرم: iOS+ Android وب Flutter Unity C++


این شروع سریع به شما نشان می‌دهد که چگونه Google Analytics را به برنامه خود اضافه کنید و شروع به ثبت رویدادها کنید.

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 را به پروژه‌تان اضافه کنید تا ویژگی‌های اضافی مثل مخاطبان و اسناددهی پویش فعال شود.

کیت توسعه نرم‌افزار Analytics را به برنامه‌تان اضافه کنید

از Swift Package Manager برای نصب و مدیریت وابستگی‌های Firebase استفاده کنید.

  1. در Xcode، درحالی‌که پروژه برنامه‌تان باز است، به File > Add Packages (فایل > افزودن بسته‌ها) بروید.
  2. وقتی خواسته شد، مخزن کیت توسعه نرم‌افزار Firebase برای پلاتفرم‌های Apple را اضافه کنید:
    3.   https://github.com/firebase/firebase-ios-sdk.git
  3. کتابخانه Analytics را انتخاب کنید.
  4. پرچم -ObjC را به بخش Other Linker Flags (سایر پرچم‌های پیونددهنده) در تنظیمات ساخت هدف اضافه کنید.
  5. برای تجربه بهینه با Analytics، توصیه می‌کنیم Google Analytics را فعال کنید در پروژه Firebase خود و افزودن کیت توسعه نرم‌افزار Firebase برای Google Analytics به برنامه خود. می‌توانید کتابخانه را بدون مجموعه IDFA یا با مجموعه IDFA انتخاب کنید. پرسشگان ما را درباره جدیدترین سازمان‌دهی واحدها در 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 استفاده می‌کنید، باید یک نماینده برنامه ایجاد کنید و آن را ازطریق UIApplicationDelegateAdaptor یا NSApplicationDelegateAdaptor به ساختار App خود متصل کنید. همچنین باید swizzling نماینده برنامه را غیرفعال کنید. برای اطلاعات بیشتر، دستورالعمل‌های 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

برای راحتی شما، کیت توسعه نرم‌افزار به‌طور خودکار برنامه شما را در Apple برای ارجاع شبکه آگهی با SKAdNetwork ثبت می‌کند. اگر می‌خواهید این ویژگی را غیرفعال کنید، مقدار GOOGLE_ANALYTICS_REGISTRATION_WITH_AD_NETWORK_ENABLED را در فایل info.plist برنامه‌تان روی NO (بولی) تنظیم کنید.

شروع کردن ثبت رویدادها

پس‌از پیکربندی نمونه 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، اشکال‌زدایی Analytics را فعال کنید:

  1. در Xcode، Product > Scheme > Edit scheme... (محصول > طرح > ویرایش طرح...) را انتخاب کنید
  2. اجرا را از منوِ سمت راست انتخاب کنید.
  3. برگه استدلال‌ها را انتخاب کنید.
  4. در بخش Arguments Passed On Launch، -FIRAnalyticsDebugEnabled را اضافه کنید.

مراحل بعدی