Send App Data To Server-side Google Tag Manager

A recent update to the Firebase SDK included the following information:

The Google Analytics SDKs for Android and for iOS now support integration with server-side tag manager. Review the implementation steps in the guide to server-side tagging for mobile apps.

This was a very welcome addition to server-side Google Tag Manager. For long, we’ve been waiting for app contexts to catch up with the web when it comes to taking control of the data flows using server-side tagging.

In this article, I’ll show you how to set everything up. I’m using an iOS app as the example.

In any case, I do recommend you check out the official implementation guide – it’s comprehensive and has instructions for an Android installation, too.

Prerequisites

This article assumes the following:

1. You have an iOS app and you have access to its codebase (d’oh).
2. That app is running the latest version of the Firebase SDK and the Firebase Analytics SDK.
3. You have connected the app to Google Analytics 4 for analytics measurement purposes.
4. You have a server-side Google Tag Manager container up and running.

The changes you need to make in order to stream your app data to server-side Google Tag Manager aren’t too complicated.

However, you do need to edit a few different places, so it’s important to make sure you have all the required bits and pieces available, and it’s important to follow this guide meticulously.

Edit the app Info.plist

The Info.plist file is usually stored in your project root. You can edit it with a text editor, or you can use Xcode to make the required changes.

Above, circled in red, are the new items you need to add to Info.plist. Make sure you get the bundle identifiers and types configured correctly.

Update URL identifier so that it has your app’s bundle identifier as its value. If you don’t know the app’s bundle ID, the easiest way to find it is to go to Google Analytics 4 and open the data stream settings for your app property.

Edit the first item under URL Schemes, too. Its value should be tagmanager.sgtm.c.<bundle ID>. So in my example app, it should be:

tagmanager.sgtm.c.simo.iOSTest

If you want to edit the Info.plist file in your favorite code editor, the new information is added to the top <dict> element of the file:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>UIApplicationSceneManifest</key>
  ...
  <!-- THESE ARE THE NEW ENTRIES YOU NEED TO ADD -->
  <key>CFBundleURLTypes</key>
  <array>
    <dict>
      <key>CFBundleTypeRole</key>
      <string>None</string>
      <key>CFBundleURLName</key>
      <string>simo.<BUNDLE ID></string>
      <key>CFBundleURLSchemes</key>
      <array>
        <string>tagmanager.sgtm.c.<BUNDLE ID></string>
      </array>
    </dict>
  </array>
  <key>GOOGLE_ANALYTICS_SGTM_UPLOAD_ENABLED</key>
  <true/>
</dict>
</plist>

In the code above, make sure you update the two <BUNDLE ID> references to your app’s correct bundle identifier.

Enable server-side Google Tag Manager preview mode

Previewing app requests in server-side Google Tag Manager is a bit different from the web, again.

Instead of visiting a URL so that preview cookies are dropped, you need to scan a QR code that opens the app on your device with the information required for preview mode to work.

To allow the app to be opened with the QR code link, you need to add some code to a lifecycle method. I’m using UIScene in my app, so I’m adding the code to SceneDelegate.swift like this. Adjust your app code as necessary:

import UIKit
import FirebaseAnalytics

class SceneDelegate: UIResponder, UIWindowSceneDelegate {

    var window: UIWindow?

    func scene(_ scene: UIScene, willConnectTo session: UISceneSession, options connectionOptions: UIScene.ConnectionOptions) {
        ...
        // THIS IS THE NEW CODE:
        if let urlContext = connectionOptions.urlContexts.first {
            let url = urlContext.url
            Analytics.handleOpen(url)
        }
        ...

To actually preview the app (once everything is up and running), you need to go to Preview mode in server-side Google Tag Manager, click the little overflow menu in the top right corner, and select Send requests from an app.

Once you click that, you need to add your app’s bundle identifier again, and then scan the QR code with your device that has the app. This should open a browser, where a pop-up should appear asking you to open the app in question. Once you open the app through this prompt, any requests to your GA4 property will be dispatched to server-side GTM Preview mode.

Just note that you still need to complete the rest of the guide steps before Preview mode works properly!

Just one more thing to do before you can test things.

Enable rerouting to server-side GTM in your GA4 property settings

This final step is, in my view, the biggest nuisance. For server-side tagging to work, you must have a functioning GA4 property.

This means that it’s impossible to do a completely isolated setup, where you only use the Firebase Analytics SDK as the dispatch mechanism. You must have GA4 enabled, because that’s where the Firebase Analytics SDK gets its configuration signals from.

In the GA4 property you’ve linked to your app, browse to Admin -> Data collection and modification -> Data streams. Here, select the data stream for the app you’re configuring.

In the data stream Settings, click Configure SDK settings, and here click Configure server-side Tag Manager.

In the next screen, toggle the Send data to a server-side Tag Manager container, and then fill in your Server container URL.

You can then choose whether to reroute app measurement data for Debug devices only, or for a percentage of traffic (25%, 50%, 75%, or 100%).

Needless to say, start with debug devices, and then ramp up slowly once you’ve verified that everything works.

Once you make this change, the Firebase Analytics SDK will receive the new configuration from GA4, and your app should start sending data to your server-side tagging endpoint.

It might take some time for the changes to propagate! If you don’t see any data flowing to server-side Google Tag Manager, be patient. If you’re using Xcode, you can try cleaning the build folder and then rebuilding the app.

Add a GA4 (App) Client in server-side Google Tag Manager

One more thing you need to do is add a Client in server-side Google Tag Manager for GA4 (App) requests. There’s a built-in Client for that purpose, and it doesn’t require any configuration.

Save the Client once you’ve created it.

Test that it works

Now, you can open your app by scanning the QR code found in the server-side Google Tag Manager Preview mode (see above for instructions).

If all works as intended, you should start seeing app-measurement requests in Preview mode when your app dispatches Firebase Analytics events.

The GA4 (App) Client automatically handles them and parses them for the constituent events.

If you’re using just Xcode to test your app, you should first enable Firebase logging in your product scheme:

After that, you can run the app and look for references to your server-side tagging endpoint:

You can also look for corresponding request rows in your server-side tagging logs (such as Logs Explorer if you’re using the Google Cloud Platform).

If you don’t see any requests in server-side GTM Preview mode (or logs), and if you don’t see references to your server-side endpoint in Xcode logs, chances are that the change hasn’t propagated yet to your Firebase SDK configuration, so be patient and try in an hour or so again.

It could also be that you messed something up in the implementation, so go over the steps of this blog again to verify it works.

What is actually sent to SGTM

So now let’s get to the interesting part. There are those /app-measurement requests, but what do they actually comprise?

Well, the request is a POST request with the parameters sent in the POST body as a serialized protobuf. If you’re using Preview mode, it handily deserializes the body:

The body contains a lot of metadata about the request, the device, and the app. It also contains a bundle of events dispatched from the app. These events are parsed by the Client into event data objects, and by selecting the events in Preview mode, you can jump into the Event Data tab to analyze what information is available to your tags.

For example, here’s what the Event Data object for a regular screen_view event contains:

This is fascinating stuff! Firebase Analytics has always been something of a black box, and trying to decipher what is dispatched with those requests has required the installation of special tools and proxies to get to the bottom of it.

With server-side GTM rerouting, you still need to do some additional configuration, but at least this time you can actually utilize the debug streams efficiently.

What next?

You’re now collecting Firebase measurement requests to server-side Google Tag Manager. Great!

One obvious thing you’ll need to do is create a Google Analytics 4 tag for those Firebase Analytics events. Assuming you want to collect the data to GA4 – but nothing’s forcing you to do this! You could just as well use Firebase Analytics as the incoming stream and then dispatch the data to some completely different location, bypassing Google Analytics 4 entirely!

The Google Analytics 4 tag in SGTM is the same one you would use for web hits. The tag automatically takes the app-measurement payload and converts it to GA4 format.

It parses the event data object before compiling the outgoing protobuf payload – the cool thing is that this means you can use Transformations to modify what the GA4 tag actually “sees”.

For example, in this request, I’ve used an Augment Event Transformation to change the event name to test-event and to add a new test-param event parameter:

You can also see how the request is not dispatched to the “regular” GA4 collection endpoint /collect, but instead it’s sent to the app-measurement.com endpoint the app would normally communicate with.

This is why the request body is serialized back into protobuf format.

It’s a bit of a shame that GA4 is built like this, with totally distinct app and web streams. They could have built a consolidated endpoint that collects data from either source. This separated approach means that collection is even more of a black box, especially considering how much metadata is sent to GA4 servers with app requests.

So what about Facebook Conversions API? What about Piwik PRO? What about Amplitude? These are solutions that have dedicated templates built for GA4 events.

Well, they definitely won’t work as smoothly out of the box with Firebase measurement data.

You’ll need to do a lot more enriching in the app code to make sure that the tags get all the data they need. After all, many of the solutions rely on first-party cookies (not available in apps) or data generated by Google Tag (not available in apps).

Summary

I sincerely hope that there will be more blog posts and guides released by the wonderful measurement community for working with Firebase measurement data in server-side Google Tag Manager.

For example, the Facebook Conversions API is a hot topic, and for it to work with app measurement data, a Campaign ID parameter needs to be collected as an additional parameter at the very least. This ID links the app session with the deep link or app-to-app click from the Facebook app.

Now, I think there are many good things about the Firebase SDK setup. It’s wonderful we finally have transparency to what the Firebase measurement stream actually looks like. Similarly, seeing how that stream is compiled into an Event Data object by the GA4 (App) Client in server-side Google Tag Manager speaks volumes.

This is a great opportunity for reverse engineers to better understand how the mythical world of Firebase app measurement works!

My biggest gripe, and it does grind my gears, is that you still need a GA4 property to configure the dispatch with. This is very different from web measurement, where you could just use a dummy Measurement ID to dispatch events to server-side Google Tag Manager.

I would have loved if setting up the rerouting was as simple as adding a configuration to the app codebase! This would have been similar to using server_container_url with a Google Tag.

A link with Google Analytics 4 is thus required, and you need to keep that link alive even if you don’t ever dispatch any hits from server-side Google Tag Manager to GA4.

That gripe aside, and ignoring the general aches and pains of debugging mobile apps, the dispatch mechanism does work like a charm.

Please let me know in the comments if you have any questions or additional input about collecting Google Analytics 4 app hits in server-side Google Tag Manager via the Firebase Analytics SDK (phew – that was a mouthful!).