Embedded JavaScript Listener

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.sub_domain.example.com';
        t.setAttribute("data-cordial-track-key", "$accountkey");
        t.setAttribute("data-cordial-url", d);
        t.setAttribute("data-auto-track", false);
        t.src = '//'+d+'/track.js';
        t.async = true;
        t.onload = 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.sub_domain.example.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.

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 contact 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, an anonymous 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 anonymous 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

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

The cordial.identify() method accepts either contactID or the primary key value (email address is the Cordial default primary key) for the contact.

Sets the contact identifier for the targeted user in the user's session cookie for use by any subsequent calls to update or track contacts.

This is useful for assigning a contact ID when the user is not referred through the system tracked link. Ex: After a login event where the contact ID becomes known.

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);
}

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 properties. If used, this parameter replaces the attr key. Item level values added using the properties key will become available for searching and segmenting audiences using the Audience Builder (searching of nested order properties must be enabled in your account first).

Example of adding order properties:

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

Example of adding order item properties:

cordial.order('add', {
  'orderID':'',
  'items': [{
    'productID': '',
    'name': '',
    'category': '',
    'sku': '',
    '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()