Google Tag Manager Integration guide

As the Splio CDP Web tracking solution supports the Snowplow event format, you can integrate the available Google Tag Manager opensource templates for Snowplow, and prepare with it the tags for the supported event types.

📘

Reminder : the supported event types at this point are :

  • Page View (with an optional authenticated contact identifier)
  • Product View (Which is a page view with an optional product identifier)
  • Add To Cart (with an optional authenticated contact identifier)

This chapter will guide you from the configuration of the Splio CDP Web Tracking endpoint to the creation of new tags for each of the supported event types.

Configure the settings variable

📘

The default settings for all Snowplow tags will use one unique variable created from a template

⚠️

If you manage multiple sites with the same Google Tag Manager container, create one distinct variable for each of them, as the property Tracker Options > Collector endpoint will be different

  1. In Google Tag Manager
    • Go to “Variables
    • Then select “New” on “User-Defined Variables” section

  1. From the "gallery", select the “Snowplow v3 Settings” template
    • You may have to click on “Discover more variable types in the Community Template Gallery

📘

Select the Snowplow V3 version instead the Snowplow e-commerce plug-in.

  1. Input the name Default SP Settingsfor the variable

  2. Configure the variable content :

    • These properties must be setup as this :

      SectionPropertyValue
      Tracker OptionsTracker NameAny unique name you prefer for this tracker. Note that if you have already configured a Snowplow Tracker you will have to setup here a different name.
      Example :

      ecommerceMarketingTracker
      Tracker OptionsCollector Endpoint HostnameSplio CDP endpoint url, compatible with various web tracker event protocols, including Snowplow.
      It is provided by your project manager during integration
      Example : https://web-collector.splio.com/collector/v1/e911bba6-aedf-41ff-a744-cbd706fdc666
      Tracker Options, sub section Javascript TrackerSnowplow JavaScript Tracker LibraryYou can keep default jsDelivr which is a free CDN dedicated to open source projects, where Snowplow Opensource tracker is available
      Tracker Options, sub section Javascript TrackerLibrary versionSetup the last version as specified by your project manager.
      Last valid version is 3.17.0. See release list for available versions
      Application SettingsApplication IDYour unique identifier, specified with the project manager that should be your tenant name by default.
      Example :

      my_store_fr
    • Other recommendations :

      SectionPropertyValue
      PrivacyRespect "Do Not Track"Always select "True" on Respect "Do Not Track
      Cookie SettingsState Storage StrategyUse a “Cookie and Local Storage” strategy. Note that it will be a first party cookie.
      Cookie SettingsCookie NameAdapt the default cookie Name to your preferences. For example sp_marketing
      Cookie SettingsOn all other propertiesKeep default configuration
      All other sectionsOn all other propertiesKeep default configuration
  3. Then, Save the variable.

    • It will be used for tag configuration

Prepare the content variables to use in tags

The tags you will add will require some other variables for content definition. They will be based on Google Tag Manager DataLayer and on Javascript functions.

It will be assumed that you have already configured the necessary DataLayer variables and integrated them in your website code. If it's not the case, go to chapter [Updating the DataLayer if the required properties are not yet available](Updating the DataLayer if the required properties are not yet available)

Gather the variable you will use

In tag configuration, you will use existing variables from the Data Layer.

The required properties for each tag, and the corresponding variables are listed here :

PropertyContentExample of variable name
Product SKU / IDUnique identifier for a product displayed in the current page. Could be any identifier which is known of Splio Predictive CDP product data{{ DL_Product_SKU }}
User IDUnique identifier for an user{{ DL_User_Id }}
User SourceName of application where the user is identified. For example it can be shopify, magento, sap ... It can be an hard coded value for simplicity if you have a single source{{ DL_Source }} or hard coded value
Product In Cart > Product SKU / IDUnique identifier for a product added in cart. Could be any identifier which is known of Splio Predictive CDP product data{{ DL_Cart_Product_SKU }}
Product In Cart > Product NameName for a product added in cart{{ DL_Cart_Product_Name }}
Product In Cart > Unit PriceUnit price for a product added in cart{{ DL_Cart_Unit_Price }}
Product In Cart > QuantityQuantity for an item added in cart{{ DL_Cart_Item_Quantity }}
Product In Cart > CurrencyCurrency for price of a product added in cart{{ DL_Cart_Currency }}

📘

It is recommended to write down first this table and to specify to each property the existing variable name you will use.

🚧

Note that the javascript variable and tag configuration described in next chapters will refer these variables with the example name.

You have to replace the variable name with the one you have already setup on your Tag Manager workspace

Prepare the 2 required javascript variables for context

Two Custom Javascript Variable are also required. They will refer to the Data Layer variables previously identified

  1. Custom Javascript Variable with name SP Context - Identified Product

    function(){
    	return [{
    		'schema': 'jsonschema:com.splio/product/1-0-0',
    		'data': { 
    			'productSKU': {{DL_Product_SKU}} 
    		}
    	}];
    }
    
  2. Custom Javascript Variable with name SP Context - Identified User

    function(){
    	return [{
    		'schema': 'jsonschema:com.splio/logged_user/1-0-0',
    		'data': { 
    			'userId': {{DL_User_Id}}, 
    			'sourceId': {{ DL_Source }} 
    		}
    	}];
    }
    

📘

Once all the variables are ready, you can initialize the tags you want to integrate.

Create the tags

Create a tag for “Page View” event

📘

You only need to setup one variable for both page view and product view events. We detect product view pages based on the product id, if sent as null or empty will be detected as a page view.

  1. Create a new tag, and on type, select “Discover more tag types in the Community Template Gallery”, then template “Snowplow v3” (it will be also available on top of tag type once you have integrated it one first time)

  2. Confirm permissions

  3. For tag configuration, start to go on section “Tracker Initialization

  4. Select for “Snowplow Settings” the settings variable previously created {{Default SP Settings}}

  5. Now select Tag Type “Page View

  6. Open section “Additional Tracking Parameters”, and add these rows :

    • Click “Add Row” and select {{SP Context - Identified Product}}

    • Repeat with {{SP Context - Identified User}}

  7. Complete the tag configuration with the relevant trigger for your ecommerce site

❗️

The trigger should be fired only if a consent initialization trigger has been setup and enabled with end user consent.

Create a tag for “Add To Cart” event

📘

The Splio CDP platform only supports the standard Snowplow “Cart Tracking > Add To Cart event”. If you are already using Google Analytic, the GA “enhanced ecommerce > Add to cart” event is not supported but it is still possible to use the ecommerce variable subset from Google Analytics in the Snowplow tag definition

  1. Create a new tag, and on type, select “Discover more tag types in the Community Template Gallery”, then template “Snowplow v3” (it will be also available on top of tag type once you have integrated it one first time)

  2. Confirm permissions

  3. For tag configuration, start to go on section “Tracker Initialization

  4. Select for “Snowplow Settings” the settings variable previously created {{Default SP Settings}}

  5. Then select “Cart Tracking” as “Tag Type”

  6. Complete configuration as this :

  • On “Parameter Configuration > Retrieve Parameters From Variable” : Choose No

  • Bellow Tracking Type add each of the Product Cart Variables you have identified :

    • sku : use the variable {{ DL_Cart_Product_SKU }} (or the existing one you already have)
    • quantity : use {{ DL_Cart_Item_Quantity }} (or the existing one you already have)
    • name : use {{ DL_Cart_Product_Name }}(or the existing one you already have)
    • UnitPrice : use {{ DL_Cart_Unit_Price }}(or the existing one you already have)
    • Currency : use {{ DL_Cart_Currency }}(or the existing one you already have)

  1. Setup the trigger to a default Add To Cart event model (if one exist)

🚧

If none setup yet, refers to your ecommerce solution recommendations, or add in your ecommerce site source code a Data Layer event property addToCart linked to the cart update, and use a custom trigger to detect it

Make sure that the consent initialization trigger is configured and enabled

📘

Once all the tags are ready, test them with the “Preview” feature, and validate that the expected events are fired as expected.

Updating the DataLayer if the required properties are not yet available

These steps will require some knowledge on content definition with Google Tag Manager. (optional) Data Layer updates will require site development knowledge

Define the data Layer content in your ecommerce site code (only if these properties are not yet specified in your tagging plan)

Regarding the event types you expect to integrate, you may have to specify new variables and add some new Google Tag Manager Data Layer content directly in your ecommerce site code.

📘

Note that if you have already specified these properties on Data Layer with another name, you should ignore this chapter, and use them directly in the new variables used for Snowplow.

Here are listed the required properties to integrate in Data Layer by event type :

  • For Page View & Product View :
    • productSKU : (string) recommended for “Product View” use cases. Define the identifier for a product
    • userId : (string) recommended for reconciliation of authenticated users. It can be specified once for all for all event types
  • For Add To Cart :
    • productInCart object, with this content :
      productInCart: {
      	sku: '<mandator_product_id_or_sku>',
      	name: '<mandator_product_name>',
      	category: '<product_category>',
      	unitPrice: <mandator_product_price>,
      	quantity: <product_quantity_added>,
      	currency: '<currency>'
      }
      
    • userId : (string) recommended for reconciliation of authenticated users.

📘

The way you can integrate these properties in the Google Tag Manager Data Layer will actually depend on your ecommerce solution. You can follow standard Google Tag Manager guides for help

Here an example of initialization of data Layer on a Typescript SPA ecommerce site :

// Define dataLayer type
declare global {
	interface Window {
		dataLayer: Record<string, any>[];
	}
}

// ...

// Example for an "AddToCart" event
window.dataLayer.push({
	// To use with a custom event type trigger
	event: 'addToCart',
	// Optional authenticated contact id
	userId: user.logged.id,
	// Payload for product added in cart
	productInCart: {
		sku: newProduct.sku,
		name: newProduct.title,
		category: 't-shirt',
		unitPrice: newProduct.price,
		quantity: newProduct.quantity,
		currency: newProduct.currencyId
	}
});

Initialize all the variables required by tags

From the tag configuration you will refer to the specific contents (usually available in the Google Tag Manager Data Layer) required by each event type through specific variables

The 3 default data Layer variables to create are :

Variable NameValue
DL - productInCartproductInCart
DL - productSKUproductSKU
DL - userIduserId

Once the variable are ready you can use them in your tag configuration