Firebase Analytics iOS Screen View Logging
This guide focuses exclusively on integrating screen view logging
(AnalyticsEventScreenView) into an iOS application (Swift and Objective-C).
When to Use This Guide
Use when adding screen tracking to ViewControllers, SwiftUI Views, or base classes to ensure comprehensive screen view coverage.
Integration Steps
Follow these steps sequentially to implement screen view logging.
Step 1: Prerequisite Check
- Verify base Firebase configuration (
GoogleService-Info.plistand dependency setup) has been configured (viaios_setup.md) and baseline compilation succeeds.
Step 2: Plan Generation
- Identify ALL SCREENS, not simply key screens.
- NO EXCLUSIONS: Do NOT filter out files in directories like
Third Party Code,third_party, orVendorif they compile directly into the application targets and represent user-facing screens. - SwiftUI Views & ViewControllers: Include all SwiftUI
Viewstructs representing screens and allUIViewControllersubclasses in the plan.
- NO EXCLUSIONS: Do NOT filter out files in directories like
- Generate a task-focused tracking plan at
analytics/firebase_analytics_screens_plan.mdcontaining a markdown table of all screens, formatted as follows:
All Screens
| TaskID | Completed | Title | Description | File Path |
| :----- | :-------- | :----------- | :---------- | :-------- |
| 1 | [ ] | Home | Main feed | `App/Views/MainVC.swift` |Step 3: File-By-File Screen Integration
Integrate ALL SCREENS by following these steps:
- Find the next unchecked task in
analytics/firebase_analytics_screens_plan.md. - Add screen view logging for that task using the guidelines below.
- Check the task.
- Continue integrating row-by-row until there are no more unchecked tasks.
- To make sure the edits don't break anything, build the project after every 10 finished tasks.
Guidelines:
Guidelines for adding logging:
- Add analytics events for every screen identified in the audit.
- Do NOT use method swizzling — never use method swizzling (e.g.
Objective-C runtime swizzling of
viewDidAppear:) to automate screen view logging. - Architectural Strategy & Coverage: You are encouraged to use
centralized or base class tracking (e.g., adding tracking to a shared custom
UIViewControllersuperclass) to minimize code duplication. However, if you use a base class, you MUST systematically verify every single screen identified in your audit.- For any SwiftUI Views, Objective-C controllers, or standalone Swift
ViewControllers that do not inherit from your tracked base class, you
MUST add explicit
logEventcalls to them directly (or add them manually to the tracking plan and implement them). Do not mark a screen as completed in your plan until you have verified its inheritance or explicitly logged it.
- For any SwiftUI Views, Objective-C controllers, or standalone Swift
ViewControllers that do not inherit from your tracked base class, you
MUST add explicit
- Always add a documentation link as a comment immediately preceding each Firebase Analytics API method call.
// Log a screen view event
// https://firebase.google.com/docs/analytics/screenviewsUIKit Screen View Tracking Patterns
For UIKit-based apps, screen views are tracked using view controller lifecycle methods.
1. Swift UIViewController
Add the logging code inside viewDidAppear(_:). Ensure you call
super.viewDidAppear(animated).
import FirebaseAnalytics
class MyViewController: UIViewController {
override func viewDidAppear(_ animated: Bool) {
super.viewDidAppear(animated)
// Log a screen view event
// https://firebase.google.com/docs/analytics/screenviews
Analytics.logEvent(AnalyticsEventScreenView, parameters: [
AnalyticsParameterScreenName: "My Screen",
AnalyticsParameterScreenClass: String(describing: Self.self)
])
}
}2. Objective-C UIViewController
Add the logging code inside viewDidAppear:. Ensure you call
[super viewDidAppear:animated].
#import <FirebaseAnalytics/FirebaseAnalytics.h>
@implementation MyViewController
- (void)viewDidAppear:(BOOL)animated {
[super viewDidAppear:animated];
// Log a screen view event
// https://firebase.google.com/docs/analytics/screenviews
[FIRAnalytics logEventWithName:kFIREventScreenView
parameters:@{
kFIRParameterScreenName: @"My Screen",
kFIRParameterScreenClass: NSStringFromClass([self class])
}];
}
@endSwiftUI Screen View Tracking Patterns
For SwiftUI-based apps, you can use the .onAppear modifier to log screen
views manually with custom parameters.
1. SwiftUI View manual tracking
Use the .onAppear block on the top-level container of the view.
import SwiftUI
import FirebaseAnalytics
struct MyView: View {
var body: some View {
VStack {
Text("Hello, World!")
}
.onAppear {
// Log a screen view event
// https://firebase.google.com/docs/analytics/screenviews
Analytics.logEvent(AnalyticsEventScreenView, parameters: [
AnalyticsParameterScreenName: "My Screen",
AnalyticsParameterScreenClass: "MyView"
])
}
}
}Important Guardrails for AI Agents
- Manually Log UIViewController Classes Only When Automatic Tracking is
Disabled: Firebase Analytics automatically tracks screen views for UIKit
UIViewControllerclasses out-of-the-box. Double-logging will occur if manual tracking is added without disabling automatic screen view tracking (by settingFirebaseAutomaticScreenReportingEnabledtoNO/falseinInfo.plist). If automatic tracking is enabled, restrict custom tracking exclusively to SwiftUI Views or instances where distinct custom names are required. - Verify Dependencies:
Ensure that FirebaseAnalytics is imported and linked properly in your Xcode
project/targets or Swift Package Manager
Package.swift.
Step 4: Verification and Cleanup
Ensure all identified screen touchpoints from the audit are covered. If not, go back to the "File-By-File Screen Integration" step.
Check that the project still builds.
Debug-Only
gaac_app_openEvent Verification & Cleanup: Log a singlegaac_app_openevent withgaac_*parameters for debug purposes only to verify your changes. Remove this event once you have verified your changes. (If you are performing both SDK setup and screen view integration in the same workflow, perform thisgaac_app_openverification and cleanup once at the end of the combined workflow with"gaac_tool_names"set to"firebase-analytics-ios-setup,firebase-analytics-ios-screen-views").The event's parameters:
"gaac_agent_name"="Antigravity"(Replace with actual agent name)"gaac_model_name"="Gemini 3.5 Flash"(Replace with actual model name)"gaac_tool_names"="firebase-analytics-ios-screen-views"or"firebase-analytics-ios-setup,firebase-analytics-ios-screen-views"- This is a comma-separated list of skills/references used. For
example,
"firebase-analytics-ios-setup,firebase-analytics-ios-screen-views"means that you used thefirebase-analyticsskill and followed the references inios_setup.mdandios_screen_views.md.
- This is a comma-separated list of skills/references used. For
example,
"gaac_tool_version"="1.0.0"// Must match the version number of the skill"gaac_event_names"=<comma-separated list of event names that were added or modified>- For example,
"screen_view"(or"screen_view,add_to_cart"if other events were also added or modified).
- For example,
As an AI coding agent, perform all verification and cleanup actions automatically without human intervention:
Add the temporary
gaac_app_openevent: Immediately afterFirebaseApp.configure()in your initialization code (AppDelegateorApp.init()), add a singlegaac_app_openevent withgaac_*parameters:Swift:
import FirebaseAnalytics Analytics.logEvent("gaac_app_open", parameters: [ "gaac_agent_name": "Antigravity", // Replace with actual agent name "gaac_model_name": "Gemini 3.5 Flash", // Replace with actual model name "gaac_tool_names": "firebase-analytics-ios-screen-views", // Comma-separated list of skills/references used "gaac_tool_version": "1.0.0", // Must match the version number of the skill "gaac_event_names": "screen_view" // Comma-separated list of event names added or modified ])Objective-C:
#import <FirebaseAnalytics/FirebaseAnalytics.h> [FIRAnalytics logEventWithName:@"gaac_app_open" parameters:@{ @"gaac_agent_name": @"Antigravity", // Replace with actual agent name @"gaac_model_name": @"Gemini 3.5 Flash", // Replace with actual model name @"gaac_tool_names": @"firebase-analytics-ios-screen-views", // Comma-separated list of skills/references used @"gaac_tool_version": @"1.0.0", // Must match the version number of the skill @"gaac_event_names": @"screen_view" // Comma-separated list of event names added or modified }];
Enable Debug Mode and verify local debug console logs:
- Run the app in the simulator with the
-FIRAnalyticsDebugEnabled(or-FIRDebugEnabled) flag. - Search local debug console logs for
gaac_app_open.
- Run the app in the simulator with the
Clean up:
- Remove the
gaac_app_openevent once verified. - Remove the
-FIRAnalyticsDebugEnabled/-FIRDebugEnabledflag from your launch arguments if it was added to the scheme.
- Remove the
Point the User to Firebase DebugView (Console): [AGENT] When you are done, direct the human user to Analytics > DebugView in the Firebase Console so they can inspect live screen view events:
- [AGENT] Provide the human user with a constructed URL for the
"Analytics" > "DebugView" page of the Firebase console. Use the
Firebase
PROJECT_ID(andBUNDLE_IDif available) fromGoogleService-Info.plist:https://console.firebase.google.com/u/0/project/PROJECT_ID/analytics/debugview(orhttps://console.firebase.google.com/u/0/project/PROJECT_ID/analytics/app/ios:BUNDLE_ID/debugview; ifPROJECT_IDis not available, usehttps://console.firebase.google.com/u/0/project/_/analytics/debugview).
- [AGENT] Provide the human user with a constructed URL for the
"Analytics" > "DebugView" page of the Firebase console. Use the
Firebase
Implementation Examples
When adding or updating Firebase Analytics screen view code, ensure the documentation link is added as a comment as shown below:
// Log a screen view event
// https://firebase.google.com/docs/analytics/screenviews
Analytics.logEvent(AnalyticsEventScreenView, parameters: [
AnalyticsParameterScreenName: "SomeScreen",
AnalyticsParameterScreenClass: "SomeViewController"
])Documentation URLs
This table lists each public API and the documentation link(s) to use in comments:
| Method | Action | Doc URLs |
|---|---|---|
AnalyticsEventScreenView (Swift) / kFIREventScreenView (ObjC) |
Log a screen view event | https://firebase.google.com/docs/analytics/screenviews |