Embedded JavaScript Listener v1

Table of Contents

• Installation
• Overview
• cordial.identify() - Identifying a contact
• cordial.contact() - Updating a contact
• cordial.event() - Tracking custom events
• cordial.cartitem() - Tracking cart items
• cordial.order() - Tracking orders & purchases
• cordial.forget() - Clearing cookies (useful for a logout event)
• Tracking Google AdWords, traffic source or other URL query string values

Installation

Include the following base script before the closing body tag of the page or site template:

<script>
    (function () {
        window.cordialLoaded = window.cordialLoaded || null;
        var t = document.createElement('script');
        var d = 'd.subdomain.yourbasedomain.com';
        t.setAttribute("data-cordial-track-key", "$accountkey");
        t.setAttribute("data-cordial-url", d);
        t.setAttribute("data-base-domain", 'yourbasedomain.com');
        t.setAttribute("data-auto-track", false);
        t.src = '//'+d+'/track.js';
        t.async = true;
        t.onload = window.cordialLoaded;
        document.body.appendChild(t);
    })();
</script>

Script Attributes

* Required

Setting domain (d) for account

At the time of this writing, Cordial is in the process of moving clients to vanity domains. If you do not yet have a vanity domain, then the domain is track.cordial.io. If you do have a vanity domain, then the domain should be set to d.subdomain.yourbasedomain.com

Setting data-cordial-track-key with your account key

The account key value can be found in the application under your username (top right) -> Administration > Account Settings > Account Info panel, see the Account Key value. If this is not set, make a request via a support ticket or email your Client Success Manager, and a key will be configured promptly.

Setting the data-base-domain

In most instances, contacts will be identified upon visiting your base domain. In order to remain identified when moving from the base domain to a subdomain, such as shop.yourbasedomain.com, it is necessary to store cookies at the base domain level. This will allow cookies to be shared across subdomains branching from the base domain.

Overview - How it works

If a contact arrives on your site from a tracked link, a cookie will be set identifying the referring message ID and the session browser ID.

If the user has not arrived from a tracked link, the user can be identified from another method (Ex: site login, or sign up). You may set the identity of the user as a contact in the cookie using the cordial.identify method.

If there is no referring message or known contact identifier available, the browser ID will be assigned to the session user. All event activity (events captured via cordial.event() method will be tracked for 30 days and attributed to the browser ID. In the event that a contact identifier becomes available for the anonymous user, activity thereafter will be tracked and attributed to the known contact, and previously generated event activity (captured via cordial.event() method) from their anonymous session will be copied into their contact record.

Using t.onload

If the base script is set to load asynchronously, you will need to set a function name in the t.onload attribute and wrap any method calls in that function.

For Example:

function cordialLoaded() {
  cordial.event('browse',{
    "category": "shirts",
    "product": "red t-shirt"
  });
};

cordial.identify() - Identifying a contact

The cordial.identify() method accepts primary or secondary contact identifier values. You may pass an object with authentication data such as an email address or any other valid contact identifier key/value pair.

cordial.identify('email:mark@example.com');
cordial.contact({});

This example is using email as the contact identifier. Other contact identifier key/value pairs such as cID: 58d2fc99ac0c8117814d4e78 and customKey: value can be used in the same manner.

cordial.contact() - Updating or creating a contact record

Once a contact is identified from a tracked link or the identify method, you may call cordial.contact() to add or update a contact record. You may also pass an object of attribute values, or list associations for a new or existing contact.

cordial.contact(contactObect,upsert)

cordial.contact({
   '$attribute-key': 'value for attribute',
   '$attribute-key': 'value for attribute',
   '$list-key': true
   },
   {'upsert': false}
)

'Upsert' is an optional parameter, which if not specified, defaults to 'true' (both insert & update methods will apply). If set to 'false', a new contact record will not be created if one does not already exist (update only).

Simple example of updating or adding a contact:

cordial.contact({
 'fname': 'Mark',
 'age': 32,
 'channels': {
   'email': {
     'address': 'mark@example.com',
     'subscribeStatus': 'subscribed'
     }
   },
 'platinum': true
})

The use of subscribeStatus key is situational and may not be necessary for all contact creation and update calls.

For example, if during the checkout process a new contact chooses not to receive promotional emails, it is not necessary to explicitly set their subscribe status to "unsubscribed", being that as a new contact without prior subscriptions, their subscribe status is initially set to "none". The best way to accomplish this is to leave the subscribeStatus key out of the call entirely.

If, however, the contact indicates by checking a box (or some other way) that they would like to receive promotional emails, the subscribeStatus key with the value of "subscribed" should be passed as demonstrated below.

var customer_data = {};
customer_data.channels = {};
customer_data.channels.email = {};
customer_data.channels.email.address = 'mark@example.com';
if(your_logic_for_box_checked){
  customer_data.channels.email.subscribeStatus = 'subscribed';
}
cordial.contact(customer_data);
}

An example of using the forceSubscribe parameter to update a contact's subscribe status to subscribed if currently set to unsubscribed.

cordial.contact({
    'channels.email.subscribeStatus': 'subscribed'
}, {
    forceSubscribe: {
        email: true
    },
    upsert: true
})

Simple example of updating a contact only if that contact already exists. Note: {'upsert': false} keeps a new contact record from being created and is treated only as an update to an existing contact.

cordial.contact({ 
   'fname': 'Mark',
   'age': 32,
   'platinum': true
   },
   {'upsert': false}
)

Three examples of working with arrays.

cordial.contact({ 
   'some_array': {'add': ['apple']},
   'second_array': {'remove': ['apple']},
   'third_array': ['apple', 'orange']
   }
)

cordial.event() - Tracking Custom Events

Track an event by calling cordial.event with the event name and optional properties object.

cordial.event('eventName',propertiesObject)

Example:

cordial.event('browse',{
    'category': 'skis',
    'product': 'Rossignol Sin 7 SKIS 2015'
})

In the example above, a custom event called "browse" will be tracked and added to the contactactivities collection. A custom event may be named whatever you like, barring the following reserved event names.

Reserved event names

There are named events that are already tracked by the Cordial and those names should not be used for custom event tracking. The event names that should NOT be used for custom events:

• click
• open
• message-sent
• bounce
• optout

All contactactivity records contain a timestamp and the contact ID of the user.

propertiesObject

You may also optionally pass an object of key/value pairs describing the event.

Searching & Segmenting on custom events

These key/value pairs can be used for filtering the browse events. For example, an Audience Rule can be created to query all contacts who were tracked for a 'browse' event. Or, a filter can be added to the rule that queries all contacts who were tracked for a 'browse' event where the category is 'skis'.

cordial.cartitem() - Tracking Cart Items

Each contact has a Cart attribute associated with their profile. Calling cordial.cartitem() will add or remove items to a contact's cart. The productID is the primary key for the cart item. Adding items with the same productID will increment the quantity for that item versus add new item records.

Request with a single cartitem

The add and remove actions support a single object of cartitems.

cordial.cartitem('add',cartitemObject)

Example:

cordial.cartitem('add', {
   'productID': '1234',
   'sku':'1234-red',
   'category':'shirts',
   'name':'Red Shirt',
   'images':['image1.jpg','image2.jpg'],
   'description':'',
   'qty': 1, 
   'itemPrice': 10.20,
   'url':'',
   'attr': {
       'manufacturer': 'ExampleCo',
       'size': 'L'
   },
   'properties': {
       'custom_key': 'custom_value'
   }
})

cordial.cartitem('remove', {
   'productID': '1234'
})

Request with an array of cartitems 

The add action supports an array of cartitems.

cordial.cartitem('add', [{
   'productID': '1234',
   'sku': '1234-red',
   'category': 'shirts',
   'name': 'Red Shirt',
   'images': [],
   'description': '',
   'qty': 1,
   'itemPrice': 10.20,
   'url': '',
   'attr': {
     'manufacturer': 'ExampleCo',
     'size': 'L'
   }
}, {
   'productID': '5678',
   'sku': '5678-red',
   'category': 'pants',
   'name': 'Red Pants',
   'images': [],
   'description': '',
   'qty': 1,
   'itemPrice': 10.20,
   'url': '',
   'attr': {
     'manufacturer': 'ExampleCo',
     'size': 'L'
   }
}])

Action

There are 2 possible actions: 'add' or 'remove'.

• 'add' - will add a new cart item record or increment the quantity of an existing record.
• 'remove' - will remove an existing cart item.

Cart Item Object

Cart Object

Below is an example of how the data is stored within a contact's profile. Note, the cartitem amount is automatically calculated (itemPrice x qty) and cart totalAmount is automatically calculated as the sum of all cart item amounts.

'cart': {
      'totalAmount': 32.97,
      'lm': '2015-10-22T20:43:38.373Z',
      'cartitems': [
        {
          'productID': 'GreenPlaid123123',
          'name': 'Green Plaid',
          'sku': '111222333',
          'category': 'Shirts',
          'qty': 2,
          'images':['image1,jpg','image2.jpg'],
          'itemPrice': 10.99,
          'amount': 21.98,
          'description': 'Awesome shirt',
          'url': 'http://www.shirts.com/GreenPlaid123123'
        },
        {
          'productID': 'BluePlaid123123',
          'name': 'Blue Plaid',
          'sku': '111222444',
          'category': 'Shirts',
          'qty': 1,
          'itemPrice': 10.99,
          'amount': 10.99,
          'description': 'Awesome shirt',
          'url': 'http://www.shirts.com/BluePlaid123123'
        }
      ]
    }

Clearing a cart

To completely remove a cart object for a contact, use the cordial.clearcart() method. Ex: clearing a cart post-purchase.

cordial.clearcart()

cordial.order() - Tracking Purchases

Calling cordial.order() will update the order collection with a new record for the individual contact.

The add and remove actions support a single object of order items.

cordial.order('add',orderObject)

cordial.order('add',{
   'orderID': '',
   'shippingAddress': {
     'name': '',
     'address': '',
     'city': '',
     'state': '',
     'postalCode': 0,
     'country': ''
   },
   'billingAddress': {
     'name': '',
     'address': '',
     'city': '',
     'state': '',
     'postalCode': 0,
     'country': ''
   },
   'items': [
     {
       'productID': '',
       'sku': '',
       'category': '',
       'name': '',
       'qty': 0,
       'tags': ['tag1', 'tag2'],
       'itemPrice': 0.0,
       'salePrice': 0.0,
       'url':'',
       'attr': {
         'color': '',
         'size': ''
       }
     }
   ],
   'tax': 0.0,
   'shippingAndHandling': 0.0
})

Adding Order and Item Properties

The properties key can be used to insert additional custom order and item values. Values added using the properties key will become available for segmenting audiences using the Audience Builder (searching of nested order properties must be enabled in your account first). If having searchable order properties is a requirement for your account, please use the properties key in place of the attr key.

Example of adding order properties:

cordial.order('add', {
  'orderID':'',
  'items': [{
    'productID': '',
    'name': '',
    'category': '',
    'sku': '',
    'tags': ['tag1', 'tag2']
  }],
  'properties': {
    'order_discount': 1.00
  }
})

Example of adding order item properties:

cordial.order('add', {
  'orderID':'',
  'items': [{
    'productID': '',
    'name': '',
    'category': '',
    'sku': '',
    'tags': ['tag1', 'tag2'],
    'properties': {
      'brands': ['brand1', 'brand2']
    }
  }]
})

Action

There are 2 possible actions: 'add' or 'remove'

• 'add' - will add a new order record.
• 'remove' - will remove an existing order record

Order Object

Tracking Google AdWords, traffic source or other URL query string values

If t.setAttribute("data-cordial-source-keys", "$key"); is set, the track script will pull values out of the URL query string for any of the keys defined. The values will be stored in cookies and will be available to the Cordial track script as variables.

For example: If you were using an ad service to drive traffic, your URLs may look like:

http://mydomain.com?utm_source=google&utm_campaign=1234.

Tell the embedded script which URL query string parameters to listen for:

t.setAttribute("data-cordial-source-keys", "utm_source,utm_campaign");

The listener will now look for those query string keys and store their values in a cookie on your domain. The values are automatically available to you as variables. For example:

cordial.utm_source
cordial.utm_campaign

You can tell the script to listen for specific query parameters, as long as the keys in the URL are alphanumerical. The keys may also contain: "-" and "_".  Multiple keys should be comma separated.

You can use the variables in a number of ways, but a common use case would be to pass them as attribute values. The following example assumes an account with attributes called "source" and "campaign". When adding or updating a contact, you could pass the following variables.

cordial.contact({
   "source":cordial.utm_source,
   "campaign":cordial.utm_campaign
})

If the contact arrived at the page from the URL above, their profile would include the following:

"source": "google",
"campaign": "1234",
...

cordial.forget() - Clearing cookies (useful for a logout event)

Calling cordial.forget() will clear the cookies for a currently identified session.

cordial.forget()