Configure & self-install the Aqurate Pixel

Find out how to install the Pixel in your Web or Server container in Google Tag Manager

This documentation guides you through the steps required for configuring and installing the Aqurate Pixel. This is applicable to you if:

you use client-side tagging, but prefer that you or your developer(s) setup the Pixel
you use server-side tagging
you have a non-standard data layer implementation

Client-side tagging

Here are the steps you’ll have to go through:

Request the aq-gtm-template.json from support@aqurate.ai
Go to Google Tag Manager and select the container installed in your shop
From the Admin tab, click on Import Container
Click Choose container file and select the aq-gtm-template.json file
Create a New workspace named Aqurate Pixel
Choose the Merge import option, then Overwrite conflicting tags
Hit Confirm, then Submit (in the top-right), then Publish

Server-side tagging

Overview

There are 2 scripts that you must add to your website:

aq-config.js
1. it populates the aqpx variable with information from several data layer variables
2. the aqpx variable is a dictionary of key-value pairs defined as per the schema below
3. in the template provided to you, some values are written in GTM notation eg, {{_event}} . Please update these as necessary for your specific setup.
aqpx.js
1. consumes data from the aqpx variable defined in aq-config.js
2. transforms the data and sends it to Aqurate’s collector pipeline at https://tracker.aqurate.ai

Steps

Here are the steps you’ll have to go through:

Request the aq-config.js and aqpx.js template scripts from support@aqurate.ai
If necessary, update the aq-config.js script to match your data layer format as per the schema and examples below. Here are examples of key-value pairs that might require changes, based on your specific setup:
1. variables relying on GTM’s double curly brackets notation and data layer variables:
  1. event: {{_event}}
  2. clickElement: {{Click Element}}
  3. clickUrl: {{Click URL}}
  4. ecommerce: {{ecommerce}}
  5. currency: ({{ecommerce}} || {}).currency || "CST"
2. variables relying on your event names:
  1. actions.detail, if you have a custom name for the view_item event
  2. actions.purchase, if you have a custom name for the purchase event
  3. actions.add, if you have a custom name for the add_to_cart event
3. optional variables if you have a non-standard data layer implementation (ie, different from the UA/GA4 schema)
  1. customDL.disableAutoData
  2. customDL.data.detail
  3. customDL.data.add
  4. customDL.data.purchase
Add the scripts in your website (first aq-config.js, then aqpx.js) and trigger them on these events (or their equivalent, if you have a non-standard data layer implementation):
1. view_item
2. add_to_cart
3. purchase
4. gtm.linkClick
5. gtm.click → only if the click is on the Add to cart button in an Aqurate widget. You can confirm this by checking if this expression is true:
  gtm.element.closest(aqpx.classes.widgets) && gtm.element.closest(aqpx.classes.add)

Configuring the aqpx variable

The aqpx variable is built as a dictionary with key-value pairs. You may omit any optional keys.

Key	Type	Example	Optional	Description
appId	string	`'1'`	No	The client ID assigned by Aqurate.
platform	string	`'shopify'`	No	The shop platform. Can be one of: `avanticart`, `magento1`, `magento2`, `merchantpro`, `prestashop`, `shopify`, `teamshare`, `custom`
ecommerce	Data Layer variable	`{{ecommerce}}`	No	The `ecommerce` (or equivalent) variable. Read more in the Google Analytics documentation. By default, it uses GTM’s double curly brackets notation for variables.
event	Data Layer variable	`{{_event}}`	No	The `_event` (or equivalent) variable. Read more in the Google Tag Manager documentation. By default, it uses GTM’s double curly brackets notation for variables.
clickElement	Data Layer variable	`{{Click Element}}`	No	The (or equivalent) variable, a reference to the DOM element where the click occurred. Read more in the Google Tag Manager documentation. By default, it uses GTM’s double curly brackets notation for variables.
clickUrl	Data Layer variable	`{{Click URL}}`	No	The (or equivalent) variable, a reference to the DOM element where the click occurred. Read more in the Google Tag Manager documentation. By default, it uses GTM’s double curly brackets notation for variables.
actions	dictionary		No	Used to match `event` against these 3 types of events to capture data: `detail`, `purchase` or `add`
actions.detail	array of strings	`['view_item']`	No	At least one string in this array must match the `event` value when a view occurs on the product detail page (eg, the `view_item` event in the standard data layer implementation, as per the Google Analytics documentation
actions.purchase	array of strings	`['purchase']`	No	At least one string in this array must match the `event` value when a transaction occurs (eg, the `purchase` event in the standard data layer implementation, as per the Google Analytics documentation
actions.add	array of strings	`['purchase']`	No	At least one string in this array must match the `event` value when a product is added to cart (eg, the `add_to_cart`event in the standard data layer implementation, as per the Google Analytics documentation
currency	string	`'EUR'`	No	Three-letter ISO currency code, in lowercase. The default value in the examples below extracts it from the `ecommerce` variable and uses the generic value `CST` as fall-back.
classes	dictionary		No	Used to check if the `gtm.click` or `gtm.linkClick` events have ocurred on an Aqurate widget or element
classes.widgets	string	`'#app-content, .aqurate-personalize'`	No	Comma-separated CSS selectors (element ID or classes) that match Aqurate widgets. Used as a fall-back mechanism to capture `gtm.click` or `gtm.linkClick` events on Aqurate widgets, if the main UTM mechanism is not available for your shop integration.
classes.add	string	`'.aqurate-add-to-cart'`	No	Comma-separated CSS selectors (element ID or classes) that match the Add to cart buttons inside Aqurate widgets. Used to capture `gtm.click` events on Aqurate widgets.
debug	boolean	`false`	No	Used to debug the Aqurate Pixel.
customDL	dictionary		Yes	Used to push specific values for eCommerce data, instead of relying on the Pixel
customDL.disableAutoData	boolean	`false`	Yes	If you have a standard data layer implementation, omit this key or set it to `false`. Otherwise, we highly recommend setting it to `true`. If `true`, all values for `customDL.data` must be also provided.
customDL.data	dictionary		Yes	Used to push specific values for eCommerce data, instead of relying on the Pixel mechanism of auto-extracting data from the data layer. If you have a non-standard data layer implementation, this is highly recommended.
customDL.data.detail	dictionary		Yes	Used to push specific values for the `view_item` event (or equivalent).
customDL.data.detail.items	array of item objects	`{{dl - view_item - items}}` The expression should evaluate to a value in this format: [ { item_id: "SKU_12345", item_name: "Stan and Friends Tee", item_brand: "Google", item_category: "Apparel", price: 10.01, quantity: 3 } ]	Yes	A list of item objects that match the UA or GA4 schema, as per the Google Analytics documentation. Should contain only item object ie, the viewed product.
customDL.data.purchase	dictionary		Yes	Used to push specific values for the `purchase` event (or equivalent).
customDL.data.purchase.items	array of item objects	`{{dl - purchase - items}}` The expression should evaluate to a value in this format: [ { item_id: "SKU_12345", item_name: "Stan and Friends Tee", item_brand: "Google", item_category: "Apparel", price: 10.01, quantity: 3 }, { item_id: "SKU_12346", item_name: "Google Grey Women's Tee", item_brand: "Google", item_category: "Apparel", price: 21.01, quantity: 2 }, ]	Yes	A list of item objects that match the UA or GA4 schema, as per the Google Analytics documentation. Should contain one or more item objects ie, the bought products.
customDL.data.purchase.id	string	`{{dl - transaction id}}` The expression should evaluate to a value in this format: `"T_12345"`	Yes	The unique identifier of the order ie, `transaction_id` (or equivalent).
customDL.data.purchase.value	number	`{{dl - transaction total}}` The expression should evaluate to a value in this format: `72.05`	Yes	The value of the order ie, `value` (or equivalent).
customDL.data.purchase.tax	number	`{{dl - transaction tax}}` The expression should evaluate to a value in this format: `3.60`	Yes	The tax amount of the order ie, `tax` (or equivalent).
customDL.data.purchase.shipping	number	`{{dl - transaction shipping}}` The expression should evaluate to a value in this format: `5.99`	Yes	The shipping amount of the order ie, `shipping` (or equivalent).
customDL.data.add	dictionary		Yes	Used to push specific values for the `add`event (or equivalent).
customDL.data.add.items	array of item objects	`{{dl - add_to_cart - items}}` The expression should evaluate to a value in this format: [ { item_id: "SKU_12345", item_name: "Stan and Friends Tee", item_brand: "Google", item_category: "Apparel", price: 10.01, quantity: 3 } ]	Yes	A list of item objects that match the UA or GA4 schema, as per the Google Analytics documentation. Should contain only item object ie, the product added to cart.
customDL.filters	dictionary		Yes	Used to send data for events only when they match additional conditions
customDL.filters.detail	boolean	`({{Page URL}} \|\| []).includes('/product/')`	Yes	Used to send data for the `view_item` event (or equivalent) only when the expression evaluates to `true`. If set to `true`, all such events are sent.
customDL.filters.purchase	boolean	`({{Page URL}} \|\| []).includes('checkout=done')`	Yes	Used to send data for the `purchase` event (or equivalent) only when the expression evaluates to `true`. If set to `true`, all such events are sent.
customDL.filters.add	boolean	`true`	Yes	Used to send data for the `add_to_cart` event (or equivalent) only when the expression evaluates to `true`. If set to `true`, all such events are sent.
user	dictionary		Yes	Used to send user identifiers for users that are logged-in
user.logged	boolean	`{{DL - userID}} && {{DL - userID}} !== '0' ? true : false`	Yes	An expression evaluating to `true` if the user is logged-in. If `false` or omitted, no user identifiers are sent. If `true`, the values in `user.id` and `user.email` keys are sent.
user.id	string	`{{DL - userID}}`	Yes	The user identifier of the logged-in user. If `user.logged` is `true`, this must not be `null.`
user.email	string	`{{DL - userEmail}}`	Yes	The email of the logged-in user. If not available, set to empty string `''`.
anonymize	boolean	`true`	Yes	If `true`, the data sent to Pixel is further anonymized / minimized.
debugMode	boolean	`false`	Yes	If `true`, the Pixel only sends data for testing purposes

Example 1 - standard aq-config (only mandatory fields)


function() {
    var aqpx = {
      appId: '1',
      platform: 'shopify',
      ecommerce: {{ecommerce}},
      event: {{_event}},
      clickElement: {{Click Element}},
      clickUrl: {{Click URL}},
      actions: {
          detail: ['view_item', '__sm__view_product'],
          purchase: ['purchase', 'conversion', 'transaction', 'prestashop_order_confirmation', 'wd_tranzactie_finalizata'],
          add: ['add_to_cart', 'addToCart', '__sm__add_to_cart']
      },
      currency: ({{ecommerce}} || {}).currency || "CST",
      classes: {
        widgets: '#app-content, .aqurate-personalize',
        add: '.aqurate-add-to-cart'
      },
      debugMode: false
    }
    return aqpx;
}

Example 2 - extended aq-config (all optional fields)


function() {
  var aqpx = {
    appId: '1',
    platform: 'shopify',
    ecommerce: {{ecommerce}},
    event: {{_event}},
    clickElement: {{Click Element}},
    clickUrl: {{Click URL}},
    actions: {
      detail: ['view_item', '__sm__view_product'],
      purchase: ['purchase', 'conversion', 'transaction', 'prestashop_order_confirmation', 'wd_tranzactie_finalizata'],
      add: ['add_to_cart', 'addToCart', '__sm__add_to_cart']
    },
    currency: ({{ecommerce}} || {}).currency || "CST",
    classes: {
      widgets: '#app-content, .aqurate-personalize',
      add: '.aqurate-add-to-cart'
    },
    customDL: { 
      disableAutoData: false,
      data: {
        detail: {
          items: null
        },
        purchase: {
          items: null,
          id: null,
          value: null,
          tax: null,
          shipping: null
        },
        add: {
          items: null
        } 
      },
      filters: {
        detail: true,
        purchase: true,
        add: true
      }
    },
    user: {
      logged: false,
      id: '',
      email: ''
    },
    anonymize: false,
    debugMode: false
  }   
  return aqpx;
}