Share
If you’ve been using Firebase Analytics (
aka Google Analytics for Firebase, aka Google Analytics
) for a while, you probably know about the automatic “screen_view” event. While easy to implement (because it is enabled out of the box and requires no effort) and well-intentioned in theory, in practice, this event often does a less than perfect job of measuring app screen transitions. This is mostly because the Firebase SDK is entirely in charge of deciding when to log the event. For some app designs, this works out okay, but for others, you can wind up with extra screen_view events, or more often, no screen_view events. Long story short, we typically have recommended that clients ignore the screen_view event and use a custom event instead, but with the recent updates to the Firebase iOS and Android SDKs, that is changing.
The examples above show how you can override the value of the screen_class parameter (which shows up in Firebase and your Google Analytics App + Web property as “firebase_screen_class”), should you want to do so. By default, the Firebase SDK will pass the name of the current UIViewController or Activity, and that is usually sufficient, but if you are doing something creative like swapping views (or Fragments) you may want to pass the name of the view or Fragment class to aid in debugging. Otherwise, you can just omit the screen class parameter.
A technical fine-point for Android apps:
The example above shows the screen_view logged in onResume (either
Activity#onResume
or
Fragment#onResume
). While onStart is often the most logical place to record a “screenview” event because it correlates with the UI becoming visible to the user, due to esoteric technical reasons involving the Android lifecycle and how Firebase uses it, the SDK will complain when you try to log the screen_view in Activity#onStart. Until Activity#onStart completes, Firebase considers the app to still be in the background and it won’t record the screen_view. Instead, you will see the following somewhat confusing warning in Logcat:
“W/FA: Cannot log screen view event when the app is in the background.”
To avoid this, just log your screen_view events in onResume. (Technically, if you’re swapping in Fragments rather than starting new Activities, once the Activity housing the Fragments is in the foreground you can log the screen_view event in Fragment#onStart if you prefer, but if you run into any “background” warnings just revert to onResume.)
To confirm that automatic screen tracking is disabled, you should see the following in your Xcode log when your app launches:
On Android, you will need to add a <meta-data> element to your AndroidManifest.xml file, inside the <application> element as follows:
There is no confirmation in Logcat that automatic tracking is disabled, but you will see entries for “V/FA: Logging screen view with name, class” when you log the event manually.
Now that you can manually log screen_view events and set the screen_name value that way, setScreenName and setCurrentScreen have been deprecated. They will continue to work for the near future, but if you are using these methods in your apps, it is time to start planning a transition to the new approach. While we are sad to say goodbye to such useful friends, the new approach to screenview tracking is definitely a big step forward and we’re glad the Firebase team has decided to put the app in control. As the world transitions to App + Web in the coming years, this new approach will make app screen tracking much cleaner and more flexible.
The way it was
In its original incarnation, the automatic “screen_view” event was logged by the Firebase SDK whenever it detected a change in UIViewController (iOS) or Activity (Android). If all of the “screens” in your app were created with distinct UIViewControllers or Activities, this model worked reasonably well, at least as far as timing went. Events got logged automatically when the user perceived a screen change. But if your app design involved swapping views in and out of a UIViewController (or swapping Android Fragments in an Activity), none of those transitions got noticed and you would miss events. And because Firebase reserved the “screen_view” event name, you couldn’t log the event directly, and you couldn’t supply custom event parameters. All you could report on were the limited parameters that the Firebase SDK included, most notably screen class (aka “firebase_screen_class”). Screen class defaulted to the name of the current UIViewController or Activity, which may have been of interest to the dev team, but the names of these technical components were often gobbledygook to marketing analysts. The setScreenName (iOS) and setCurrentScreen (Android) methods provided the ability to set an “analyst friendly” screen name, but you had to pepper your apps with calls to these methods, which largely undid the convenience of the “automatic” screen tracking. Plus, calling these methods would trigger an additional screen_view event, often throwing the counts off. As I said, well-intentioned, but suboptimal in practice.The new model
Recent updates to the Firebase SDK ( 6.29.0 on iOS and 17.5.0 on Android ) allow you to disable automatic screen tracking and manually log the screen_view event when it makes sense, regardless of your app’s design. And you can even add custom parameters to the event! So the screen_view event can now effectively function like a custom event, but with the benefit of setting the screen name for subsequent events. To facilitate this, the Firebase SDK on iOS now defines three new Objective-C constants: kFIREventScreenView , kFIRParameterScreenName and kFIRParameterScreenClass (aka AnalyticsEventScreenView , AnalyticsParameterScreenName and AnalyticsParameterScreenClass in Swift). On Android, the new constants are Event.SCREEN_VIEW , Param.SCREEN_NAME , and Param.SCREEN_CLASS , respectively. To manually log a screen_view event, do something like this: The examples above show how you can override the value of the screen_class parameter (which shows up in Firebase and your Google Analytics App + Web property as “firebase_screen_class”), should you want to do so. By default, the Firebase SDK will pass the name of the current UIViewController or Activity, and that is usually sufficient, but if you are doing something creative like swapping views (or Fragments) you may want to pass the name of the view or Fragment class to aid in debugging. Otherwise, you can just omit the screen class parameter.
A technical fine-point for Android apps:
The example above shows the screen_view logged in onResume (either
Activity#onResume
or
Fragment#onResume
). While onStart is often the most logical place to record a “screenview” event because it correlates with the UI becoming visible to the user, due to esoteric technical reasons involving the Android lifecycle and how Firebase uses it, the SDK will complain when you try to log the screen_view in Activity#onStart. Until Activity#onStart completes, Firebase considers the app to still be in the background and it won’t record the screen_view. Instead, you will see the following somewhat confusing warning in Logcat:
“W/FA: Cannot log screen view event when the app is in the background.”
To avoid this, just log your screen_view events in onResume. (Technically, if you’re swapping in Fragments rather than starting new Activities, once the Activity housing the Fragments is in the foreground you can log the screen_view event in Fragment#onStart if you prefer, but if you run into any “background” warnings just revert to onResume.)
How to disable automatic screen tracking
On iOS, to disable automatic screen tracking so that you can assume control of the screen_view event, you will need to add a Boolean “FirebaseAutomaticScreenReportingEnabled” key to your Info.plist file and set it to the value of “NO". To confirm that automatic screen tracking is disabled, you should see the following in your Xcode log when your app launches:
On Android, you will need to add a <meta-data> element to your AndroidManifest.xml file, inside the <application> element as follows:
There is no confirmation in Logcat that automatic tracking is disabled, but you will see entries for “V/FA: Logging screen view with name, class” when you log the event manually.
Goodbye setScreenName and setCurrentScreen
In the original “automatic” screen tracking incarnation, setScreenName (iOS) and setCurrentScreen (Android) were needed for two things: To force a screen_view event when the Firebase SDK wasn’t detecting the need for one, and to set the value of the screen name parameter. As mentioned above, we were never fans of using the automatic screen_view event, so forcing more of them was never something we cared about. But the second feature (setting the value of the screen name parameter) was something we really liked because once you set the screen name, it was automatically appended to every subsequent event until the next time the method was called. This made it easy to identify where in the app each event was logged without having to pass a custom parameter.
Now that you can manually log screen_view events and set the screen_name value that way, setScreenName and setCurrentScreen have been deprecated. They will continue to work for the near future, but if you are using these methods in your apps, it is time to start planning a transition to the new approach. While we are sad to say goodbye to such useful friends, the new approach to screenview tracking is definitely a big step forward and we’re glad the Firebase team has decided to put the app in control. As the world transitions to App + Web in the coming years, this new approach will make app screen tracking much cleaner and more flexible.