Getting Started with Google Tag Manager Function Call Variables in App Analytics

There’s a lot of excitement these days about Google Analytics 4 and the new integrated app and web analysis capabilities that it will provide, but while the world dual-tags and waits for “GA4” to reach its full potential, using Firebase and Google Tag Manager (GTM) v5 to send app analytics data to traditional GA “Universal Analytics” properties will remain best practice for many enterprises, at least for the next year or two. And as long as app GTM will remain a key app analytics component for a while, we might as well use it to its full potential!

One of the most underappreciated (and poorly documented) aspects of Tag Manager for native apps is also one of its most powerful features: Function call variables. In a normal Firebase Analytics implementation, Tag Manager effectively uses two sources of data when building hits for traditional GA: event parameters and user properties. But with a very small amount of effort, a third source of data can be created via Tag Manager’s function call variables. These are especially useful when you only need to send the data in question to Universal Analytics rather than to Firebase/GA4.

What is a function call variable?

In Google Tag Manager (v5) for apps, a “function call variable” is a variable that calls out to code in the app and requests that the app provide a value. The value is then returned to GTM in a variable that works just like any other GTM variable. For example, suppose you want to collect a human-readable timestamp as a custom dimension on each GA hit, but you don’t really need the timestamp value in Firebase/GA4, or don’t want to use one of the limited Firebase event parameters. Instead of passing the value as an event parameter, you can set up a GTM function call variable that calls out to the app, asks for the current timestamp value and uses that in a custom dimension sent to Universal Analytics.

Code in the app

To enable function call variables in GTM, you need to add a piece of code to your app that responds to Tag Manager’s requests, performs the necessary calculations and returns a value. Technically, this piece of code needs to implement Tag Manager’s CustomVariableProvider interface (Android) or TagCustomFunction protocol (iOS). This GitHub repository contains sample code for an “AnalyticsVariableProvider” class that implements this interface/protocol and returns a handful of illustrative values like environment, timestamp, timezone offset, logged-in status, etc. Versions are provided for Android (Java, Kotlin) and iOS (Swift, Objective-C). Note that this code is only one example of how the function call mechanism can be implemented. That said, it will give you a good foundation for adding additional custom values based on what you want to collect for your apps.

GTM configuration

In order for Tag Manager to be able to call out to the app and execute the code in the AnalyticsVariableProvider class, you need to tell GTM where the code is located in the app via the “Class Path” field (in Android variables) and the “Class Name” field (in iOS variables).

On Android: the entered value needs to be the fully-qualified class name of the AnalyticsVariableProvider class; typically the class name prefixed with the app’s package name (e.g., com.mydomain.myapp.AnalyticsVariableProvider).

On iOS: if the app is built with Swift, the class name for GTM’s purposes would be the name of the class prefixed with the module name (e.g., MyModule.AnalyticsVariableProvider). If using Objective-C, it would simply be the name of the class (e.g., AVPAnalyticsVariableProvider).

Because you will need to provide this class name/path value for each function call variable, it is best to define a GTM constant (e.g. AnalyticsVariableProviderClass), and use that as shown in the examples above. Note that the value of this constant will differ between Android and iOS, so for cross-platform configuration consistency, you may want to create a lookup table variable based on the built-in GTM variable to return the proper value.

Key-value pairs

Each function call variable can pass a custom set of parameters (key-value pairs) from GTM to the AnalyticsVariableProvider code, and the code can then use those parameters to determine what value to return. In the sample code provided, we’ve created logic that depends on the parameter keys “action”, “variable_name”, and “default_value”. (And since it’s usually best practice to not send empty custom dimensions to Universal Analytics, we’re also defined a “default_none” key that tells the code to return null/nil if no value is available.)

To configure a function call variable for “timestamp” in GTM, we pass the appropriate values for these parameters: the “action” we want the code to perform is “fetch_variable” (i.e., we want the code to return a specific value); the name of the variable (“variable_name”) we want the code to return is “timestamp”; and if for some reason a value cannot be determined, we pass “default_none” to have the code return null/nil (so the custom dimension will be dropped from the GA hit). Alternatively, we could pass the key “default_value” along with whatever value we wanted the code to return by default.

Keep in mind that all of these keys (and values) are completely customizable. In the sample code provided, we’ve defined two “actions” for use cases we commonly need to address, but your “actions” could be something else entirely. Or you might not even need to use an “action” parameter: In the simplest implementation, you might not pass any values to the code. But the point is that you have the flexibility to supply a map (dictionary) of dynamic values from GTM to the app (sourced from other GTM variables) and your code can then use those values as needed, ultimately returning some desired value to GTM.

You can also use function call variables to perform custom functions beyond just returning a value: For example, you could use the function call structure to trigger functions in the app that send data to another server, update the state of the app based on values known to GTM, etc.

Recap

Regardless of how you decide to utilize the function call mechanism, all implementations require the following:

• Code in the app that implements the CustomVariableProvider interface (Android) or the TagCustomFunction protocol (iOS) and returns the desired value to GTM.
• A GTM function call variable that: 1) Specifies the “Class Name” (aka “Class Path” for Android) which points to the code in the app, so GTM can find it and 2) Provides an optional set of key-value pairs for use by the code during processing.

Questions about your App Analytics setup or Google Tag Manager? We can help! Please contact us for answers to your questions.