In January 2020, when Google Tag Manager\u2019s server-side tagging<\/a> was first introduced to the general public at SuperWeek<\/a>, I wrote a flurry of tweets<\/a>, sharing my vision of a server-side tagging future.<\/p>\n In one of the tweets, I discussed how you could do these:<\/p>\n <\/p>\n <\/a><\/p>\n<\/div>\n Fast forward to today, over three years later, and we are finally<\/em> treated to a feature that grants us scalable controls to properly interrupt data flows within server-side GTM.<\/p>\n I\u2019m talking about TRANSFORMATIONS<\/strong>.<\/p>\n <\/p>\n <\/a><\/p>\n<\/div>\n It\u2019s a new feature and resource<\/strong> type in server-side tagging, which you can access through the new entry in the container resource navigator.<\/p>\n Transformations sit firmly between the client<\/strong> and tags<\/strong>, allowing you to include<\/strong> and exclude<\/strong> parameters from the event data object<\/a> before tags can access it.<\/p>\n You can also use it to augment<\/strong> existing parameters. This is useful if you want to enrich the event data object with an appropriately designed Firestore pipeline<\/a>, or something similar.<\/p>\n Read on for more information about how transformations work and how to use them.<\/p>\n \n \n Subscribe to the Simmer newsletter<\/a> to get the latest news and content from Simo Ahava into your email inbox!\n <\/p>\n <\/span><\/p>\n To understand transformations, you first need to recall how clients<\/strong> and tags<\/strong> interact in a server-side tagging container.<\/p>\n A client<\/strong> is a server-side tagging resource whose purpose is to digest an incoming HTTP request<\/strong> and ideally turn it into an event data object<\/a>.<\/p>\n This event data object is then consumed by tags<\/strong> 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<\/a>.<\/p>\n For example, a client could take a URL parameter like <\/p>\n <\/a><\/p>\n<\/div>\n The best way to check what type of event data objects are generated by clients is to use Preview mode<\/a>. When you select an event<\/em> in the left-hand navigation, the Event Data<\/strong> tab will show what the client produced.<\/p>\n <\/p>\n <\/a><\/p>\n<\/div>\n Why don\u2019t you see events under all the requests? That\u2019s because there either wasn\u2019t a client to claim<\/strong> the request in question, or the client didn\u2019t produce an event object using a specific template API<\/a>.<\/p>\n<\/blockquote>\n The main problem with event data is that the client\u2019s operations are fixed<\/strong>. The event data object it produces is the same for all tags<\/strong> 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<\/em>.<\/p>\n Furthermore, Google\u2019s own clients, which the majority of users will default to as the main controllers of the incoming data streams, are black boxes and there\u2019s not much you can do to control how they work.<\/p>\n <\/p>\n <\/a><\/p>\n<\/div>\n For long, we\u2019ve been waiting for a feature that would allow us to edit the event data object itself before tags get to consume it.<\/p>\n This is where transformations<\/strong> enter the stage.<\/p>\n With transformations<\/strong>, you can now create a rule that removes or modifies the values in the event data object before tags can access it.<\/p>\n Instead of having to make tag-specific exceptions, you can now modify the event data object itself<\/strong>. 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.<\/p>\n <\/p>\n <\/a><\/p>\n<\/div>\n Importantly, transformations don\u2019t permanently edit<\/strong> the event data object. They create a transformed clone<\/em> 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.<\/p>\n<\/blockquote>\n To create a new transformation, click the Transformations<\/strong> entry in the left-hand navigation of your server-side tagging container. You\u2019ll see a list of your existing transformations. If you click the button labeled NEW<\/strong>, you can create a new transformation.<\/p>\n <\/p>\n <\/a><\/p>\n<\/div>\n When you create a transformation, you\u2019ll first need to choose its type.<\/p>\n Transformations come in three types<\/strong>:<\/p>\n <\/p>\n <\/a><\/p>\n<\/div>\n When you choose Allow parameters<\/strong> as the transformation type, you\u2019ll need to populate a table of rows, with each row corresponding to a parameter name in the event data object.<\/p>\n <\/p>\n <\/a><\/p>\n<\/div>\n When this transformation is evaluated, the keys in the event data object are compared against the parameters listed in this transformation. If there\u2019s a match, that key is kept in the event data object.<\/p>\n If there\u2019s no match, then the key is dropped from the event data object for this transformation.<\/p>\n <\/p>\n <\/a><\/p>\n<\/div>\n In the example above, the only allowed parameters are 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\u2019t exclusively allowlisted for the tags that consume this transformation.<\/p>\n It\u2019s 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<\/strong> transformation is most potent when you\u2019re working with a service for which you know exactly which parameters are required and which are optional.<\/p>\n<\/blockquote>\n Like Allow parameters<\/em> above, parameter exclusion requires you to populate a table of rows, with each row corresponding to a parameter in the event data object.<\/p>\n <\/p>\n <\/a><\/p>\n<\/div>\n However, this time when comparing keys in the event data object against this list, any key that matches between the two is dropped<\/strong> from the event data object. Keys that are not<\/em> matched are kept.<\/p>\n <\/p>\n <\/a><\/p>\n<\/div>\n In this case, While the allowlist is more proactive<\/strong> and pre-emptive as a measure, the Exclude parameters<\/strong> transformation lets you remove parameters that you know<\/em> to be problematic.<\/p>\n Event augmentation is what you\u2019d use for data enrichment and for cleaning up the contents of the event data object. Instead of removing or keeping parameters, the augment event<\/strong> transformation type lets you add<\/strong> new keys to the event data object and\/or<\/em> modify<\/strong> existing values.<\/p>\n <\/p>\n <\/a><\/p>\n<\/div>\n 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\u2019s 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.<\/p>\n <\/p>\n <\/a><\/p>\n<\/div>\n In the example above, with the exception of The cool thing is that the values<\/strong> you set support the full range of server-side Google Tag Manager\u2019s variable capabilities, including things like asynchronous API calls<\/strong> and Firestore lookups<\/strong>.<\/p>\n While event augmentation is very useful for removing sensitive information<\/strong> from the It\u2019s possible for multiple transformations to apply to a given event data key. For example, you might have a transformation in place that augments<\/strong> an event data key and also another transformation in place that excludes<\/strong> this key under certain conditions.<\/p>\n In this case it might be sensible to set the exclusion at a higher priority, so that the key isn\u2019t unnecessarily augmented in cases where it\u2019s already been excluded.<\/p>\n <\/p>\n <\/a><\/p>\n<\/div>\n You can find the priority setting under the Advanced Settings<\/strong> of any transformation.<\/p>\n If you don\u2019t specify a priority, then transformations are evaluated in this default priority order:<\/p>\n Allow parameters<\/strong> > Augment event<\/strong> > Exclude parameters<\/strong><\/p>\n Matching conditions<\/strong> allow you to enable the given transformation only when certain variable conditions are matched.<\/p>\n For example, given the Ecommerce augmentation example from above, it makes sense to only enable this transformation when the <\/p>\n <\/a><\/p>\n<\/div>\n If GA4 is your main incoming data stream, you could even add a Client Name<\/strong> condition to the transformation to make sure that other types of incoming streams don\u2019t trigger the Firestore lookups.<\/p>\n <\/p>\n <\/a><\/p>\n Matching conditions in preview mode<\/span><\/p>\n<\/div>\n If any of these matching conditions does not<\/em> match, then the transformation is not evaluated and event data is not modified.<\/p>\n 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<\/strong> settings.<\/p>\n <\/p>\n <\/a><\/p>\n<\/div>\n In the example above, my Allow parameters<\/strong> transformation allowlists only a very restricted range of event data parameters for my custom analytics collector system.<\/p>\n 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 allowlisted in this transformation.<\/p>\n In Preview mode, the main way to see transformations at work is to select an event<\/strong> in Preview mode, and then open a tag<\/strong> that should be affected by a transformation.<\/p>\n <\/p>\n <\/a><\/p>\n<\/div>\n Here, under Modified event data<\/strong> you\u2019ll see what was available to the tag when it fired. If you check Show Original<\/strong>, you\u2019ll see a diff<\/em> of what the original event data object looked like.<\/p>\n <\/p>\n <\/a><\/p>\n<\/div>\n 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 \u201cbefore\u201d and \u201cafter\u201d states of the event data object after the transformation does its job.<\/p>\n If there are multiple transformations affecting the current tag, then the \u201cbefore\u201d state might be impacted by prior (higher priority) transformations modifying it.<\/p>\n <\/p>\n <\/a><\/p>\n<\/div>\n In the image above, this transformation only shows a few keys in the event data object, because there was a higher priority Allow parameters<\/strong> transformation before this one, stripping out all the keys that were not explicitly allowlisted.<\/p>\n Here are some use cases for transformations.<\/p>\n #1 Flag custom events as conversions for GA4<\/a> Naturally, all of these use cases have been doable before with server-side Google Tag Manager in one way or another. However, not all tags allow you to modify the information consumed from the event data object.<\/p>\n Furthermore, the problem with modifying individual tags is that you might slip and miss a tag, which then becomes a liability in your tracking schema. By nipping the problem in the bud using a transformation, the event data object itself is modified making it impossible for a tag to access something that doesn\u2019t exist anymore.<\/p>\n One of the \u201cquirks\u201d of Google Analytics 4 is that it determines conversions<\/strong> in two places: in the Google Analytics 4 Admin interface<\/a> and<\/em> in the client-side implementation, where conversion events are flagged with a specific URL parameter ( This second context can result in a bit of a headache if you\u2019re using a server-side container to duplicate events across different Measurement IDs.<\/p>\n For example, let\u2019s say you have a Google Analytics 4 event stream collecting to Measurement ID However, in server-side GTM you forward this event to Augment event<\/strong> transformation to the rescue!<\/p>\n\n
![\"Tweet](\"https:\/\/www.simoahava.com\/images\/2023\/04\/simo-twitter.jpg#ZgotmplZ\")
<\/p>\n![\"Transformations\"\/](\"https:\/\/www.simoahava.com\/images\/2023\/04\/transformations.jpg#ZgotmplZ\")
<\/p>\n
\n X<\/span><\/p>\n
\n The Simmer Newsletter<\/strong>\n <\/p>\nTransformations in a nutshell<\/h2>\n
&cid=12345.12345<\/code> and turn it into an event data object key named client_id<\/code> with the value 12345.12345<\/code>. Tags could then be coded or configured to take this client_id<\/code> key from the event data object and populate their own outgoing requests with the value.<\/p>\n![\"Server-side](\"https:\/\/www.simoahava.com\/images\/2023\/05\/sgtm-client.jpg#ZgotmplZ\")
<\/p>\n![\"SGTM](\"https:\/\/www.simoahava.com\/images\/2023\/05\/sgtm-preview.jpg#ZgotmplZ\")
<\/p>\n\n
![\"GA4](\"https:\/\/www.simoahava.com\/images\/2023\/04\/ga4-client.jpg#ZgotmplZ\")
<\/p>\n![\"Transformationt](\"https:\/\/www.simoahava.com\/images\/2023\/04\/transformation-type.jpg#ZgotmplZ\")
<\/p>\n\n
Create a new transformation<\/h2>\n
![\"New](\"https:\/\/www.simoahava.com\/images\/2023\/05\/new-transformation.jpg#ZgotmplZ\")
<\/p>\nTransformation types<\/h2>\n
\n
![\"Transformation](\"https:\/\/www.simoahava.com\/images\/2023\/05\/transformation-type.jpg#ZgotmplZ\")
<\/p>\nAllow parameters<\/h3>\n
![\"Allow](\"https:\/\/www.simoahava.com\/images\/2023\/05\/allow-parameters.jpg#ZgotmplZ\")
<\/p>\n![\"Allowed](\"https:\/\/www.simoahava.com\/images\/2023\/05\/allowed-parameters.jpg#ZgotmplZ\")
<\/p>\nclient_id<\/code>, event_name<\/code>, ga_session_id<\/code>, and custom_timestamp<\/code>. Other parameters are not included in this transformation.<\/p>\n\n
Exclude parameters<\/h3>\n
![\"Exclude](\"https:\/\/www.simoahava.com\/images\/2023\/05\/exclude-parameters.jpg#ZgotmplZ\")
<\/p>\n![\"Excluded](\"https:\/\/www.simoahava.com\/images\/2023\/05\/excluded-parameters.jpg#ZgotmplZ\")
<\/p>\nclient_hints<\/code> and ip_override<\/code> have been excluded from the final event data object in this transformation. That\u2019s why they have empty values above whereas all the other parameter values are preserved.<\/p>\nAugment event<\/h3>\n
![\"Augment](\"https:\/\/www.simoahava.com\/images\/2023\/05\/augment-event.jpg#ZgotmplZ\")
<\/p>\n![\"Parameters](\"https:\/\/www.simoahava.com\/images\/2023\/05\/parameters-from-firestore.jpg#ZgotmplZ\")
<\/p>\n\n
currency<\/code>, all the ecommerce parameters are retrieved from Firestore<\/a>.<\/p>\n<\/blockquote>\npage_location<\/code> field, for example, its biggest potential lies in enriching<\/strong> the information in the event data object so that a multitude of tags can make use of the modification.<\/p>\nTransformation priority<\/h2>\n
![\"Transformation](\"https:\/\/www.simoahava.com\/images\/2023\/05\/transformation-priority.jpg#ZgotmplZ\")
<\/p>\nMatching conditions<\/h2>\n
event_name<\/code> value is purchase<\/code>, as that\u2019s the only event that would include the transaction ID required for fetching the data from Firestore (read more about this use case below).<\/p>\n![\"Matching](\"https:\/\/www.simoahava.com\/images\/2023\/05\/matching-conditions.jpg#ZgotmplZ\")
<\/p>\n![\"Matching](\"https:\/\/www.simoahava.com\/images\/2023\/05\/matching-in-preview.jpg#ZgotmplZ\")
<\/p>\n![\"Affected](\"https:\/\/www.simoahava.com\/images\/2023\/05\/affected-tags.jpg#ZgotmplZ\")
<\/p>\nDebug transformations<\/h2>\n
![\"Preview](\"https:\/\/www.simoahava.com\/images\/2023\/05\/preview-mode.jpg#ZgotmplZ\")
<\/p>\n![\"Show](\"https:\/\/www.simoahava.com\/images\/2023\/05\/show-original.jpg#ZgotmplZ\")
<\/p>\n![\"Transformation](\"https:\/\/www.simoahava.com\/images\/2023\/05\/transformation-details.jpg#ZgotmplZ\")
<\/p>\nUse cases<\/h2>\n
#2 Enrich ecommerce data<\/a>
#3 Hash sensitive URLs<\/a>
#4 Populate identifiers from Firestore storage<\/a>
#5 Clear unwanted parameters from GA4\u2019s event data object<\/a>
#6 Force GA4 hits to show up in DebugView<\/a>
#7 Augment event with first-party user data<\/a><\/p>\nUse case #1: Flag custom events as conversions for GA4<\/h3>\n
_c=1<\/code>) that tells GA4 the incoming event is, indeed, a conversion.<\/p>\nG-1234567<\/code>. In this stream, the event click_to_call<\/code> has not<\/strong> been flagged as a conversion, so the event requests do not have the _c=1<\/code> parameter.<\/p>\nG-2345678<\/code> where click_to_call<\/code> has<\/em> been flagged as a conversion. But because the original request didn\u2019t have the _c=1<\/code> parameter, this conversion is not registered correctly.<\/p>\n
![\"Augment](\"https:\/\/www.simoahava.com\/images\/2023\/05\/augment-conversion.jpg#ZgotmplZ\")
<\/p>\n![\"Lookup](\"https:\/\/www.simoahava.com\/images\/2023\/05\/lookup-events.jpg#ZgotmplZ\")
<\/p>\n