Introduction to the Klaviyo object
Learn more about the new Klaviyo JavaScript object, which offers full support for callbacks and promises.
What is the klaviyo
object?
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
klaviyo
objectTo use the klaviyo object immediately on page load, we recommend manually installing the snippet on your site. This snippet would exist in addition to Klaviyo's onsite script. 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.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
- Parameters -
- identify
- Parameters -
properties: Object
,callback?: Function
- Return type - object
- Parameters -
- track
- Parameters -
event: string
,properties?: Object
,callback?: Function
- Return type - boolean
- Parameters -
- trackViewedItem
- Parameters -
item: Object
,callback?: Function
- Return type - none
- Parameters -
- account
- Parameters -
account_id?: string
,callback?: Function
If anaccount_id
string is provided, it will set the account id. - Return type - string
- Parameters -
- cookieDomain
- Parameters -
cookieDomain?: string
,callback?: Function
If acookieDomain
string is provided, it will set the cookie domain. - Return type - string
- Parameters -
- isIdentified
- Parameters -
callback?: Function
- Return type - boolean
- Parameters -
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))
returnsNone
-
klaviyo.identify({})
returnsPromise<Object>
-
klaviyo.identify({}, (result) => console.log(“Identify result “ + result))
returnsPromise<Object>
Update _learnq
code to use klaviyo
_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
?
_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.
Updated 4 months ago