❗️

This guide refers to Klaviyo's v1/v2 legacy APIs.

We are in the process of updating these guides, please check back later! For more information about the differences between legacy and new APIs, check out the comparison chart and [new API overview] (ref:api_overview).

What is the klaviyo object?

The new klaviyo object replaces the legacy _learnq and klOnsite objects. These JavaScript objects offer a shorthand way to interact with our APIs and send events into Klaviyo with event tracking. The klaviyo object offers robust support for asynchronous JavaScript implementations with callbacks and promises. It also supports existing klOnsite functionality, such as opening sign up forms with custom triggers and executing end-user provided callbacks, which provide better control over when forms are displayed.

Klaviyo.js, also known as Klaviyo’s “Active on Site” JavaScript, automatically supports the klaviyo object. If you have enabled an integration with your Klaviyo account or installed Klaviyo.js manually, you will be able to initiate klaviyo to listen for relevant calls.

How to load the klaviyo object

To use the klaviyo object immediately on page load, we recommend manually installing the snippet on your site. The klaviyo object only needs to be loaded once per page.

To load the klaviyo object:

!function(){if(!window.klaviyo){window._klOnsite=window._klOnsite||[];try{window.klaviyo=new Proxy({},{get:function(n,i){return"push"===i?function(){var n;(n=window._klOnsite).push.apply(n,arguments)}:function(){for(var n=arguments.length,o=new Array(n),w=0;w<n;w++)o[w]=arguments[w];var t="function"==typeof o[o.length-1]?o.pop():void 0,e=new Promise((function(n){window._klOnsite.push([i].concat(o,[function(i){t&&t(i),n(i)}]))}));return e}}})}catch(n){window.klaviyo=window.klaviyo||[],window.klaviyo.push=function(){var n;(n=window._klOnsite).push.apply(n,arguments)}}}}();

Callback support

Klaviyo offers full support for callbacks, giving you more control over the order in which your functions are invoked. Callbacks will be called with a return value.

For example, to identify a cookied user without a callback using klaviyo:

klaviyo.identify({});

With the klaviyo object, you can now pass in a callback to the identify call. This allows the customer to be identified as well as track any onsite event without having to reload the page (ex: viewed product):

function myCallback() {
  var item = {
    "ProductName": item.ProductName,
    "ProductID": item.ProductID,
    "SKU": item.SKU,
    "Categories": item.Categories,
    "ImageURL": item.ImageURL,
    "URL": item.URL,
    "Brand": item.Brand,
    "Price": item.Price,
    "CompareAtPrice": item.CompareAtPrice
  };
  klaviyo.push(["track", "Viewed Product", item]);
}

klaviyo.identify({
  '$email' : '[email protected]',
  '$first_name' : 'Thomas',
  '$last_name' : 'Jefferson'
}, myCallback);

Promise support

The klaviyo object also supports promises, which offer a cleaner approach to resolving asynchronous requests. This option eliminates the potential complexity of nested callbacks and can simplify your code. Promises will be resolved with a return value.

For example, to return a promise when an identify call has been completed:

klaviyo.identify({}).then(() => console.log('Identify has been completed'));

Supported methods

The klaviyo object supports the following methods. Optional parameters are represented by a ?.

• openForm
  • Parameters - formId: string, callback?: Function
  • Return type - none
• identify
  • Parameters - properties: Object, callback?: Function
  • Return type - object
• track
  • Parameters - event: string, properties?: Object, callback?: Function
  • Return type - boolean
• trackViewedItem
  • Parameters - item: Object, callback?: Function
  • Return type - none
• account
  • Parameters - account_id?: string, callback?: Function
    If an account_id string is provided, it will set the account id.
  • Return type - string
• cookieDomain
  • Parameters - cookieDomain?: string, callback?: Function
    If a cookieDomain string is provided, it will set the cookie domain.
  • Return type - string
• isIdentified
  • Parameters - callback?: Function
  • Return type - boolean

Return values:

klaviyo.push([‘method’, ...params, callback]) returns None, and instead executes a callback with a return type.

klaviyo.method(...params, callback) returns a Promise that resolves to a return type.

Examples:

• klaviyo.push([‘identify’, {}, (result) => console.log(“Identify result “ + result)) returns None

• klaviyo.identify({}) returns Promise<Object>

• klaviyo.identify({}, (result) => console.log(“Identify result “ + result)) returns Promise<Object>

Update _learnq code to use klaviyo

If you have implemented custom code using the _learnq object, we recommend that you update your code to use klaviyo.

You can quickly update instances of the legacy learnq.push to use the new klaviyo.push.

For example:
_learnq.push([‘identify’,{}]);
becomes
klaviyo.push(['identify', {}]);

Can I still use _learnq and klOnsite?

We will continue to support the functionality of legacy objects such as _learnq and klOnsite, so that sites using them will not break and you will have time to adopt the new klaviyo object.

However, we highly recommend moving to klaviyo as soon as possible to utilize its additional features and broad support for callbacks, promises, and functions.