JavaScript API for identification and tracking

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.

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>
  klaviyo.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 klaviyo 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>
//Identify a user
  klaviyo.identify({
    '$email' : '[email protected]',
    '$first_name' : 'George',
    '$last_name' : 'Washington',
    'Birth Year' : 1732
  });

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

//Optionally include a callback function
  function onIdentifyCompleteCallback () {
		klaviyo.push(["track", "Custom Event"]);
  }

  const identityProperties = {
  	'$email' : '[email protected]'
  }
// Identify user then send custom event for the identified user
  klaviyo.identify(identityProperties, onIdentifyCompleteCallback);
</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>
  // Identifying a person and tracking special Klaviyo properties.
  klaviyo.identify({
    '$email' : '[email protected]',
    '$first_name' : 'Thomas',
    '$last_name' : 'Jefferson'
  });

  // Adding custom properties. Note that Klaviyo understands different data types.
  klaviyo.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 only tracks events when a user is identified

Klaviyo will only save a track event when we know what profile to record it to. If you're having trouble tracking events, make sure you're making an identify call beforehand.

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>
  // Track presidential elections
  klaviyo.push(['track', 'Elected President', {
    'PreviouslyVicePresident' : true,
    'YearElected' : 1801,
    'VicePresidents' : ['Aaron Burr', 'George Clinton']
  }]);

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