Snowplow Tag for Google Tag Manager Server-side

Snowplow is a scalable open-source platform for rich, high quality, low-latency data collection. It is designed to collect high quality, complete behavioral data for enterprise business.

To find out more, please check out the Snowplow website and our documentation.

Overview

The Snowplow Tag for Google Tag Manager Server-side is a server-side tag for forwarding events to a Snowplow collector, from the Snowplow Google Tag Manager Server-side Client or other clients which populate the common event model.

Events

When the Snowplow Tag is triggered, it receives the client event.

If the event is a Snowplow event collected and forwarded by the Snowplow GTM Server-side client, it forwards it to the Snowplow collector. For other client events, the Snowplow Tag will transform them to Snowplow events before sending them to the Snowplow collector.

By default, the Snowplow tag will tranform the following client events into self-describing Snowplow events:

The Google Tag Manager Server-side events.
The GA4 enhanced-measurement events.
The GA4 automatically collected events for the web.

In addition, users can change the default or add custom event definitions according to their use case.

Installation

The server Docker image must be 2.0.0 or later.

Installing from the Google Tag Manager Template Gallery

From the Templates tab in GTM Server Side, click "Search Gallery" in the Tag Templates section
Search for "Snowplow" and select the official "By Snowplow" tag
Click Add to Workspace
Accept the permissions dialog by clicking "Add"

Manual Installation

To manually install this Tag:

Download template.tpl
Create a new Tag Template in the Templates section of a Google Tag Manager Server container
Click the More Actions menu in the Template editor and select Import
Import template.tpl downloaded in Step 1
Click Save.

Then, create a new Tag using the template just created.

Configuration

In order to use the Snowplow Tag, you need to specify your Snowplow collector URL in the Tag Configuration.

Other available settings are:

1. Cookie Settings

Through the Cookie Settings you can configure the cookie name returned by your Snowplow collector or further override the collector cookie with your own settings. More specifically, besides the cookie name, the cookie attributes you can configure are:

Domain
Path
SameSite
Expiration
HttpOnly
Secure

2. Advanced Event Settings

Through the Advanced Event Settings, you can control and customize the Snowplow Tag's behaviour concerning client events' tranformations. More specifically, you can:

Add your custom event definitions for selected events to be sent as self-describing Snowplow events.

After you enable this option, you can specify the event name, the event schema, and the event data mappings, that the Snowplow Tag will use to transform a client event into a Snowplow one. Self-describing events are a data structure based on JSON Schemas and can have arbitrarily many fields. To define your own custom event, you must first create a JSON schema for that event and upload it to an Iglu Schema Repository, since Snowplow uses the schema to validate the event. Then:
1. use the Event Name to Schema table to map that schema for a given client event name.
2. use the Event Definitions table to define how each Snowplow data property maps to the client event.
Send selected events as structured Snowplow events.

After you enable this option, just add the event names you want to be tranformed into structured Snowplow events. This option is better suited towards events that follow the category-action-label-value taxonomy. The Snowplow Tag will specifically look for the corresponding event_category(required), event_action, event_label and event_value properties in the server-side event object.
Set whether Base64 will be used to encode self-describing data

3. Logs Settings

Through the Logs Settings you can control the logging behaviour of the Snowplow Tag. The available options are:

Do not log: This option allows you to completely disable logging. No logs will be generated by the Tag.
Log to console during debug and preview: This option enables logging only in debug and preview containers. This is the default option.
Always: This option enables logging regardless of container mode.

Note: Please take into consideration that the logs generated may contain event data.

The logs generated by the Snowplow GTM-SS Tag are standardized JSON strings. The standard log properties are:

{
    "Name": "Snowplow"  // the name of the tag
    "Type": "Message"   // the type of log (one of "Message", "Request", "Response")
    "TraceId": "xxx"    // the "trace-id" header if exists
    "EventName" "xxx"   // the name of the event the tag fired at
}

Depending on the type of log, additional properties are logged:

Type of log	Additional information
Message	"Message"
Request	"RequestMethod", "RequestUrl", "RequestHeaders", "RequestBody"
Response	"ResponseStatusCode", "ResponseHeaders", "ResponseBody"

Find out more

Technical Docs	Setup Guide

Technical Docs	Setup Guide

Contributing

Feedback and contributions are welcome - if you have identified a bug, please log an issue on this repo. For all other feedback, discussion or questions please open a thread on our discourse forum.

Contributing

Contributing

Copyright and license

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this software except in compliance with the License.

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

snowplow / snowplow-gtm-server-side-tag