Developer docs // JavaScript API

Full instructions on how to install our web tracking code on your bespoke e-commerce platform

Overview

Note: This entire page is only relevant if you have a bespoke e-commerce platform. If you use Magento, BigCommerce, Shopify or WooCommerce you can install our plugins directly from the respective app store (i.e. Magento Connect)


Welcome to our JavaScript developer documentation. Our JavaScript installation is really flexible and should be quite quick to get installed. We typically find that it takes anywhere between a hour or so to a day at most, it all depends on how well you know your system and the customer/product information you have available when developing.

What you'll need to do:

  1. Copy/paste our basic tracking code script
  2. Identify customers (i.e. when they log in etc...)
  3. Track specific pages (like products, order placed etc...)

We're totally here to help, so please get in touch with us if you've got any questions or just need some technical help.

Install the basic tracking code

In order to start tracking your visitors, the Seg asynchronous javascript library needs to be installed on your website. To do this visit the integrations / website section of Seg, then copy and paste the code snippet into your HTML just before the </HEAD> element closes. This should be installed on every page on your website ideally.

<script type="text/javascript">
    ;(function () { var a, b, c, e = window, f = document, g = arguments, h = "script", i = ["config", "track", "identify", "callback"], j = function () { var a, b = this; for (b._s = [], a = 0; a < i.length; a++) !function (a) { b[a] = function () { return b._s.push([a].concat(Array.prototype.slice.call(arguments, 0))), b } }(i[a]) }; for (e._seg = e._seg || {}, a = 0; g.length > a; a++) e._seg[g[a]] = e[g[a]] = e[g[a]] || new j; b = f.createElement(h), b.async = 1, b.src = "https://seg-js.azureedge.net/seg-analytics.min.js", c = f.getElementsByTagName(h)[0], c.parentNode.insertBefore(b, c) }("seg"));
    
    // Unique website identifying code
    seg.config({
        site: "{ Your Website Identifier }"
    });
</script>

Identifying customers

You need to tell Seg who the visitor is (if you can), on every page possible. A visitor is be identified to Seg by passing an Email property to the seg.identify() function:

seg.identify( { "Email" : "the email address for your visitor" } );

Supplying extra customer information

Seg accepts any information you have about your customers, at any time and of any type. All you need to do is pass in a non-null value (in a native javascript type) with a property name. Examples below.

Seg also has some reserved property names, these are:

Property Description
Email The email address of the customer (required)
FirstName The first name of the customer
LastName The last name of the customer
Title The title of the customer (i.e. Mr, Mrs)
CountryCode The ISO 3166-1 alpha-3 / alpha-2 letter country code of the country of the customer.

All properties (except Email) are optional. If any properties are specified, they get added to the Seg customer profile, or get updated if they already exist. This means you do not need to provide a full customer definition every time you call seg.identify, only when the information changes.

Examples

// An example of a the bare minimum code identifying a visitor
seg.identify({
    "Email" : "[email protected]"
});
// An example of a full customer definition without any extra company specific information
// All properties (except Email) are optional. 
seg.identify({
    "Email" : "[email protected]",
    "Title" : "Mr",
    "FirstName" : "Don",
    "LastName" : "Draper",
    "CountryCode" : "USA"
});
// An example of a full customer definition adding an additional and additional 4 properties known about the customer
seg.identify({
    "Email" : "[email protected]",
    "Title" : "Mr",
    "FirstName" : "Don",
    "LastName" : "Draper",
    "CountryCode" : "USA",
    "NumberOfDogs" : 0,
    "DateOfBirth" : new Date("1926-01-01"),
    "HasBeenDivorced" : true,
    "PreviousName" : "Richard Whitman"
});

Changing a customer's email address

To update a customer's email address, all you need to do is supply one extra property in the seg.identify method: OldEmail. For example:

// An example of updating a customer's email address by supplying the old and new/current email address, along with some optional additional properties
seg.identify({
    "OldEmail" : "[email protected]",
    "Email" : "[email protected]",
    "Title" : "Mr",
    "FirstName" : "Don",
    "LastName" : "Draper",
    "CountryCode" : "USA",
    "NumberOfDogs" : 0,
    "DateOfBirth" : new Date("1926-01-01"),
    "HasBeenDivorced" : true,
    "PreviousName" : "Richard Whitman"
});

Automatic idenfitication and country code lookup new

Seg automatically attempts to identify customers by monitoring all input fields and forms for an email address. This only applies if Seg has not been told who the visitor is.

Seg also automatically identifies the country of the visitor if not specified by performing a geo IP lookup.

Best practice

  1. Call seg.identify on every page, if you know who the customer is.

    For the best results and for us to assign (and not assume) the correct events with the correct customer we require that you identify the customers if you know who they are for every event you send to Seg. In practice this is simple to do, simply call seg.identify if you now who the customers is.

  2. Quote property names by default

    The properties object passed to the function must have valid JavaScript object property names. The best way to ensure this is to quote all property names.

Events

Seg requires you to fire one, and only one, event per page the visitor views. You can choose from one of 5 events we support:

  1. Page view - Use this to track unknown or generic pages
  2. Range view - Use this to track groups of products (like category pages)
  3. Product view - Use this to track a single product view
  4. Added to basket - Use this when adding or viewing a basket/cart
  5. Order placed - Use this when an order is placed

Tags - what are they?

Tags are accepted on all the events above. They are an array of strings in Javascript. They are a core part of Seg's understanding of what the customer is doing and typically represent things like brand names, or category names.

For example: if a customer is looking at a product that exists in the following place: "Home > Men > Shirts", then we would expect the Tags to be populated as follows:

// An example product view event demonstrating how Tags should be populated
seg.track("ProductView", {
    "Id": "Product Id",
    "ImageUrl": "http://example.com/url-to-product-image",
    "Name": "Product Name",
    "OriginalPrice": 19.99,
    "Price": 17.49,
    "VariantName": "Product Variant Name",
    "Tags": [ "Men", "Shirts" ]
});

Generic page view event

An event that is not either a "ProductView", "RangeView", "AddedToBasket" or "OrderPlaced" event should be tracked a generic "PageView" event as described below.

You should use these events if no other event makes sense to use.

// track a page view
seg.track();
    
// or track a page view with some Tags
seg.track('PageView', {
    "Tags": [
        "tag1",
        "tag2",
        "tag3"
    ]
});

Range view event

If the customer is looking at a range of items (such as a category or brand page), this event should be used. As with other events, this event is used to infer the customer's preferences profiles.

// track a range view
seg.track('RangeView', {
    "Tags": [
        "tag1",
        "tag2",
        "tag3"
    ]
});

The following properties are recognised on a RangeView event:

Name Description
Tags A collection of tags to associate with the event, such as a brand name or category names. Learn about tags.

Product view event

If the customer is looking at a specific product page, this event should be used.

// track a product view
seg.track('ProductView', {
    "Id": "Product Id",
    "ImageUrl": "http://example.com/url-to-product-image",
    "Name": "Product Name",
    "OriginalPrice": 19.99,
    "Price": 17.49,
    "VariantName": "Product Variant Name",
    "Tags": [
        "tag1",
        "tag2",
        "tag3"
    ]
});

The following properties are recognised on a ProductView event:

All properties contained in it are optional. However, it is good practice to pass in as much as you can. Of particular interest is the Tags array. No other properties can be passed in other than those specified.

Name Description
Id The ID of the product
Name The name of the product
OriginalPrice The original price of the product (if different from price)
VariantName A variant name of the product if for example, the product is a variation of a more general product
Tags A collection of tags to associate with the event. Learn about tags.
Price The price of the product
ImageUrl A public URL resource to an image of the product

Added to basket event

AddedToBasket events are recommended for use on pages following the addition of a product to the customers shopping basket / cart. Ideally it will describe the entire basket not just the item added. It can also be used when the customer is simply viewing their basket / cart (just set added: false on all OrderLines)

// track an added to basket event
seg.track('AddedToBasket', {
    "DeliveryMethod": "1st Class",
    "DeliveryRevenue": 2.99,
    "Discount": 5.00,
    "Id": "{Optional reference Id}",
    "OrderLines": [
        {
            "Added": true, // Use this to indicate that this is the product that was just added to the basket
            "Quantity": 2,
            "Id": "Product Id",
            "ImageUrl": "http://example.com/url-to-product-image",
            "Name": "Product Name",
            "OriginalPrice": 1.99,
            "Price": 1.29,
            "VariantName": "Product Variant Name",
            "Tags": [
                "tag1",
                "tag2",
                "tag3"
            ]
        },
        {
            "Quantity": 1,
            "Id": "Product 2 Id",
            "ImageUrl": "http://example.com/url-to-product-image-2",
            "Name": "Product 2 Name",
            "Price": 9.99,
            "VariantName": "Product 2 Variant Name",
            "Tags": [
                "tag2",
                "tag3",
                "tag4"
            ]
        }
    ],
    "_p": 5.25,
    "Revenue": 12.57
});

The following properties are recognised on an AddedToBasket event

All properties contained in it are optional. However, it is good practice to pass in as much as you can. Of particular interest is the tags collections in the OrderLines array.

Name Description
Id The ID of the event, if applicable
DeliveryRevenue The revenue generated from the delivery/shipping method
DeliveryMethod The delivery/shipping method chosen
Revenue The total cart revenue.
Profit The total profit generated from the cart. This is sent as a property named '_p'
Discount The cart discount value
OrderLines A collection of products associated with the event.

Each item in the OrderLines collection has the following properties

Name Description
Id The ID of the product
Name The name of the product
OriginalPrice The original price of the product (if different from price)
Tags A collection of tags to associate with the product. Learn about tags.
VariantName A variant name of the product if for example, the product is a variation of a more general product i.e. A product might be called " Luxury Shampoo", and the customer has added a "500ml" variant to the basket
Quantity The quantity of the product
Price The price of the product
ImageUrl A public URL resource to an image of the product
Added Indicates if this product was added to the basket in this event (multiple lines can have this set to true if required)

Order placed event

OrderPlaced events are recommended for use on pages following the placing of a customer order.

// track an orderplaced event
seg.track('OrderPlaced', {
    "DeliveryMethod": "1st Class",
    "DeliveryRevenue": 2.99,
    "Discount": 5.00,
    "Id": "Order Id",
    "OrderLines": [
        {
            "Quantity": 2,
            "Id": "Product Id",
            "ImageUrl": "http://example.com/url-to-product-image",
            "Name": "Product Name",
            "OriginalPrice": 1.99,
            "Price": 1.29,
            "VariantName": "Product Variant Name",
            "Tags": [
                "tag1",
                "tag2",
                "tag3"
            ]
        },
        {
            "Quantity": 1,
            "Id": "Product 2 Id",
            "ImageUrl": "http://example.com/url-to-product-image-2",
            "Name": "Product 2 Name",
            "Price": 9.99,
            "VariantName": "Product 2 Variant Name",
            "Tags": [
                "tag2",
                "tag3",
                "tag4"
            ]
        }
    ],
    "_p": 5.25,
    "Revenue": 12.57
});

The following properties are recognised on an OrderPlaced event. It is functionally the same as the AddedToBasket event with the exception of the OrderLines.added property.

All properties contained in it are optional. However, it is good practice to pass in as much as you can. Of particular interest is the tags collections in the OrderLines array.

Name Description
Id The ID of the event, if applicable
DeliveryRevenue The revenue generated from the delivery method
DeliveryMethod The delivery method chosen
Revenue The total revenue of the order.
Profit The total profit generated from the order. This is sent as a property named '_p'
Discount The discount value
OrderLines A collection of products associated with the event.

Each item in the OrderLines collection has the following properties

Name Description
Id The ID of the product
Name The name of the product
OriginalPrice The original unit price of the product (if different from price)
Tags A collection of tags to associate with the product purchased. Learn about tags.
VariantName A variant name of the product if for example, the product is a variation of a more general product i.e. A product might be called " Luxury Shampoo", and the customer has added a "500ml" variant to the basket
Quantity The quantity of the product
Price The unit price of the product (the single unit price)
ImageUrl A public URL resource to an image of the product

Full working examples

Putting it all together on one page would look like this:

Example 1) a known customer viewing a white shirt:

<head>
    <script type="text/javascript">
        ;(function () { var a, b, c, e = window, f = document, g = arguments, h = "script", i = ["config", "track", "identify", "callback"], j = function () { var a, b = this; for (b._s = [], a = 0; a < i.length; a++) !function (a) { b[a] = function () { return b._s.push([a].concat(Array.prototype.slice.call(arguments, 0))), b } }(i[a]) }; for (e._seg = e._seg || {}, a = 0; g.length > a; a++) e._seg[g[a]] = e[g[a]] = e[g[a]] || new j; b = f.createElement(h), b.async = 1, b.src = "https://seg-js.azureedge.net/seg-analytics.min.js", c = f.getElementsByTagName(h)[0], c.parentNode.insertBefore(b, c) }("seg"));
    
        // Unique website identifying code (mandatory)
        // Do not copy this website id!
        seg.config({
            site: "25892e17-80f6-415f-9c65-7395632f0223"
        });
    </script>
</head>
    
<body>
    <!-- This is where you would have your website body HTML //-->
    <script type="text/javascript">
        // Identifying the customer (optional) 
        seg.identify({
            "Email" : "[email protected]",
            "Title" : "Mr",
            "FirstName" : "Don",
            "LastName" : "Draper",
            "CountryCode" : "USA"
        });
    
        // Tracking an event (a product view in this instance) (mandatory)
        // It is at this point that a request is fired to Seg, not before. 
        seg.track("ProductView", {
            "Id": "123",
            "ImageUrl": "http://example.com/product-image.jpg",
            "Name": "A White Shirt",
            "OriginalPrice": 19.99,
            "Price": 17.49,
            "VariantName": "Medium",
            "Tags": [ 
                "Men", 
                "Shirts"
            ]
        });
    </script>
</body>

Example 2) an unknown customer viewing a range of white shirts:

<head>
    <script type="text/javascript">
        ;(function () { var a, b, c, e = window, f = document, g = arguments, h = "script", i = ["config", "track", "identify", "callback"], j = function () { var a, b = this; for (b._s = [], a = 0; a < i.length; a++) !function (a) { b[a] = function () { return b._s.push([a].concat(Array.prototype.slice.call(arguments, 0))), b } }(i[a]) }; for (e._seg = e._seg || {}, a = 0; g.length > a; a++) e._seg[g[a]] = e[g[a]] = e[g[a]] || new j; b = f.createElement(h), b.async = 1, b.src = "https://seg-js.azureedge.net/seg-analytics.min.js", c = f.getElementsByTagName(h)[0], c.parentNode.insertBefore(b, c) }("seg"));
    
        // Unique website identifying code (mandatory)
        // Do not copy this website id!
        seg.config({
            site: "25892e17-80f6-415f-9c65-7395632f0223"
        });
    </script>
</head>
    
<body>
    <!-- This is where you would have your website body HTML //-->
    
    <script type="text/javascript">
    // Tracking an event (a range view in this instance) (mandatory)
    // It is at this point that a request is fired to Seg, not before. 
    seg.track("RangeView", {
        "Tags": [ 
            "Men", 
            "Shirts"
        ]
    });                         
    </script>
</body>

Example 3) a full 'OrderPlaced' example:

<head>
    <script type="text/javascript">
        ;(function () { var a, b, c, e = window, f = document, g = arguments, h = "script", i = ["config", "track", "identify", "callback"], j = function () { var a, b = this; for (b._s = [], a = 0; a < i.length; a++) !function (a) { b[a] = function () { return b._s.push([a].concat(Array.prototype.slice.call(arguments, 0))), b } }(i[a]) }; for (e._seg = e._seg || {}, a = 0; g.length > a; a++) e._seg[g[a]] = e[g[a]] = e[g[a]] || new j; b = f.createElement(h), b.async = 1, b.src = "https://seg-js.azureedge.net/seg-analytics.min.js", c = f.getElementsByTagName(h)[0], c.parentNode.insertBefore(b, c) }("seg"));
    
        // Unique website identifying code (mandatory)
        // Do not copy this website id!
        seg.config({
            site: "25892e17-80f6-415f-9c65-7395632f0223"
        });
    </script>
</head>
    
<body>
    <!-- This is where you would have your website body HTML //-->
    
    <script type="text/javascript">
    // Tracking an event (an order placed event in this instance) (mandatory)
    // It is at this point that a request is fired to Seg, not before. 
    seg.identify({
        "Email" : "[email protected]"
    });

    seg.track('OrderPlaced', {
        "DeliveryMethod": "1st Class",
        "DeliveryRevenue": 2.99,
        "Discount": 5.00,
        "Id": "Order Id",
        "OrderLines": [
            {
                "Quantity": 2,
                "Id": "Product Id",
                "ImageUrl": "http://example.com/url-to-product-image",
                "Name": "Product Name",
                "OriginalPrice": 1.99,
                "Price": 1.29,
                "VariantName": "Product Variant Name",
                "Tags": [
                    "tag1",
                    "tag2",
                    "tag3"
                ]
            },
            {
                "Quantity": 1,
                "Id": "Product 2 Id",
                "ImageUrl": "http://example.com/url-to-product-image-2",
                "Name": "Product 2 Name",
                "Price": 9.99,
                "VariantName": "Product 2 Variant Name",
                "Tags": [
                    "tag2",
                    "tag3",
                    "tag4"
                ]
            }
        ],
        "_p": 5.25,
        "Revenue": 12.57
    });
    </script>
</body>