How can we help?

✪ Embedded JavaScript Listener v2 features


The second iteration of the embedded JavaScript listener (JS listener) introduces a number of noteworthy enhancements.

Notable updates include the use of browser ID instead of contact ID for contact activity attribution; support for cross-domain contact identification and event tracking; inclusion of order and cart item calls into to the anonymous activities collection; and bundling of contact identify, create, and update operations into one call.

Additionally, several infrastructure enhancements were made resulting in significant improvements to the security and stability of the JS listener script.

The Embedded JavaScript Listener v2 article covers installation instructions and provides script parameter use case examples.

Script parameters

Although much of the core functionality remains unchanged, there are notable functional and structural differences between JS listener v1 and v2 script parameters. The following comparison table illustrates the differences.

Parameter JS Listener V1 JS Listener V2 Description
identify cordial.identify(pk|cid) NA Identify a contact.
contact, options) crdl('contact', auth_data, contact_data) Identify, update or create a contact.
event cordial.event('name', data) crdl('event', 'action_name', data) Send event, order and cart item calls to Cordial.
order cordial.order(orderData) crdl('order', order_data) Send order data to the orders collection in Cordial.
cart cordial.cart('clear') crdl('cart', 'clear') Clear cart contents.
cartitem cordial.cartitem('action', data) crdl('cartitem', 'action', cart_data) Add, remove and track cart items.
forget cordial.forget() crdl('forget') Clear current browsing session and assign a new browser ID.
connect NA crdl('connect', account_key, {config}); Configure account connection.
param store t.setAttribute("data-cordial-source-keys", "utm_source"); crdl('param-store', 'utm_source') Store URL strings as variables.

Introduction to browser IDs

JS listener v2 introduces the use of browser IDs as a way of attributing and referencing contact activity. This is a departure from the previous version of the script, where the primary contact ID was used in a similar manner.

Browser ID is a randomly generated string that is assigned at the beginning of a browsing session. All contact activity thereafter is attributed to the browser ID for future reference. Once the contact becomes identified through sign up, log in, or a similar event, all browser ID attributed activity is copied into the contact's profile.

Browser ID is perishable and does not serve as the primary contact key.

If the contact is not immediately identified, their activity will be stored in the anonymous history collection. For contact identifications that take place at a later time, JS listener v2 will search the anonymous history collection using the initially assigned browser ID and copy matching activity to the now identified contact's profile.

Cross-domain contact identification

JS listener v2 supports cross-domain contact identification and event tracking, a feature not supported in JS listener v1 without custom-built solutions. Unlike contact ID, browser ID is bound to the contact's browser and persists across multiple domain names, while the script continues attributing event, order, and cart activity to the same browser ID.

Whether the contact has been identified prior to being redirected to a different domain or is identified while at the redirected domain, the script will retain access to browser ID attributed activity, starting from the moment the browsing session began on a JS listener v2 enabled website.

This solves the previously reported issue where contacts' cart data did not always carry over from one domain to the next. The result is a more seamless browsing experience without interruptions to contacts' interaction with the brand.

Note: The above is true provided each visited domain contains the same JS listener v2 configuration snippet including the same Cordial account key, trackUrl, and conectURL.


Although cordial.identify() method is no longer used in JS listener v2, contact identification still takes place within the crdl(contact) method when the primary contact key value (email address for example) is passed as authentication data. The difference is that crdl(contact) discretely validates authentication data, giving JS listener v2 the opportunity to copy browser ID attributed activity to contact's profile.

The crdl(contact) has become a multi-function method that can handle calls to identify, create and update contact data.

Contact creation

A new contact will be created when previously unrecorded authentication data is passed with crdl(contact). Assuming is not an existing contact, the following example will create a new contact and the current session browser ID will be assigned to them:

var auth_data = {
  email: ''
var contact_data = { 
  	  'email': { 
  'first_name': 'Joy', 
  'age': '32',
  'platinum': true
crdl('contact', auth_data, contact_data);

If, on the other hand, was identified as an existing contact, the above example would update Joy's profile without creating a new contact entry.

When no authentication data is passed, JS listener v2 will use the current session browser ID to search the anonymous history collection. In the event no existing records match the same browser ID, a new record will be added to the anonymous history collection. Should a match be found, the passed data will be used to update the existing anonymous history record.

Because crdl(contact) is able to identify, update or create a contact, the use of "upsert" parameter is no longer necessary to distinguish between updating or adding a contact.


JS listener v2 expands anonymous event data collection to now include event, order, and cart item calls. All anonymous event activity will be attributed to the session browser ID and stored in the anonymous history collection, where it will remain until the contact is identified, or 30 days have passed since the contact was last active.


Browser ID can be disassociated from the current browsing session by using the crdl(forget) method. This is the recommended way of handling user logout events.

A common scenario where this may be useful involves keeping browsing sessions and browser ID attributed activity between two users on the same computer separate from one another. When one user logs out, calling crdl(forget) will result in a new browser ID for use by the next user.

Expiring a cookie is another way to disassociate and refresh the browser ID after a desired period of time has passed. This can be accomplished by specifying cookie expiration time in days using the cookieLife parameter within the JS listener v2 base installation script. The default cookie life is set to 365 days.

cookieLife: 365

Cookie expiration does not impact the collected anonymous event data, which is stored in the Cordial platform.

Storing parameters

The crdl(param-store) method will store URL string values such as utm_source and utm_campaign for later retrieval as parameters. This serves as a way to identify sources of traffic and using collected data to report on purchase attributions, campaign effectiveness, and a variety of other analytics.

This method operates in the same manner as t.setAttribute(data-cordial-source-keys) does in JS listener v1. A notable difference is that JS listener v2 handles Crdl(param-store) as a method call whereas t.setAttribute is configured within the JS listener v1 base installation script.



Please sign in to leave a comment.