GTM Transformations is a new feature and resource type in server-side tagging, which you can access through the new entry in the container resource navigator.
Transformation is middleware b/w the client and tags, allowing you to include and exclude parameters from the event data objects before tags can access it.
You can also use it to augment existing parameters. This is useful if you want to enrich the event data object with an appropriate.
Transformations In A Nutshell
To understand transformations, you first need to understand how clients and tags interact in a server-side tagging container.
A client is a server-side tagging resource that consumes incoming HTTP requests and turns them into an event data object.
This event data object is then consumed by tags in order to perform their tasks, such as dispatching requests to third-party vendors. The event data object semantics are not standardized or enforced, but it is recommended that clients follow the schema outlined by Google.
For example, a client could take a URL parameter &cid=99881.99881 and turn it into an event data object key named client_id with the value 99881.99881. Tags could then be coded or configured to take this client_id key from the event data object and populate their own outgoing requests with the value.
The best way to check what type of event data objects are generated by clients is to use Preview mode. When you select an event in the left-hand navigation, the Event Data tab will show what the client produced.
The main problem with event data is that the client’s operations are fixed. The event data object it produces is the same for all tags that are configured to make use of it. If you want a tag to ignore certain fields in the event data object, or if you want a set of tags to mutate some of the values into another format, the tag template itself needs to support this, and not all tag templates do.
Furthermore, Google’s own clients, which the majority of users will default to as the main controllers of the incoming data streams, are black boxes and there’s not much you can do to control how they work.
For a long, we’ve been waiting for a feature that would allow us to edit the event data object itself before tags get to consume it.
This is where transformations enter the stage.
With transformations, you can now create a rule that removes or modifies the values in the event data object before tags can access it.
Instead of having to make tag-specific exceptions, you can now modify the event data object itself. After doing so, any tag that is set to consume this transformation will be privy only to the modified event data object rather than the original one.
Importantly, transformations don’t permanently edit the event data object. They create a transformed clone of the object to be digested by whatever tags and whatever conditions you specify in the transformation (more about these below). Tags that are not affected by a transformation will have access to the original, unmodified event data object.
Create a new Transformation
To create a new transformation, click the Transformations entry in the left-hand navigation of your server-side tagging container. You’ll see a list of your existing transformations. If you click the button labeled NEW, you can create a new transformation.
Tranformation Types
Transformations come in three types:
- Allow parameters, which lets you allowlist the parameters that should end up in the event data object. This is very powerful, as parameters that are not allowed will be excluded from the event data.
- Exclude parameters, which lets you denylist the parameters that should not end up in the event data object. Parameters that are not excluded will be included in the event data.
- Augment event, which lets you add or modify event data parameters. This is where you would do data enrichment, sensitive data purges, and similar.
Allow Parameters
When you choose Allow parameters as the transformation type, you’ll need to populate a table of rows, with each row corresponding to a parameter name in the event data object.
When this transformation is evaluated, the keys in the event data object are compared against the parameters listed in this transformation. If there’s a match, that key is kept in the event data object.
If there’s no match, then the key is dropped from the event data object for this transformation.
In the example above, the only allowed parameters are client_id, event_name, ga_session_id, and custom_timestamp. Other parameters are not included in this transformation.
This is a very powerful transformation type, as it lets you proactively exclude all parameters that you are not aware of or that you haven’t exclusively allowlisted for the tags that consume this transformation.
It’s also a risky transformation type because of this. Especially when working with third-party vendors, you might not know exactly which parameters the vendor needs due to poor documentation or lazy template design. The Allow parameters transformation is most potent when you’re working with a service for which you know exactly which parameters are required and which are optional.
EXCLUDE PARAMETERS
Like Allow parameters above, parameter exclusion requires you to populate a table of rows, with each row corresponding to a parameter in the event data object.
However, this time when comparing keys in the event data object against this list, any key that matches between the two is dropped from the event data object. Keys that are not matched are kept.
In this case, client_hints and ip_override have been excluded from the final event data object in this transformation. That’s why they have empty values above whereas all the other parameter values are preserved.
While the allowlist is more proactive and pre-emptive as a measure, the Exclude parameters transformation lets you remove parameters that you know to be problematic.
AUGMENT EVENT
Event augmentation is what you’d use for data enrichment and for cleaning up the contents of the event data object. Instead of removing or keeping parameters, the augment event transformation type lets you add new keys to the event data object and/or modify existing values.
When you add parameter names and values into this transformation, any parameters that share the same name in the event data object get overwritten by the transformation’s value for the given parameter. If there is no pre-existing parameter with that name, a new one is added to the event data object.
In the example above, with the exception of
currency, all the ecommerce parameters are retrived from firestoreThe cool thing is that the values you set support the full range of server-side Google Tag Manager’s variable capabilities, including things like asynchronous API calls and Firestore lookups.
While event augmentation is very useful for removing sensitive information from the page_location field, for example, its biggest potential lies in enriching the information in the event data object so that a multitude of tags can make use of the modification.
TRANSFORMATION PRIORITY
It’s possible for multiple transformations to apply to a given event data key. For example, you might have a transformation in place that augments an event data key and also another transformation in place that excludes this key under certain conditions.
In this case it might be sensible to set the exclusion at a higher priority, so that the key isn’t unnecessarily augmented in cases where it’s already been excluded.
You can find the priority setting under the Advanced Settings of any transformation.
If you don’t specify a priority, then transformations are evaluated in this default priority order:
Allow parameters > Augment event > Exclude parameters
MATCHING CONDITIONS
Matching conditions allow you to enable the given transformation only when certain variable conditions are matched.
For example, given the Ecommerce augmentation example from above, it makes sense to only enable this transformation when the event_name value is purchase, as that’s the only event that would include the transaction ID required for fetching the data from Firestore (read more about this use case below).
If GA4 is your main incoming data stream, you could even add a Client Name condition to the transformation to make sure that other types of incoming streams don’t trigger the Firestore lookups.
Matching conditions in preview mode
If any of these matching conditions does not match, then the transformation is not evaluated and event data is not modified.
AFFECTED TAGS
In addition to restricting transformations to work only under certain conditions, you can also apply them only to specific tags that you allowlist in the Affected tags settings.
In the example above, my Allow parameters transformation allowlists only a very restricted range of event data parameters for my custom analytics collector system.
Other tags can make use of the entire event data object, but this particular Custom Analytics Collector tag is only privy to the limited set allowed in this transformation.
DEBUG TRANSFORMATIONS
In Preview mode, the main way to see transformations at work is to select an event in Preview mode, and then open a tag that should be affected by a transformation.
Here, under Modified event data you’ll see what was available to the tag when it fired. If you check Show Original, you’ll see a diff in what the original event data object looked like.
The transformations that affect this tag are also listed. By clicking them open, you can see what the transformation is supposed to do, and you can also see another diff of the “before” and “after” states of the event data object after the transformation does its job.
If there are multiple transformations affecting the current tag, then the “before” state might be impacted by prior (higher priority) transformations modifying it.
In the image above, this transformation only shows a few keys in the event data object, because there was a higher priority Allow parameters transformation before this one, stripping out all the keys that were not explicitly allowlisted.
SUMMARY
The benefit of transformations for data governance should be obvious:
- Google strongly recommends and incentivizes vendors to utilize the event data object when sourcing values for their tag templates.
- With transformations, you have full control over what the event data object ends up looking like, regardless of what the client originally produces.
- This control can be used for adding, removing, and updating values in the event data object.
Naturally, tags don’t have to use the event data object. As transformations obviously pose a risk to malicious tags that want to collect as much as they can without users having a proper say, these tags could now proceed to scrape the information from the request URL itself or from cookies or other HTTP headers.
Hopefully there will be additional UI signals in server-side Google Tag Manager that help us clearly see what data each tag template is using.
One of the problems with transformations is that you need to know both what the event data object can look like at different times and which parameters each tag makes use of.
A solid way of figuring out what a tag template is actually trying to do is to observe its permissions. Good template design involves adding as few permissions as possible, so if a template clearly lists which event data keys it wants to access, you can build your transformations more efficiently.
Obviously templates can also be built with wildcard permissions access, in which case this sleuth work won’t be as effective. I hope that Google figures out a way to incentivize limited permission sets over broader wildcard selections.
A few features that I’d still like to see in transformations include:
- Ability to select a tag type over individual tags when choosing Affected tags.
- Ability to populate the table of parameters with a single variable, so that you could iterate over all the keys in the event data object, for example, and return an array (for Allow / Exclude) or object (for Augment) of parameter names (and values) to which you want the transformation to apply.
What do you think about transformations? Do you have additional use cases in mind for them?