Client Template for server-side Google Tag Manager

The JSON Client receives JSON Payloads and makes the data available in the Event Data. The built-in ID Service creates long lasting server-side set (HTTP-Only) cookies for visitor identification.

For a detailed guide please check the Blogpost about JSON Tag & JSON Client.

1. Download the template.tpl from this GitHub Repository
2. Go to the Templates Section in your server-side GTM Instance
3. In the Client Templates Section click on "New"
4. Select "Import" in the three dots menu at the top right
5. Select the Downloaded template.tpl file and save the Template
6. Close the Template Editor and go to the Clients Section

Please keep in mind that this Template is not part of the Community Template Gallery, so you will need to get the latest state again if there is a new version of the template.

After you added this Template to your container, you can create a new Client with it. In the Clients Section click on "New". Then you need to choose "JSON Client" as the Client Type.

Configure the JSON Client according to your needs and save it.

Please define the Path under which you want the Endpoint to be available. This path needs to match the path which is configured in the JSON Tag Variable in the client-side GTM (See: https://github.com/floriangoetting/json-tag-variable?tab=readme-ov-file#endpoint-path).

If this option is enabled, a UUID v4 will be generated and will set a server-side Cookie with the configured settings. This can be used to reidentify the device of a visitor.

This field can contain the Path to Event Data which contains a boolean value to define dynamically if the Device ID Cookie should be set or not. For example this could be a consent boolean for a service for which this cookie is relevant. If no Event Data is specified, the Device ID Cookie will be set in any case.

In this field you can specify the name of your server-side Device ID cookie.

You can customize the number of days here how long you want the Device ID Cookie to live. The default value 400 is the maximum number of days for a cookie to live which is supported by Google Chrome.

The Domain on which you want to set your server-side Cookies. Usually this will be .yourdomain.com to include subdomains as well. If you leave the default value "auto" it will be automatically detected as the eTLD+1 of the first header found in the following priority order: 1. 'Forwarded', 2. 'X-Forwarded-Host', 3. 'Host'.

You can specify a path here if you want the cookies only be sent on specific URL Paths. Normally this should be left with the default "/".

With the secure flag enabled you make sure, that the cookies will only be set if the HTTPS protocol is beeing used.

With the HttpOnly Flag enabled, you make sure, that the cookies can not be read by javascript for example using document.cookie. If you need to read the cookie values in the client-side GTM, you can still read them from the Data Layer.

This attribute defines whether the cookies are sent with cross-site requests.

If this option is enabled, a unix timestamp in milliseconds will be generated and will set a server-side Cookie with the configured settings. This can be used to identify the session of a visitor.

This field can contain the Path to Event Data which contains a boolean value to define dynamically if the Session ID Cookie should be set or not. For example this could be a consent boolean for a service for which this cookie is relevant. If no Event Data is specified, the Session ID Cookie will be set in any case.

In this field you can specify the name of your server-side Session ID cookie.

You can customize the number of minutes here how long you want the Session ID Cookie to live. With the default value of 30 minutes, the Session ID Cookie will be deleted and recreated if the visitor comes back to the site after 30 minutes of inactivity. If the visitor continues to browse through the site, the Session Cookie lifetime will be reset to the number of minutes again to retain the session.

The Domain on which you want to set your server-side Cookies. Usually this will be .yourdomain.com to include subdomains as well. If you leave the default value "auto" it will be automatically detected as the eTLD+1 of the first header found in the following priority order: 1. 'Forwarded', 2. 'X-Forwarded-Host', 3. 'Host'.

You can specify a path here if you want the cookies only be sent on specific URL Paths. Normally this should be left with the default "/".

With the secure flag enabled you make sure, that the cookies will only be set if the HTTPS protocol is beeing used.

With the HttpOnly Flag enabled, you make sure, that the cookies can not be read by javascript for example using document.cookie. If you need to read the cookie values in the client-side GTM, you can still read them from the Data Layer.

This attribute defines whether the cookies are sent with cross-site requests.

You can define cookies here that you want to persist as long as possible. The JSON client will then extend their lifetimes server-side. This can be especially beneficial for client-side cookies used for device identification, which would otherwise be unstable due to privacy protections. There's no need to include the device and session ID cookies from the JSON client here, as they are created server-side anyway.

If your Tagging Server is served from a different domain or subdomain, you will need to configure the CORS Headers to make sure that the requests are not blocked. Please note that the CORS Headers will not work until you publish the ssGTM Container the first time with the setting enabled. You will also need to clear the browser cache and cookies after you published the ssGTM Container.

Please enter a valid RegEx here to validate the origin. If the RegEx is not matched, the request will not be claimed. If you do not want to validate the origin, just leave the default value of "*".

When this option is activated, the JSON Client will listen for failed tags and will create a monitor event when at least one of the tags failed. You can send additional data like the request and response from the tags to the JSON Client which will be included in the event. For more details about this please check the section "How to get a more detailed Monitor Event".

When this option is activated, the JSON Client will listen for successful tags and will create a monitor event when at least one of the tags suceeded. You can send additional data like the request and response from the tags to the JSON Client which will be included in the event. For more details about this please check the section "How to get a more detailed Monitor Event".

You can customize the name of the monitor event here. The default event name is "server_monitor".

You can specify here, if the Monitoring Event should be sent as well if no custom Monitor Data had been provided through the send message "server_monitor" API Call from your server tags. For more details about this please check the section "How to get a more detailed Monitor Event".

If you enable the Monitor Event, the first step you should do afterwards is to enable the Additional Tag Metadata in your Server Tags. This will enable you to identify the actual tag which failed or succeeded. To do this, go to each Server Tag Configuration and search for the section "Additional Tag Metadata". Activate the option "Include tag name" and just enter "name" in the "Key for tag name". Now you will see the Name of the tag in the Monitor Event in case it matches the conditions in the monitoring settings.

For a more detailed monitoring, you can also send any information from the Server Tag to JSON Client to be included in the Monitor Event. You can use this for example to send the response from the Server Tag to JSON Client in case of a failure or success and you will have much more actionable insights. If you want to use this feature, you would need to update the Template Code of the Server Tag where you want to send data from. Please note that when updating a Tag Template, you won't receive automatic updates of the Tag Template anymore from the Template Gallery. If you want to proceed with this anyway, you need to follow these steps:

1. Open the Code Editor of the Tag Template which you want to modify.

2. Require the send Message library with this line of code:

   const sendMessage = require('sendMessage');

3. Use the sendMessage Api with the message Type 'server_monitor' and as message set an object with an attribute 'service' with an identifier of the tag and set any additional attributes which you want to measure in the Monitor Event. Example:

   sendMessage('server_monitor', {
      'service': 'amplitude',
      'status': 'failure', // indicates if a 'failure' or 'success' is measured
      'request': postBody,
      'response': JSON.parse(responseBody)
    });

4. Update the Uses messages permission and set it to "Any".

5. If you now produce a tag failure or a tag success where this sendMessage API is used by using some invalid field values, you should see the Monitor Event firing in the ssGTM Preview Mode. An object called "monitor" will contain the information of the tags and your custom data sent via sendMessage. You can track the data with the tag of your choice.

JSON Client is capable to receive message data from Server Tags and sends the data in the response. The JSON Tag is then including this data in the Data Layer Push as well which makes it available to be used in the client-side Google Tag Manager.

If you want to use this feature, you would need to update the Template Code of the Server Tag where you want to send data from. Please note that when updating a Tag Template, you won't receive automatic updates of the Tag Template anymore from the Template Gallery.

If you want to proceed with this anyway, you need to follow these steps:

1. Open the Code Editor of the Tag Template which you want to modify.

2. Require the send Message library with this line of code:

   const sendMessage = require('sendMessage');

3. Use the sendMessage Api with the message Type 'send_response' and as message, set an object with a parent key which should be the Name of the Tag. In this Example, it is an Amplitude Tag so the parent key is set to "amplitude". Example:

    //return response to JSON Client
    sendMessage('send_response', {
      amplitude: {
        api_key: apiKey
      }
    });

4. Update the Uses messages permission and set it to "Any".

5. Save the Template and test if it works as expected.

There is no native SDK or direct support for the mobile client-side GTM for JSON Tags. However, it is possible to generate JSON payloads in a native app and send the data to the JSON Client endpoint in server-side GTM. An Android Sample Tracking App where JSON Payloads are generated and sent to the ssGTM to be received from JSON Client is available on GitHub now! Check the guide and configuration options in the GitHub Repository of the JSON Tag Test App for Android.

It is not an issue that requests from native apps do not contain an Origin header. If the JSON Client does not find an Origin in the request, the validation will automatically pass without any checks.

Since native apps do not support cookies, a custom mechanism must be implemented to persist the device ID and session ID.

On the first tracking call, the JSON Client generates a new device ID and session ID, which are returned in the response. The app must then store this information locally and include both IDs in subsequent requests—either by:

1. adding them to the payload (“client_id” for the device ID and “session_id” for the session ID), or
2. sending them as cookie headers using the cookie names defined by the JSON Client.

If both the payload and cookies contain client_id and session_id, the values in the payload take precedence.

This method is implemented in the Android Test App and can be customized for your app.

The same principle applies to webviews:

1. Inject the device and session cookies into the webview using the configured cookie names.
2. This ensures the JSON Client reuses existing IDs rather than generating new ones.

This logic is also part of the Android Test App and can be adapted to your project setup.

Contributions to any of the Templates are highly welcome! The process to contribute works like this:

1. Fork the repository
2. Pull and merge all updates from the main repository
3. Make your adjustments to the files locally
4. Test the Templates with your changes in GTM and ssGTM
5. If you updated a template.tpl file, please do not replace the full original template.tpl file but only the part from "TEMPLATE_PARAMETERS" to the end of the file.
6. Create small commits with good comments to make it easy to follow your adjustments
7. Push the Commits
8. Create a new pull request for the main repository including an understandable summary of your changes

I will review the pull request and will provide feedback or questions if something is unclear. If everything is fine, your changes will be merged with the main repository and you will be listed in the list of contributors! If you want to contribute but you don't know which adjustments make sense, please check the list of issues (https://github.com/floriangoetting/json-client/issues), where I and others will list feature wishes or bug reportings.

Please note that it is not planned to support GA4 as destination Analytics Tool. If you want to use GA4 or contribute to a project for first party tracking with GA4 support, please check out Stapes Data Client (https://github.com/stape-io/data-client).