Implementing the Tweakwise Event Tag is an essential step for us to analyze the performance of your configuration, power our insights reports and support personalization. To support this we need key e-commerce events on your platform. These are events such as product views, item clicks, add-to-carts, and purchases.

To get more insights, follow these steps:

• Install the snippet
• Track:
  • search phrases on search results pages
  • product views when viewing a product (detail page)
  • purchases when a conversion is logged (order is placed)
  • add to cart on product detail pages, or other quick-add locations.
  • add to wishlist on product detail pages or other quick-add locations.
  • item clicks on category pages, search results, suggestions and recommendations *
  • session start on new sessions *
  • pageimpression on category pages, search results *
  • add to cart on Plugin Studio tiles **

* when using Tweakwise JS, these events are working out of the box

** tiles containing an add to cart button that are part of Tweakwise JS will work out of the box, any other add to carts need to be sent manually.

Looking for a server-to-server option? Check out Event Tag - Server-to-server.

Before you begin

Some events require a ProductKey. This is not your shop’s SKU or internal ID, but the item ID as known in Tweakwise.

Before sending events, make sure these match up:

• Use the correct identifier: the ProductKey must match the item ID in your Tweakwise feed. If it doesn’t, the event won’t link to the right product.
• Check for multi-store setups: in multi-language or multi-store environments, the item key often includes a storeview prefix (for example 1000102345 or 1000202345). Always send the key with the correct prefix for that storeview.

Installation

The Insights Tag is a lightweight javascript SDK to capture key e-commerce events on your platform. To make use of essentials or personalization, implement the following snippet on the frontend of your platform:

 <script>
    (function(w, d, l, i, u) {
      w['_twa'] = l;
      w[l] = w[l] || [];
      w[l].push({ 'twa.start': new Date().getTime(), event: 'twa.js' });
      w[l].push({ 'twa.instance': i, event: 'twa.init' });
      var f = d.getElementsByTagName('script')[0],
          j = d.createElement('script');
      j.async = true;
      j.src = u;
      f.parentNode.insertBefore(j, f);
    })(window, document, 'tweakwiseLayer', '{instancekey}', "//navigator-analytics.tweakwise.com/bundles/scout.js");
    </script>

Notes:

• Replace {instancekey} with your instance key. You can find the key on your app dashboard.

🚧

CSP

If you implemented a Content Security Policy, make sure navigator-analytics.tweakwise.com is added to the allowed domains list.

Custom profilekey

In some cases, you might want to determine the profile key yourself. For example if you want to support cross-device personalization. In these cases is is recommended to use the currently authenticated user.

Replace the default snippet with:

 <script>
    var profileKey = '{profilekey}';

    (function(w, d, l, i, p, u) {

      w['_twa'] = l;
      w[l] = w[l] || [];
      w[l].push({ 'twa.start': new Date().getTime(), event: 'twa.js' });
      w[l].push({ 'twa.instance': i, event: 'twa.init' });
      
      p && w[l].push({ 'twa.profile': p, event: 'twa.profile' });
  		if(p){ w[l].getProfileKey = function(){ return p; } }

      var f = d.getElementsByTagName('script')[0],
          j = d.createElement('script');
      j.async = true;
      j.src = u;
      f.parentNode.insertBefore(j, f);

    })(window, document, 'tweakwiseLayer', '{instancekey}', profileKey, "//navigator-analytics.tweakwise.com/bundles/scout.js");
    </script>

• Replace {instancekey} with your instance key. You can find the key on your app dashboard.
• Replace {profilekey} with a reference to the current customer/visitor.

Events

To analyze the performance of your configuration and power some of our insights reports, we gather information from key requests.

Search

To measure the amount of search queries, send a search event when the search results page. I is displayed user enters a search term, including the term the user has entered.

tweakwiseLayer.push({
  event: 'search',
	data: {
		searchTerm: 'Jeans'
  }
});

Click product

To measure how many times an item is clicked, send a itemClick event whenever a user clicks/taps an item. It is crucial for analyzing the performance of builder components.

tweakwiseLayer.push({
	event: 'itemClick',
	data: {
		itemId: 'item-id-123',
		requestId: '45fdf-a5401-845d5-596b7-99226-14a43-5bcf'
	}
});

<template>
  <div v-for="product in navigation.items" class="group" @click="onProductClick">
    <a :href="product.href" class="aspect-square w-full bg-gray-100">
      <img :src="product.image" class="aspect-square object-cover" />
    </a>
    <h3 class="mt-4 font-bold"><a :href="product.href">{{ product.title }}</a></h3>
    <p>{{ $n(product.price, 'currency') }}</p>
  </div>
</template>

<script lang="ts" setup>
let url = `https://gateway.tweakwisenavigator.com/navigation/${instanceKey}/?tn_cid=${cid}&format=json`;

const { data, error } = await useAsyncData('category:' + cid, async () => {  
  const response = await $fetch.raw(url, { responseType: 'json' });  
  
  // save requestid to pass on to client
  const requestId = response.headers.get('twn-request-id');
  
  return { navigation: response._data, requestId };
})

function onProductClick() {
    window['tweakwiseLayer'].push({
        event: 'itemClick',
        data: {
            itemId: product.itemno,
            requestId: requestId
        }
    })
}
</script>

Notes:

• Using Tweakwise JS? This will work out of the box!
• This is only available if a response contains a requestId. To learn more, go to About requestid.
• When implementing the Tweakwise event tag in Google Tag Manager (GTM), you need to store the requestId from the Tweakwise navigation-search response and pass it to the dataLayer. This allows you to use the requestId in your GTM tags and triggers.

View product

To measure how many times item details are viewed, send a productView event whenever a user views an item’s details screen.

tweakwiseLayer.push({
	event: 'productView',
	data: {
		productKey: 'ARTICLENUMBER1'
	}
});

Purchase

The purchase event tracks the transaction of your customers. It is crucial for analyzing the performance of A/B tests, builder, filter templates and more.

tweakwiseLayer.push({
	event: 'purchase',
	data: {
		productKeys: ['ARTICLENUMBER1', 'ARTICLENUMBER2', 'ARTICLENUMBER3'],
    revenue: 124.50
	}
});

Add to cart

The addtocart event tracks cart additions.

tweakwiseLayer.push({
	event: 'addtocart',
	data: {
		productKey: 'ARTICLENUMBER1',
		quantity: 1,
		totalAmount: 124.50
	}
});

Add to wishlist

The addtowishlist event tracks wishlist/favorite additions.

tweakwiseLayer.push({
	event: 'addtowishlist',
	data: {
		productKey: 'ARTICLENUMBER1'
	}
});