Apple tvOS Tracking with Google Analytics 4 Properties


October 26, 2020

Google recently announced that Google Analytics (GA) is getting its most significant update ever with the release of Google Analytics 4 properties. In 2015, Apple released tvOS, and Adswerve was the first to provide an open library for the Universal Analytics version of Google Analytics. With the release of the new Google Analytics 4 properties and the rollout of its new Measurement Protocol library, we are excited to share a new version of tvOS tracking for Google Analytics 4 properties. (Huge thanks to my colleague Chris Hubbard for bringing this to life.)

Note: Measurement Protocol is still an alpha release from Google, and everything provided should be considered experimental. Important limitations and known limitations are shared below.

Getting Started with tvOS tracking for Google Analytics 4

You can find our GitHub project here. The library is written in Swift and modeled after the Firebase Analytics SDK. Using this code should be very familiar if you are used to logging events and setting user properties with Firebase. Just add the “GA4MPClient.swift” file to your Xcode project, and grab a reference to the shared Measurement Protocol client instance. Then, you can use the Measurement Protocol client to log events, set user properties, etc. For example:

Create a reference to the shared client instance:

let mpClient = GA4MPClient.shared

To log an event with parameters:

mpClient.logEvent("tvos_event_with_params", parameters: ["screen_name": "the screen", "pointless_message": "yes it is"])

To log an event without parameters:

mpClient.logEvent("tvos_event_no_params", parameters: nil)

To set a user property:

mpClient.setUserProperty("test value", forName: "tvos_test_prop")

For a complete set of usage examples for the tvOS library, see the README file.

Important Note about Limitations

As noted above, the new Measurement Protocol is currently an alpha release, so functionality may change and all of the issues mentioned are expected to be addressed as the product matures. Here are a few known limitations:

  • Firebase’s “automatic” events are currently reserved and will be rejected by the GA server when sent via Measurement Protocol. This makes it impossible to log a screen_view event, or a session_start, etc. This may result in certain reports looking very strange with the UI.
  • Measurement Protocol is currently required to attach to a web or app stream, which results in the tvOS analytics not being treated as a first-class citizen within Google Analytics 4 properties.
  • DebugView is not currently supported.

For more information about the new Measurement Protocol, see Google’s official documentation. If you need any help or support with connected devices, Measurement Protocol, or Google Analytics 4 properties, you can reach out to our team at wecanhelp@adswerve.com.