Documentation / Product / Features / Lytics JavaScript Tag

Migrating to JS Tag Version 3

Lytics kept backwards compatibility and future scalability in mind when designing version 3 of our core JavaScript SDK. As such, the vast majority of legacy approaches against version 2 of the Lytics JavaScript (JS) tag are compatible with version 3. Only alterations that fixed long-standing bugs or flawed architecture represent backwards incompatible changes. This document will outline specifically what needs to be updated to migrate to version 3.

How do I know what version I am currently on?

This migration guide assumes you are on version 2.0 or greater. You can easily check which version you are on. If there are any concerns, please check with your Account Manager for verification.

Backwards Incompatible Changes

Core Tag Wrapper

Because many of the changes represent new or altered functionality, migration will require adding a new tag to all of your web properties. A variety of performance and bug-related fixes have been corrected in this new snippet as well as the addition of many more configuration options and controls. Our tag installation instructions within the app contain both your old and new snippets for convenience.

Getting the Anonymous ID

In version 2 you could gain access to a user's anonymous ID (_uid or seerid) created by Lytics by simply calling the getid method. This represented an issue for many customers in the form of a race condition. Because assigning the ID is an asynchronous process and may require calling an API to check for a third-party cookie, it was possible to either get no ID or an invalid ID from that call.

Version 3 corrects this by leveraging callbacks. You simply pass a callback function to the same getid method and once the request completes, your function will be passed the correct ID. See version 2 vs. 3 code samples below:

// version 2
var myid = jstag.getid();

console.log(myid);
// version 3
var myfunction = function(id) {
    console.log(id);
}

jstag.getid(myfunction);

Audience Membership Cookie Storage

Upon loading a visitor's profile, version 2 would store all audiences that the visitor was a member of as a cookie named ly_segs. This enabled a small subset of use cases related to low latency but introduced a variety of issues with maximum cookie size, outdated audience membership, etc.

Version 3 stores the same data in localStorage. This is a much more efficient and scalable solution with virtually no downsides to performance from a customer standpoint. In addition, an optional integration will be released in the near future to write the same information to a cookie if desired.

// version 2
function getCookie(name) {
    var v = document.cookie.match('(^|;) ?' + name + '=([^;]*)(;|$)');
    return v ? v[2] : null;
}

var audiences;
var ckieValue = unescape(getCookie('ly_segs')); // the raw cookie value

try {
  audiences = JSON.parse(ckieValue);
}
catch(error) {
  console.error(error);
}

console.log(audiences);

// sample output
{
  "audience1": "audience1",
  "audience2": "audience2"
}
// version 3
var audiences;
try {
  audiences = JSON.parse(localStorage.lytics_segments);
}
catch(error) {
  console.error(error);
}

Calling lio.data

In version 2 it was somewhat common to access the visitor's profile by calling lio.data. This represents various issues around ensuring the entity has been loaded. Again, because accessing the visitor’s profile is an asynchronous action, it inherently needs to be leveraged with a callback.

In version 3 the method for initializing callbacks is vastly improved and should be used in all cases, though the version 2 method for creating and managing callbacks is backwards compatible.

// version 2
var profile = lio.data;

console.log(profile.segments);
// version 3
var myfunction = function(p){
    console.log(p.data.user.segments);
}

jstag.call('entityReady', myfunction)