Support Center

Advanced: Shopgate Tracking Variables and Events

Follow

In this article, you will find out in-depth knowledge about the Javascript variables and events used in the Shopgate custom tracking code system.

 This article is designed for advanced Javascript coders who intend to create or customize a tracking code for a Shopgate mobile shop. For basic information on how to convert and embed an existing tracking code, read Embedding a custom tracking code

 

Topics covered in this article:

  1. Getting started
  2. The Tracking Variables
  3. The Tracking Events
  4. Frequently Asked Questions (FAQ)

 

 

1. Getting started

The Shopgate custom tracking code system is a Javascript-based system with 150+ pre-defined variables for tracking various customer behaviors of a Shopgate mobile app and website.

1.1 An example code

Here is a tracking code example customized with Shopgate Variables (highlighted in yellow):

// Facebook Tracking Code for Conversion Rate

var cart_items_amount_net = sgData.order.amount.net - sgData.order.shipping.amount.net - sgData.order.payment.amount.net;

(function() {
var _fbq = window._fbq || (window._fbq = []);
if (!_fbq.loaded) {
var fbds = document.createElement('script');
fbds.async = true;
fbds.src = '//connect.facebook.net/en_US/fbds.js';
var s = document.getElementsByTagName('script')[0];
s.parentNode.insertBefore(fbds, s);
_fbq.loaded = true;
}
})();
window._fbq = window._fbq || [];
window._fbq.push(['track', 'xxxx_your_id_xxxx', {'value':cart_items_amount_net,'currency': sgData.order.amount.currency}]);

 

In this example, the Shopgate variables used are:

Shopgate Variable Description
sgData.order.amount.net This variable gives you the value amount of an order before taxes.
sgData.order.shipping.amount.net This variable gives you the shipping costs of an order before taxes.
sgData.order.payment.amount.net This variable gives you the payment amount of an order before taxes
sgData.order.amount.currency This variable tells you the currency of this order.

Click here for a complete list of available variables with details.

 

 

1.2 Available platforms and pages

Some of the Shopgate variables are made available on all pages; more are designed for a specific page only. All variables can be used on both the mobile website and native apps.

For example,

  • sgData.device: Available on every page of your apps and mobile site.
  • sgData.cart.products[].uid: Available only on the Shopping cart page of your apps and mobile site.

In the table below, you can see all the available platforms and pages. Click on a page to jump to a list of variables that are available for this page.

Available Platform Available Page
All platforms

Mobile Website Smartphone
Mobile Website Tablets
Mobile Website Smartphone + Tablets

Native Apps Smartphone
Native Apps Tablets
Native Apps Smartphone + Tablets
All pages
Start Page / Homepage (sgData.page.startpage*)
Search (sgData.page.search)
Product List (sgData.page.productList)
Product Detail Page (sgData.page.productDetails)
Shopping Cart (sgData.page.cart)
Login / Registration (sgData.page.loginAndRegister)
Checkout Summary (sgData.page.checkoutConfirm)
Checkout Success (sgData.page.checkoutSuccess)

* This is the Javascript name of this page. 

IMPORTANT: Duplicate tracking code for a page can hurt your mobile SEO. How to avoid using duplicate tracking code?

 

 

1.3 How to embed a custom tracking code at Shopgate

To embed a custom tracking code function in your Shopgate apps and mobile website, follow the steps here:

  1. Log in to your Shopgate Admin. Click on Settings from the menu bar, then select  Tracking Tools.
  2. Locate the Tracking codes section, select a platform and a page to display the code, and click +Add. Click here to see all available platforms and pages
  3. An empty script editor will open. Simply type or paste your tracking code here and click Save.
    Use keyboard shortcut CTRL+Space to show a list of variables available on this page.

That's it! This is how to embed a custom tracking code. Repeat the steps to enter another code.

 

 

2. The Tracking Variables

In this chapter, you will find all the details about the pre-defined tracking variables.

2.1 All Pages

The following variables are available on all platforms and pages.

Variable Availability Description Example
sgData.device Always Information about the mobile device Object
sgData.device.codebase Apps only Codebase version of our apps "7.1.0"
sgData.device.userAgent Always User Agent "Mozilla/3.0 (iPhone; CPU iPhone OS 5_0 likeMac OS X) AppleWebKit/532.46 (KHTML, likeGecko) Version/3.1 Mobile/9A334 Safari/7532.48.3"
"Mozilla/3.0 (iPad; CPU OS 8_0 like Mac OS X) AppleWebKit/538.32.9 (KHTML, like Gecko) Mobile/12A4265u"
sgData.device.os Always Operating system "iOS"
"Android"
"Other"
sgData.device.type Always Type of mobile website "Phone"
"Tablet"
sgData.device.access Always Type of app "web"
"Native"
sgData.page Always Object with page info  
sgData.page.title Always Page title  
sgData.page.name Always Name of the current page "startpage" for Start Page / Homepage
"search" for Search
"productList" for Product List
"productDetails" for Product Detail Page
"cart" for Shopping Cart
"loginAndRegister" for Login / Registration
"checkoutConfirm" for Checkout Summary Page
"checkoutSuccess" for Checkout Success Page
sgData.page.link   Current URL "http://m.myshop.com/product/435230303631"
"http://myshop.shopgate.com/product/435230303631"
sgData.page.referrer Always Referrer http://www.myshop.com
sgData.user Always Object with user info  
sgData.user.email Only when logged in Email address of the logged-in user name@myshop.com
sgData.user.gender Only when logged in Sex of the logged-in user "m" / "f"
sgData.user.phone Only when logged in Phone number of the logged-in user  
sgData.user.birthday Only when logged in Birthday of the logged-in user "1972-07-22"
sgData.user.sessionId Always md5('tr1014'.session_id().'ack13') "7e716d0e702df0505fc72e2b89467910"
sgData.user.loggedIn Always Is the user logged in? "true"
"false"
sgData.tracking.get.$key Optional Get the parameters that GET Parameter has white-listed as cookies, or is written in this session. Object
sgData.tracking.get.$key.value Optional Value of the GET Parameter  

 

2.2 Start Page / Homepage

Please see variables from "All Pages" table.

 

2.3 Search

Variable Availability Description Example
sgData.search Always

Search information

Object
sgData.search.query Always Keywords that were searched for "Nike Air Max"
"Winter socks"
sgData.search.resultCount Always Number of results found "152"
"0"

 

2.4 Product List

Variable Availability Description Example
sgData.category Always Category information Object
sgData.category.uid Always Category number "104256"
"52-21-74"
"ja8z2ha92712jd8917wh1923-47443d"
"5%542$SALE$"
sgData.category.name Always Category name "Shoes"
"13 Inches"
"Women"
sgData.category.path Always Category path "Clothes=>Men=>Jeans"
"Technic=>Laptops=>13 Inches"
"Socks=>Women"
sgData.products[] Always List of products displayed (use the same product info as the product detail page.) Array

 

2.5 Product Detail Page

Variable Availability Description Example
sgData.product Always Product Information Object
sgData.product.tags[] Always List of tags for products Array
sgData.product.uid Always "Shopproduct.product_number" from our database 1231341
3131121
sgData.product.productNumber Optional "Shopproduct.product_number_public" from our database foo12
18219
aouhiu
sgData.product.name Always product_name Cotton jacket with hood
"Fisticup" Coffee Mug by Inked (Black)
sgData.product.amount Always    
sgData.product.amount.currency Always Currency ID, based on ISO_4217 standard "USD"
"EUR"
sgData.product.amount.net Always Net amount "12.11"
"1.00"
"9889.00"
sgData.product.amount.gross Always Gross amount "12.99"
"3.99"
sgData.product.amount.tax Always Tax amount "0.11"
sgData.product.amount.taxRate Always Tax (VAT) rate "19.00"
sgData.product.stockQuantity Always Number of products in stock "5"

 

2.6 Shopping Cart

Variable Availability Description Example
sgData.cart Always Object with information about the shopping cart Object
sgData.cart.orderable Always Is the cart in this form ordered true
false
sgData.cart.amount.currency Always Currency ID, based on ISO_4217 standard "USD"
"EUR"
sgData.cart.amount.net Always Total net amount from cart, including shipping and other costs  
sgData.cart.amount.gross Always Total gross amount from cart, including shipping and other costs  
sgData.cart.amount.tax Always Total tax amount from cart  
sgData.cart.amount.taxes[].tax Optional    
sgData.cart.amount.taxes[].taxRate Optional    
sgData.cart.amount.products Always Information about products in cart Object
sgData.cart.productsCount Always Number of products in cart  
sgData.cart.products[].tags[] Always List of tags for products Array
sgData.cart.products[].uid Always Product number from Shopgate  
sgData.cart.products[].productNumber Always Product number public from your shop system  
sgData.cart.products[].name Always Product name  
sgData.cart.products[].quantity Always Number of a product in cart  
sgData.cart.products[].stockQuantity Always Number of a product in stock "5"
sgData.cart.products[].amount.currency Always Currency ID, based on ISO_4217 standard "USD"
"EUR"
sgData.cart.products[].amount.net Always

Net price from the product

 
sgData.cart.products[].amount.gross Always Gross price from the product  
sgData.cart.products[].amount.tax Always VAT amount of the product  
sgData.cart.products[].amount.taxRate Always VAT rate of the product  
sgData.cart.products[].additionalShippingCosts Optional   Object
sgData.cart.products[].additionalShippingCosts.perOrder Optional Additional shipping cost per order  
sgData.cart.products[].additionalShippingCosts.perUnit Optional Additional shipping costs per unit  
sgData.cart.coupons[].code Optional Coupon code  
sgData.cart.coupons[].discountAmount Optional Coupon value  
sgData.cart.coupons[].discountPercent Optional Coupon discount in percentage  

 

2.7 Checkout Summary Page

Variable Availability Description Example
sgData.cart Always Object with information about the shopping cart Object
sgData.checkout Always Information on selected addresses, payment method and shipping Object
sgData.checkout.payment.name Always Name of the payment method 'Authorize.net', 'PayPal'
sgData.checkout.shipping.name Always Name of the shipping method 'DHL Express'
sgData.checkout.shippingAddress Always Shipping address information Object
sgData.checkout.shippingAddress.firstName Always First name of the customer in the shipping address  
sgData.checkout.shippingAddress.surname Always Last name of the customer in the shipping address  
sgData.checkout.shippingAddress.company Optional Company of the customer in the shipping address  
sgData.checkout.shippingAddress.street Always Street in the shipping address  
sgData.checkout.shippingAddress.street2 Optional Street line 2 in the shipping address  
sgData.checkout.shippingAddress.zipcode Always

Post code of the shipping address

 
sgData.checkout.shippingAddress.stateId Optional State ID of the shipping address

'CA', 'FL', 'NY'

(ISO_3166)

sgData.checkout.shippingAddress.city Always City of the shipping address  
sgData.checkout.shippingAddress.countryId Always Country ID of the shipping address

ISO_3166-1_alpha-2

sgData.checkout.invoiceAddress   Billing address information  
sgData.checkout.invoiceAddress.firstName Always First name of the customer in the billing address  
sgData.checkout.invoiceAddress.surname Always Last name of the customer in the billing address  
sgData.checkout.invoiceAddress.company Optional Company of the customer in the billing address  
sgData.checkout.invoiceAddress.street Always Street in the billing address  
sgData.checkout.invoiceAddress.street2 Optional Street line 2 in the billing address  
sgData.checkout.invoiceAddress.zipcode Always Post code of the billing address  
sgData.checkout.invoiceAddress.stateId Optional State ID of the billing address

ISO_3166

sgData.checkout.invoiceAddress.city Always City of the billing address  
sgData.checkout.invoiceAddress.countryId Always Country of the billing address

ISO_3166-1_alpha-2

 

2.8 Checkout Success Page

Variable Availability Description Example
sgData.order Always Order information Object
sgData.order.number Always Shopgate Order number 144055402858
sgData.order.amount Always Object  
sgData.order.amount.currency Always Currency ID, based on ISO_4217 standard "USD"
"EUR"
sgData.order.amount.net Always   20.74
sgData.order.amount.gross Always   23.22
sgData.order.amount.tax Always Tax payable on the entire cart 2.48
sgData.order.amount.taxRate
Currently not available
Always

Tax rate of the entire cart (grouped)

 
sgData.order.shipping Always Shipping info Object
sgData.order.shipping.name Always Name of shipping DHL-Express
sgData.order.shipping.amount.currency Always Currency ID, based on ISO_4217 standard "USD"
"EUR"
sgData.order.shipping.amount.net Always Shipping cost net 3.00
sgData.order.shipping.amount.gross Always Shipping cost gross  
sgData.order.shipping.amount.tax Optional Tax amount on shipping costs  
sgData.order.shipping.amount.taxRate
Currently not available
Optional Tax rate on shipping costs  
sgData.order.payment   Payment info Object
sgData.order.payment.name Always Payment name DHL-Express
sgData.order.payment.amount.currency Optional Currency ID, based on ISO_4217 standard "USD"
"EUR"
sgData.order.payment.amount.net Optional Additional cost for payment method net 3.00
sgData.order.payment.amount.gross Optional Additional cost for payment method gross  
sgData.order.payment.amount.tax Optional Tax amount on additional cost for payment method net  
sgData.order.payment.amount.taxRate
Currently not available
Optional Tax rate on additional cost for payment method net  
sgData.order.products[] Always List of products Array
sgData.order.products[].uid Always Unique product ID ("Shopproduct.product_number")  
sgData.order.products[].productNumber Always Public product number ("Shopproduct.product_number_public")  
sgData.order.products[].name Always Product name  
sgData.order.products[].quantity Always Product quantity  
sgData.order.products[].stockQuantity Always Number of product in stock  
sgData.order.products[].amount.currency Always Currency ID, based on ISO_4217 standard "USD"
"EUR"
sgData.order.products[].amount.net Always

Net price of the products

 
sgData.order.products[].amount.gross Always Gross price of the products  
sgData.order.products[].amount.tax Always Tax amount of one product  
sgData.order.products[].stockQuantity Always Stock quantity of one product  
sgData.order.products[].tags[] Always List of tags for products Array
sgData.order.coupons[] Optional Coupon-array Array
sgData.order.coupons[].code Optional Coupon code  
sgData.order.coupons[].amount.currency Optional Currency ID, based on ISO_4217 standard "USD"
"EUR"
sgData.order.coupons[].amount.net Optional Coupon value net  
sgData.order.coupons[].amount.gross Optional Coupon value gross  
sgData.order.coupons[].amount.tax Optional Tax amount of the redeemed coupon  
sgData.order.coupons[].amount.taxRate
Currently not available
Optional Tax rate of the redeemed coupon  
sgData.order.amount.coupons.currency Always Currency ID, based on ISO_4217 standard "USD"
"EUR"
sgData.order.amount.coupons.net Always Coupon value net  
sgData.order.amount.coupons.gross Always Coupon value gross  
sgData.order.shippingAddress Always Shipping address information Object
sgData.order.shippingAddress.firstName Always First name of the customer in the shipping address  
sgData.order.shippingAddress.surname Always Last name of the customer in the shipping address  
sgData.order.shippingAddress.company Optional Company of the customer in the shipping address  
sgData.order.shippingAddress.street Always Street in the shipping address  
sgData.order.shippingAddress.street2 Optional Street line 2 in the shipping address  
sgData.order.shippingAddress.zipcode Always

Post code of the shipping address

 
sgData.order.shippingAddress.stateId Optional  

ISO_3166

sgData.order.shippingAddress.city Always City of the shipping address  
sgData.order.shippingAddress.countryId Always Country of the shipping address

ISO_3166-1_alpha-2

sgData.order.invoiceAddress   Billing address information  
sgData.order.invoiceAddress.firstName Always First name of the customer in the billing address  
sgData.order.invoiceAddress.surname Always Last name of the customer in the billing address  
sgData.order.invoiceAddress.company Optional Company of the customer in the billing address  
sgData.order.invoiceAddress.street Always Street in the billing address  
sgData.order.invoiceAddress.street2 Optional Street line 2 in the billing address  
sgData.order.invoiceAddress.zipcode Always Post code of the billing address  
sgData.order.invoiceAddress.stateId Optional  

ISO_3166

sgData.order.invoiceAddress.city Always City of the billing address  
sgData.order.invoiceAddress.countryId Always Country of the billing address

ISO_3166-1_alpha-2

sgData.order.user   Customer information  
sgData.order.user.customerNumber Always Customer number  
sgData.order.user.externalCustomerId Always    
sgData.order.user.externalCustomerNumber Always    
sgData.order.user.email Always Customer email address name@email.com
sgData.order.user.gender Optional Customer gender "m" or "f"
sgData.order.user.phone Optional Customer phone number  
sgData.order.user.birthday Optional Customer birthday 1971-07-22
sgData.order.field.$key Optional Custom Field ("ExtraField") Object
sgData.order.field.$key.label Optional Field label  
sgData.order.field.$key.value Optional Field value  

 

 

3. The Tracking Events

Apart from the tracking variables mentioned above, we have also pre-defined 4 tracking events for you.

For example,

An example written in jQuery

$(document).on('sgAddToCart', function(e) {
console.log(e.originalEvent.detail);
});

An example written in Vanilla JS

document.addEventListener('sgAddToCart', function(e) {
console.log(e.detail);
});

In the examples, event "sgAddToCart" is used to monitor useful information after the "Add To Cart" button from a specific product has been clicked.

 

To see the details of all the available events, refer to the table below:

Event Description

sgViewAppear

This event is no longer necessary because it is now incorporated in the tracking codes.

Is triggered when the page is called and can be tracked. On the mobile site, this happens after the page has loaded in the app every time the view is displayed. The event is necessary because views can be preloaded in the background, but the background views will not be tracked.

sgProductUpdate Is triggered when a change has been made on the product detail page, e.g. another child product is selected.
sgAddToCart Is triggered when a product is placed into the cart from the product detail page. This event contains data about this product and the products that are in the same product group.
sgCartUpdate Is triggered when a change has been made in the cart, e.g. quantity of a product is changed, a product is removed, or a coupon is added. Contains the updated cart.
sgDataUpdate Is triggered every time a sgData variable is updated by sgDataHelper.

 

 

4. Frequently Asked Questions (FAQ)

4.1 Why isn't code in <noscript> tags necessary?

Your code snippet inside the <noscript>...</noscript> tags is used as a fallback in case Javascript is not available. However, Javascript is required in ALL Shopgate systems. Therefore, you do not need to provide any <noscript> fallback code.

 

4.2 How to avoid using duplicate tracking code?

Your Shopgate tracking code system is designed to execute all tracking codes, including those that are entered more than once on the same page of a platform. Tracking codes set up for "all pages" will be processed in additional to any page-specific tracking codes. Therefore it is recommended to check your tracking codes carefully:

  • Did I enter or paste a code snippet more than once?
  • If I have more than one entry for a page on the same platform, did I enter or paste the same tracking function in more than one entry?
  • If I have a tracking code set up for "All pages", did I remove this tracking code from all other entries?

 

4.3 How to create a tracking pixel?

To create or modify a tracking pixel, refer to the example here. To append parameters such as user email, phone number, etc. to your pixel, use "?" and the available variables (highlighted in yellow):

var image = document.createElement('img');
image.height = '1';
image.width = '1';
image.style = 'border-style:none;';
imgtag.alt = '';
image.src = 'http://yourdomain.com/pixel.png?email='+sgData.user.email+'&phone='+sgData.user.phone;
document.getElementsByTagName('body')[0].appendChild(image);

Click here for a complete list of available variables.

 

 

 

Comments