The latest Google Analytics for Firebase SDK release now makes it possible for you to log the screen_view event manually for both Android and iOS!

When you add the Google Analytics for Firebase SDK to your app, there are a number of different events that start getting collected automatically - including the screen_view event for your Android and iOS apps.

This event is incredibly important to understand your users’ behavior since it can tell you the number of users who have visited each screen in your app, and which screens are the most popular. In addition, this event powers the Behavior reports offered in Google Analytics’s App + Web properties, which can tell you how much time users spend in each screen. It also powers the Path Analysis tool where you can discover the most popular navigational paths within your app.

Behavior overview reporting page

Path analysis technique

Most of the automatically collected events, including screen_view, use protected event names that prevent you from being able to manually log events with the same name. There are good reasons for doing this because a lot of these events power other Firebase products, like A/B Testing and Firebase Predictions, and first class reporting features in Google Analytics.

But we’ve heard a lot of your feedback - and screen_view is one event for which you wanted more control over how and when the event gets logged - in addition to having the option to continue logging events automatically.

So our latest release now makes this possible. This release also marks the deprecation of the setCurrentScreen (on Android) and setScreenName (on iOS) methods which will be replaced by the new calls to manually log the screen_view event.

There are many benefits to having more control for when the screen_view event gets logged:

1. Only log screen_view events that are meaningful in your app
   For example, you might only want to log a screen_view event when a user has spent at least some minimum amount of time on the screen.

   In fact, you might recall that Google Analytics previously logged session_start events ten seconds after an app first loaded into the foreground. While this has changed and session_start events are logged immediately, there can be instances in your app when it makes sense to wait a few seconds before logging a meaningful screen_view.

   In a video streaming app, users may often load up a title selection screen and quickly scroll through and select a series they’ve already been watching to pick up where they left off. They might not really be searching for new titles, even though they’re visiting the title screen, and you’ll want to only log screen views here when you really know that they’re looking for new titles, not just quickly scrolling through it.

2. Log screen_view events for important sections and subscreens in your app
   Your app might have subsections in some screens (think “Container View Controllers” with inner Child VCs or Fragments), or in the case of a game or a Flutter app, be driven by one screen that powers other views that present meaningful actions a user can take, or represent places in your app where users will spend a significant amount of time. In such cases, you might want to log a screen_view event manually, and add additional event parameters that represent the subsections of your app that your users spend more time exploring.

   A good example here is an app that provides a customer support chat interface that overlays onto an existing screen the user is viewing. In such cases, you might want to log a manual screen_view event that represents that chat interface and that can collect more information in added event parameters - like which topic or which screen the user was on before they opened the support chat window.

In addition to the reasons above, there was an issue on iOS devices with automatically collected screen_view events using the soon-to-be-deprecated setScreenName method in which the events were dual-logged. This change also corrects this issue so it is no longer a factor.

How to manually log a screen_view event

You can log a manual screen_view just like you would any other event in Google Analytics. You can also include the two optional parameters (i) screen_name and (ii) screen_class, as well as any custom event parameters you want to include. The two optional parameters take the place of the firebase_screen and firebase_screen_class event parameters that get passed into automatically collected screen_view events.

Specifically for iOS, this would look like:

override func viewDidAppear(_ animated: Bool) {
    super.viewDidAppear(animated)

    // After enough time has passed to make this screen view significant.
    Analytics.logEvent(AnalyticsEventScreenView, parameters: [
        AnalyticsParameterScreenName: screenName!,
        AnalyticsParameterScreenClass: screenClass!,
        MyAppAnalyticsParameterFitnessCategory: category!
    ])
}

And for Android:

@Override
public void onResume() {
    super.onResume();

    // After enough time has passed to make this screen view significant.
    Bundle bundle = new Bundle();
    bundle.putString(FirebaseAnalytics.Param.SCREEN_NAME, screenName);
    bundle.putString(FirebaseAnalytics.Param.SCREEN_CLASS, screenClass);
    bundle.putString(MyAppAnalyticsConstants.Param.TOPIC, topic);
    mFirebaseAnalytics.logEvent(FirebaseAnalytics.Event.SCREEN_VIEW, bundle);
}

As mentioned before, the new API will allow you to log manual screen_view events along with the option to continue collecting screen_view events automatically. Since both are possible at the same time, let’s get into some questions to learn more about how the new feature works with the existing automatic event collection.

Can I disable automatically collected screen_view events and only use manual logging?

Yes. While you can use both together at the same time, you can disable automatic event collection for screen_view events if you’d like. On iOS, set FirebaseAutomaticScreenReportingEnabled to “NO” in your info.plist. On Android, set google_analytics_automatic_screen_reporting_enabled to “false” in your manifest.

What changes do I need to make to migrate from the setScreenName / setCurrentScreen method calls?

The setScreenName and setCurrentScreen method calls were used to set a custom-defined screen name as the firebase_screen_name parameter value included with all automatically logged screen_view events. If you want to continue collecting custom screen names on your screen_view events, you will need to log the screen_view event manually and pass in the screen_name event parameter (likely using the same value you were using in the soon-to-be deprecated methods).

Note that for automatically reported screen_view events, the screen name value will be left blank, and the screen class value will be set to that of the most recently shown screen.

If you disable automatic screen reporting, some values are still accessible and can be automatically added to your manually logged screen_view events, such as the firebase_screen_class parameter.

This is because parameters like the screen class are first-class metrics that feed into Google Analytics’ Behavior Reports, and so we’ve gone the extra mile to automatically populate this field using information we know on the client. On Android, the current activity will be used to populate the screen class parameter. On iOS, if you make a call to the logEvent() method, the root UIViewController will be used to populate the screen class value. You can always overwrite this value by passing in a different screen_class parameter, though. On both platforms the screen name will be left blank (unless you specify it), and the value “not set” will be displayed in the Google Analytics console.

Do other event parameters that get passed into automatically collected screen_view events also get passed into manually logged screen_view events?

Yes, all event parameters that are reported along with automatically collected screen_view events will also be automatically reported with manually logged screen_view events - with one temporary exception for the engagement_time_msec on iOS devices. We are working on implementing support to have the engagement time parameter included with manually reported screen_view events on iOS, but for the time being this parameter isn’t included and instead, is reported on a designated user_engagement event.

We hope you enjoy the new ability to manually log your screen view events, and would love to hear more feedback from you about this feature, or about the Google Analytics for Firebase SDK for your apps in general. Please reach out to us at our Firebase Google Group, on StackOverflow or on our Firebase Support channel to submit your feature requests.