Snowplow Template

This template implements the Snowplow JavaScript tracker for Google Tag Manager. It allows for the sending of Snowplow events from your website to your Snowplow collector.

Tag Types are the kinds of events that can be tracked with the Snowplow v4 Tag Template. Each tag type has its own set of options and parameters that can be configured.

You can also configure plugins to use with this template.

Ad Tracking

The Ad Tracking tag is used to track impressions and ad clicks. This can used by, for example, ad networks to identify which sites and web pages users visit across a network, so that they can be segmented.

Ad Tracking Parameters

All ad tracking events take the following common parameters:

Name	Required?	Description	Example
advertiserId	No	The advertiser ID	201
campaignId	No	The campaign ID	12
cost	No	The cost of the ad	5.5
costModel	No	The cost model for the campaign. Must be one of cpc, cpm, or cpa	cpc

The ad tracking tag includes three event types, each with its own set of additional parameters:

Impression Event

Name	Required?	Description	Example
impressionId	No	Identifier for the particular impression instance	67965967893
targetUrl	No	The destination URL	https://www.example.com
bannerId	No	Adserver identifier for the ad banner (creative) being displayed	23
zoneId	No	Adserver identifier for the zone where the ad banner is located	7

Click Event

Name	Required?	Description	Example
targetUrl	Yes	The destination URL	https://www.example.com
clickId	No	Identifier for the particular click instance	12243253
bannerId	No	Adserver identifier for the ad banner (creative) being displayed	23
zoneId	No	Adserver identifier for the zone where the ad banner is located	7

Conversion Event

Name	Required?	Description	Example
conversionId	No	Identifier for the particular conversion instance	743560297
category	No	Conversion category	ecommerce
action	No	The type of user interaction	purchase
property	No	Describes the object of the conversion	shoes
initialValue	No	How much the conversion is initially worth	99

Button Click Tracking

This tag will enable the tracking of clicks on buttons, covering both <button> and <input type="button"> elements.

info

This does not track track a button click event directly, but rather will enable listen for button clicks.

Filter

The Filter option allows you to specify a list of CSS classes that will be used to filter out elements that should not be tracked. This can be useful if you have a large number of buttons on your site, but only want to track clicks on a subset of them.

There are two types of filters you can use:

• Allow: Only elements that match the specified CSS classes will be tracked.
• Block: Elements that match the specified CSS classes will not be tracked.

Each filter takes a comma-separated list of CSS classes. For example, to only track clicks on buttons with the classes "track-me" and "click-me" you would add enter track-me, click-me into Classes when the Allow filter type is selected.

Cart Tracking

The Cart Tracking tag is used to track interactions with a shopping cart. This can be used to track the addition and removal of items to a cart.

Cart Tracking Parameters

Add To Cart and Remove From Cart events take the following parameters:

Name	Required?	Description	Example
sku	Yes	The stock keeping unit (SKU) of the product being added/removed	000345
unitPrice	Yes	The price of the product being added/removed	12.99
quantity	Yes	The quantity of the product being added/removed	2
name	No	The name of the product being added/removed	'blue tie'
category	No	The category of the product being added/removed	'clothing'
currency	No	The currency of the product being added/removed	'USD'

info

We recommend migrating to the Snowplow Ecommerce Tag template to take advantage of the latest ecommerce tracking features.

Site Search

The Site Search tag can be used to track searches on your website, using the Site Search Schema

Site Search Parameters

Name	Required?	Description	Example
terms	Yes	Search terms	['unified, log']
filters	No	Search filters	{'category': 'clothing'}
totalResults	No	Results found	10
pageResults	No	Results displayed on first page	5

Timing

This is used to track user timing events, such as how long resources take to load.

Timing Parameters

Name	Required?	Description	Example
category	Yes	Timing category	'load'
variable	Yes	Timed variable	'map_loaded'
timing	Yes	Number of milliseconds elapsed	50
label	No	Label for the event	'Map loading time'

Enhanced Consent

The Enhanced Consent tag is used to track user consent preferences. This can be used to track whether a user has given consent to certain tracking activities, such as tracking cookies or personalized ads.

Enhanced Consent Events

Name	Description
Allow All	Track an acceptance of user consent.
Allow Selected	Track a specific selection of consented scopes.
Pending	Track the unconfirmed selection about user consent.
Implicit	Track the implicit consent on user consent preferences.
Deny	Track a denial of user consent.
Expired	Track the expiration of a consent selection.
Withdrawn	Track the withdrawal of user consent.

Enhanced Consent Parameters

Attribute	Description	Example
basisForProcessing	GDPR lawful basis for data collection & processing.	Consent
consentUrl	URI of the privacy policy related document.	https://example.com
consentVersion	Version of the privacy policy related document.	1.0
consentScopes	The scopes allowed after the user finalized their selection of consent preferences.	'analytics, functional'
domainsApplied	The domains for which this consent allows these preferences to persist to.	https://example.com
gdprApplies	Determine if GDPR applies based on the user's geo-location.	-

Enhanced Ecommerce

For Google Analytics 4 compatible ecommerce tracking, see the dedicated Snowplow v3 Ecommerce Tag template instead.

info

The following Enhanced Ecommerce plugin has been deprecated in favor of the Snowplow Ecommerce Tag template, it is recommended to use the new template for the latest ecommerce tracking features. This tag remains for compatibility with existing setups.

The Enhanced Ecommerce tag is used to track ecommerce events, such as product views, add to cart, and purchases.

When you select Enhanced Ecommerce, you are left with two options: Use Data Layer or Choose Variable. The way it works is very similar to Enhanced Ecommerce in Google Analytics.

If you choose the first, the template will look into the dataLayer structure for the most recently pushed Enhanced Ecommerce object, and map this object to the request to Snowplow Analytics.

If you selected Choose Variable, you need to provide a GTM variable that returns an object in the correct, expected format.

Error Tracking

The Errors tracker tag provides a way to manually track any errors that occur on your website.

Error Tracking Parameters

Name	Required?	Description	Example
message	Yes	Error message	'Cannot get user object'
filename	No	Filename or URL	'shop.js'
lineno	No	Line number of problem code chunk	23
colno	No	Column number of problem code chunk	45
error	No	JS ErrorEvent	{Stack trace string}

Page View

You can provide a Custom Page Title if you wish, and you can add a custom context to the request, as also described here.

If you enable Page Activity Tracking, page pings will be sent at intervals that you can specify.

The Callback Function is something you can set to a JavaScript function. If you set the callback, then instead of sending the page ping to Snowplow, the function gets invoked instead. See the JavaScript tracker documentation for more information.

Link Click Tracking

The Track Link Click event is similar to regular parameter-based events, as it lets you add parameters and track a link click as a manually encoded hit.

The Enable Automatic Link Click Tracking adds listeners to the page, which will track clicks on links permitting they adhere to the allow/denylisted class names you can optionally provide. It is intended to trigger early on a page to begin listening for click events, not to trigger on click events like Click Triggers.

The Fix Middle-click Tracking adds a fix for some browsers where middle-clicks were not tracked properly.

If you check Track HTML Content Of Clicked Link, then the full text content of the link element will be sent to Snowplow as well.

note

This setting enables the tracker's native Link Click Tracking plugin, it does not directly fire an event.

Form Tracking

Form tracking has just two options, because filters and transformations won’t work with the custom template (due to lack of support for processing HTML elements). The options are to set form and/or field denylists and allowlists.

Denylists and allowlists for forms are a list of comma-separated HTML class names. If denylisted, then any form element with a listed class will not trigger the form event. If allowlisted, then only form elements with a listed classname will be tracked.

For fields, denylists and allowlists work similarly, except they use the name attribute rather than the class.

Note that this tag enables the tracker's native Form Tracking plugin, it does not directly fire an event. It is intended to trigger early on a page to begin listening for form events, not to trigger on form events like Form Submit Triggers.

Custom commands

For any other commands which are supported by the Snowplow JavaScript Tracker v4, you can select the [Custom Command] option. Once selected, you can enter any function name and the associated parameter for that function. The parameter can either be a simple string, in examples such as setUserId:

Or it can be set to a Custom JavaScript Variable in the instances where an Object should be passed to the function, such as with enableAnonymousTracking:

And then use this variable as your Command Argument:

For a list of available commands, consult the API documentation for the Browser Tracker

Additional Tracking Parameters

Add custom context entities

Using the Context Entities table allows you to attach custom context entities to the Snowplow event. Each row should be set to a variable value that must be an array of custom context objects that will all be concatenated to add to the Event.

For example to manually attach the web page context, create a custom JavaScript variable that returns an array with the custom context object:

function() {
    return [{
        schema: 'iglu:com.example/web_page/jsonschema/1-0-0',
        data: {
            id: '12345',
            title: 'Example Page',
            url: 'https://example.com'
        }
    }];
}

Then set this variable as the value in the Context Entities table.

Set Custom Timestamp

You can also choose to set the True Timestamp with this field. The format must be UNIX time in milliseconds.

Parameter Object

Tags that can derive their parameters from a Google Tag Manager variable are:

• Ad Tracking
• Cart Tracking
• Error Tracking
• Self-describing Event
• Site Search
• Social Interaction
• Structured Event
• Timing

You can set the Retrieve Parameters From Variable setting to a Google Tag Manager variable. This parameter must return an object. In the object, the key-value pairs should reflect the named parameters in the event documentation. For example, to have the variable populate an Error event, you could use a Custom JavaScript variable like this:

function() {
  return {
    message: 'Some Error Happened',
    filename: 'somefile.js',
    lineno: 5,
    colno: 236,
    error: null
  }
}

Alternatively, you can set the drop-down to the value No, and add the parameters manually instead:

Some tag types will add additional selections to this section. Follow the official tracker documentation for more information about what each option does.