JavaScript API for identification and tracking

❗️

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).

Add the Klaviyo snippet

To start tracking people, add the snippet below to your website's main template so it will automatically be added to every page on your website. If you have a developer that will add this script to your website, you can send them a link to this guide.

📘

This guide uses the legacy _learnq object

We recommend using the new Klaviyo object, which offers robust support for callbacks and promises. Check out this introduction to the Klaviyo object to get started!

Adjust the code snippet based on your business needs as outlined.

• Ecommerce businesses: remove the four lines with the identify call. The identify call is useful for pages where your users' emails have already been collected and can be pushed to a cookie for tracking. Your storefront pages, which likely collect user signups, do not require this call.
• Websites or web apps that require logins: replace the {{ email }} placeholder email with the appropriate template variable that has the logged in user's email address.

We suggest putting the Klaviyo code at or near the bottom of your site template. If you use Google Analytics or other third party services, you can place the Klaviyo code directly above or below that.

// Replace "PUBLIC_API_KEY" with your real API key.
<script
  async type="text/javascript"
  src="//static.klaviyo.com/onsite/js/klaviyo.js?company_id=PUBLIC_API_KEY"
></script>

<script>
  var _learnq = _learnq || [];
  _learnq.push(['identify', {
    // Change the line below to dynamically print the user's email.
    '$email' : '{{ email }}'
  }]);
</script>

You might be wondering, "How does using Klaviyo affect my site's performance?" The answer is Klaviyo doesn't affect your website's performance at all. Our code only loads once the rest of your website has finished loading. In addition, Klaviyo tells browsers to cache our JavaScript so your visitors often don't even need to download our JavaScript every time switch pages.

API basics

To make calls to the Klaviyo API and store information about people, you'll use the _learnq object that's automatically added by the Klaviyo script.

To make an API call, Klaviyo uses a special syntax that allows your API calls to work even when our script hasn't loaded on the page yet. You'll create an array where the first value is the name of the method you want to call and any subsequent values are arguments to pass to that method.

<script>
  var _learnq = _learnq || [];

//Optionally include a callback function
  function onIdentifyCompleteCallback () {
    _learnq.track("An Event");
  }

  _learnq.identify(identityProperties, undefined, undefined, onIdentifyCompleteCallback);

//Identify a user
  _learnq.push(['identify', {
    '$email' : '[email protected]',
    '$first_name' : 'George',
    '$last_name' : 'Washington',
    'Birth Year' : 1732
  }]);

//Track events for an identified user
  _learnq.push(['track', 'Elected President', {
    'Country' : 'United States'
  }]);
</script>

Identify people

The identify method allows you to identify and set properties on an individual. This method accepts a dictionary or hash of properties. When you identify someone, you must include either their email address with the $email key, or, if you have SMS-only contacts, their phone number with the $phone_number key.

Once you've included at least one of those identifiers, you're free to add any custom properties you want. Custom properties are useful for tracking facts about individuals. In Klaviyo, you can then create segments of people based on those properties. For instance, you might want to track an individual's plan type or sign up date. Klaviyo will also understand different data types you use, so feel free to use numbers, booleans and dates.

Klaviyo has a few special properties that are used to display information about people. These are: $first_name, $last_name, $phone_number, $title and $organization.

In addition to properties you track, Klaviyo will automatically determine what website each person was first referred from for attribution tracking and a person's location based on where they access your website.

<script>
  var _learnq = _learnq || [];

  // Identifying a person and tracking special Klaviyo properties.
  _learnq.push(['identify', {
    '$email' : '[email protected]',
    '$first_name' : 'Thomas',
    '$last_name' : 'Jefferson'
  }]);

  // Adding custom properties. Note that Klaviyo understands different data types.
  _learnq.push(['identify', {
    'Plan' : 'Free Trial',
    'SignUpDate' : '2016-01-27 12:10:05',
    'HasFilledOutProfile' : false
  }]);
</script>

Track events and actions

The track method allows you to record events and actions people take on your website. This method accepts a string which is the name you give to that event. This method also accepts an optional dictionary or hash of properties associated with that event.

For example, you could track when someone purchases an item and include information on the purchase price and what items they bought. If you have an application where people have profiles you could track when someone fills out their profile. If you are planning on a full ecommerce integration for your platform, check out our guide Integrate a platform without a pre-built Klaviyo integration.

Klaviyo's event tracking and analytics are very flexible, so you can customize them to keep track of what's important to your business. Our track method also understands different data types, so you can use numbers, booleans and dates and we'll create intelligent charts and graphs based on the data you send.

<script>
  var _learnq = _learnq || [];

  // Track presidential elections
  _learnq.push(['track', 'Elected President', {
    'PreviouslyVicePresident' : true,
    'YearElected' : 1801,
    'VicePresidents' : ['Aaron Burr', 'George Clinton']
  }]);

  // Track a simpler version.
  _learnq.push(['track', 'Elected President']);
</script>