Google Tag Manager Server-Side — Parsing Event Data From Any Custom Vendor Request

One of the core components of a Google Tag Manager server-side container is the client. The client claims a request, handles the information associated with it, returns a response, and triggers the succeeding container logic . When the container is called, the client can pass information from the incoming event to the server-side container in the form of an event object. This post and the corresponding GTM server-side client template aim to explain and facilitate this process for any GET or POST request. At the moment, the built-in client templates in GTMSS only support Universal Analytics, GA4, and measurement protocol hits.

The Custom Event Parser (available on GitHub) is a more vendor-agnostic approach and will hopefully be added to the GTM Community Template Gallery soon.

Note that I have written about managing custom vendor tags before. Those were my first steps exploring GTM server-side and especially the code examples for client and tag are quite manual and tailored to a specific request structure. While this helps to understand the logic in general, the code is far from being universally applicable, which is why I decided to build a client template, which is a little more standardized.

How The Template Works

1) The configuration requires a path to tell the client, which requests it should handle. You can also specify a cookie from your request, which will be stored in the event data (more on that below). This is optional.

2) Once configured, the client claims all requests for said path and extracts the tracking information from various sources: Query string, headers, cookies, request body, and IP. Here is the full event data mapping:

Please note that by default, each key-value pair of the JSON request body is stored as a key-value pair in the resulting event object. That means, that you might have to do some additional JSON parsing in the template code, depending on how the request body is structured. You will find an annotation about this in the code as well.

3) The client then sends a response and returns the resulting event data in a structured object to the container. As a next step, you can access and use the data for your server-side tags in two ways:
-) Either by calling it right from a tag template via the tagging API:

const getAllEventData = require('getAllEventData');
const event = getAllEventData();

-) Or by storing it in a variable first:

4) A word about cookies: As mentioned above, the template has an input field that lets you parse existing cookies from your request. These will also be added to the event object. Here you can jump on already existing cookies (such as _fbp, _ga etc.). In the long-run, however, it is worth considering whether to manage all user- and session-cookies independently in your own first party context. This is also possible via GTM server-side logic.

Why This Is Important

The event data object is the central connection between client and tag in a GTM server-side environment. It is the client’s output and the tag’s input. Having all available information in a consistent object structure is an important part of a centrally managed data model in a server-side tag manager.

The Custom Event Parser works with any kind of GET or POST tracking request, which is being routed through your server-side container — analytics.js requests for GA4, smartttag.js requests for AT Internet etc. All you have to do when configuring the client template is to specify the path, to which it should respond — /collect for GA4, /hit.xiti for AT Internet etc. However, the template is not limited to just parsing a specific vendor hit. In theory, you can also put together your own data collection request with custom data, which will also be parsed by the client template:

Closing Thoughts

The custom approach is the most interesting. Along with a universally applicable data collecting method, this would be the first step towards implementing a vendor-agnostic and unified data model in a first party context. Thus, reducing dependence on non-transparent vendor-specific client-side scripts, which end up cluttering many websites.

Of course, one can still benefit from all the great functionality that analytics and MarTech vendors are offering. But it certainly does not hurt to understand and control, which data you are collecting, where it is coming from, and where it is going. Eventually, data processes should be deliberate, transparent, and smart. And a server-side tagging solution like GTM can be one of many great tools to pave the way.

— Get the template on GitHub here. Feedback and suggestions are very welcome. If you have questions, found a bug in the code, or if you’re simply up for talking analytics: Feel free to reach out. —

UPDATE

September 2021: While the original client template was designed to only handle GET requests, I have updated the Github repository as well as the documentation and this article to also handle POST requests. This update mainly includes also parsing the request body into the event object.