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>
t.src
URL. The appropriate protocol used by your website will be populated by default when only //
is added before the track URL.Script Attributes
* Required
Attribute | Description | Type | Default |
---|---|---|---|
* data-cordial-track-key | Replace $accountKey with the account key value for your account. Read more |
valid account key | none |
* data-cordial-url | See domain below. | valid domain | none |
* data-auto-track | When set to true, a pageView event is captured on each page load (impression). | boolean | false |
data-base-domain | Your base domain where cookies will be stored. Necessary for allowing cookies to be shared across subdomains such as shop.yourbasedomain.com. | valid domain | none |
* t.src | Path of the track.js file | URL | //track.cordial.io/track.js - without the web protocol |
t.async | When set to true, the script will load asynchronously and will not adversely affect your page load speed. | boolean | true |
t.onload | Useful when t.async is true and initiating custom functions, which must only be fired when the track.js file is completely loaded. | function name | none |
t.setAttribute("data-cordial-source-keys", "$key"); | If set, the track script will pull values out of the URL query string for any of the keys defined. Useful for source tracking. Read more |
Key name or an array of key names | none |
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.
www.
subdomain. Adding www.
before your base domain will cause it to be treated as a subdomain, and cookies stored under this subdomain will not be accessible to other subdomains such as shop.yourbasedomain.com.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
Key | Description | Type | Required |
---|---|---|---|
productID | Item Identifier | string | Required |
sku | Item Number | string | Required |
category | Item Category | string | Required |
name | Item Name | string | Required |
description | Item description | string | Optional |
qty | Quantity in the cart | int | Optional |
itemPrice | Price per item | float | Optional |
url | Link to the item | string | Optional |
images | image names or paths | array | Optional |
attr | attribute value pairs | object | Optional |
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
Key | Description | Type | Example | Required |
---|---|---|---|---|
Order | ||||
orderID | Unique identifier assigned for the order | string | 33451 | Required |
customerID | An ID value assigned by the ecommerce or CRM system | string | abc123 | Optional |
tax | The amount of the tax | float | 22.50 | Optional |
shippingAndHandling | The amount charged for shipping and handling | float | 0.0 | Optional |
shippingAddress | name, address, city, state, postalCode, country | object | see below | Optional |
billingAddress | name, address, city, state, postalCode, country | object | see below | Optional |
items | Each object describes an item of the order | array of objects | See parameters per item object below | Optional |
Parameters per each item object. The items object is optional but if included, product ID, SKU, category, qty, and name item parameters are required. | ||||
productID | A unique identifier for the product. | string | 1234abcd | Required |
sku | The Stock Keeping Unit value for a particular item. | string | RF-WP33286-21 | Required |
category | The category given to the particular item. | string | Major Appliance | Required |
name | The name of the product | string | S22-Refrigerator | Required |
tags | Tags assigned to the item. | string | series-s2 | Optional |
qty | The quantity of this item purchased. | integer | 1 | Required |
description | Description of the product | string | Great product! | Optional |
url | Link to the product | string | http://myproduct.com | Optional |
attr | Key value pairs describing attributes of the product. Values added cannot be searched using the Audience Builder or within Smarty for personalization. | object | "size":"large", "color":"red" | Optional |
properties | Can be used in place of the attr key. Values added can be searched using the Audience Builder and within Smarty for personalization, if searching of nested order properties is enabled in the account. |
object | "size":"large", "color":"red" | Optional |
itemPrice | The item's retail price. | float | 129.95 | Optional |
Optional parameters for billingAddress and shippingAddress objects | ||||
name | The name of the person or company making the order | string | Mark Smith | Optional |
address | Defines the street address | string | 13130 Silverlake Road | Optional |
city | Defines the city | string | Hollywood | Optional |
state | Defines the state | string | CA | Optional |
postalCode | Defines the postal code | integer | 90028 | Optional |
country | Defines the country | string | USA | Optional |
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()
Comments
0 comments
Please sign in to leave a comment.