Set up API-based website activity events

❗️

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

While our prebuilt integrations offer some common on site events by default, you may have other event information that you'd like to track. This guide will review some examples of additional data you might want to track which can enhance your marketing goals.

The first question to ask when you consider tracking additional data is "what is the marketing or reporting goal of tracking this data?" If there is a clear answer, it would make sense to track it! If not, it may just add clutter to your Klaviyo account. Remember, while more data can be better, useless data may add unneeded cognitive overhead and detract from the user-friendliness of your account.

This guide will provide examples of how to implement the following common on site activity events:

• Referrals & Shares
  • Send to a Friend (product, article, page)
  • Refer a Friend (referral code)
• Website activity
  • Viewed Category
  • Searched Site
  • Clicked Banner

The level of detailed data you send to Klaviyo within these web activity events will determine how you can filter and segment based on these events in Klaviyo. To understand how data must be structured so that key event details are available for segmentation, check out our guide on segment conditions.

The snippets in this guide use example data. You will need to update the values of the JSON properties in these snippets such that they dynamically pull from the relevant information needed for that property.

If you have questions about customer integrations check out our Custom integration FAQ.

JavaScript requests

To enable our JavaScript API and the ability to push events and profile properties to Klaviyo from your site, add the following snippet so it appears on every page on your website. (Often the end of the footer is a good place to add this.) Make sure to replace PUBLIC_API_KEY with your Klaviyo account's 6 character Public API Key:

<script type="application/javascript" async src="https://static.klaviyo.com/onsite/js/klaviyo.js?company_id=PUBLIC_API_KEY"></script>

Server-side requests

For sending server-side events and profile properties, you should make a Track or Identify request to our server-side API. We have libraries available for Python, Ruby, and PHP, but in a general sense the API just requires making an HTTP GET request with a base64 encoded JSON payload.

You'll want to send server-side data to Klaviyo in one of two ways: real-time or batch.

• Real-time: requests are made as soon as an action is taken
• Batch: this script that will run at least once an hour, sending all events from the past hour to your Klaviyo account

Key things to be aware of when tracking server-side events:

• Make sure to replace PUBLIC_API_KEY with your public API key
• The $event_id should be a unique identifier for the order (e.g. Order ID)
• If the same combination of event and $event_id are sent more than once, we will skip all tracked events after the first with the same combination
• time is a special property that should be a UNIX timestamp of the order date and time

Server-side events should include any information about the person who took the action (e.g. first name) as profile properties in the customer_properties dictionary and any information specific to the event itself (eg. a list of ordered items) in the properties dictionary.

Shares and referrals

Shares and referrals can be leveraged by your business to gain new customers and increase brand awareness.

Share an item

There are two types of events you can track when someone shares something (a product, an article, a page, etc.) with another person:

• An event for the person who sent the item
• An event per person who received the item

The first is sent using our Javascript Track API, but the second must be sent using our server-side Track API. For the sake of simplicity, we will use blog articles as an example.

Shared article event

When the article is initially shared, the Shared Article event uses our Track API to record the following information:

• The article recipient(s), identified by their email address (array of strings)
• The quantity of articles shared
• The name of the article (string)
• Article URL (string)
• Identifying picture for article (string)

Once someone enters the email address(es) of the person(s) they'd like to share with, send a Shared Article event that looks something like this:

<script type="text/javascript">
   _learnq.push(["track", "Shared Article", {
     "Recipients": ["[email protected]","[email protected]"],
     "Quantity": 2,
     "Name": "Top 10 flows for great holiday success!",
     "URL": "https://www.example.com/top-10-flows-holidays",
     "ImageURL": "https://www.example.com/top-10-flows-holidays-hero-image.png"
   }]);
</script>

Received article share event

The Received Article Share event is sent to people who aren’t cookied on the front-end at the time of this action, so this event requires a server-side Track request for each email in the Shared Article event.

📘

Info

To make sure the Received Article Share events are recorded separately, each call needs to have a different $event_id. There are many ways to generate a unique $event_id; one method is to base64 encode the email address of the recipient and concatenate it with the current UNIX timestamp, as shown below.

{
  "token": "PUBLIC_API_KEY",
  "event": "Received Article Share",
  "customer_properties": {
    "$email": "[email protected]"
  },
  "properties": {
    "$event_id": "ZW1haWwub24ubGlzdEBlbWFpbC5jb20=_1500922636",
    "SharerName": "John Smith",
    "SharerEmail": "[email protected]",
    "Name": "Top 10 flows for great holiday success!",
    "URL": "https://www.example.com/top-10-flows-holidays",
    "ImageURL": "https://www.example.com/top-10-flows-holidays-hero-image.png"
  },
  "time": 1500922636
}

Referrals

If you’d like to report on who’s referred your brand to a friend or send a thank you note to the person who referred you, you can track Referred Friend and Referred by Friend events. Similar to when someone shares content with a friend, you’ll need to track two kinds of events:

• An event for the person who referred a friend, sent via the JavaScript Track API
• An event per friend referred, sent via the server-side Track API

As part of a server-side Track request, you can also send profile properties, which may be useful in this case if a person can use a referral code to gain some kind of perk with your brand.

Referred friend event

When the referral is initially made, the Referred Friend event uses our Track API to record the following information:

• The article recipient(s), identified by their email address (array of strings)
• The quantity of recipients

See the code block below for an example of what the Referred Friend event looks like:

<script type="text/javascript">
   _learnq.push(["track", "Referred Friend", {
     "Recipients": ["[email protected]","[email protected]"],
     "Quantity": 2
   }]);
 </script>

Referred by friend event

At the same time, send something like the following payload for each referred person:

{
  "token": "PUBLIC_API_KEY",
  "event": "Referred by Friend",
  "customer_properties": {
    "$email": "[email protected]",
    "ReferrerName": "John Smith",
    "ReferrerEmail": "[email protected]",
    "ReferrerCode": "123abc456def"
  },
  "properties": {
    "$event_id": "ZW1haWwub24ubGlzdEBlbWFpbC5jb20=_1500922636",
  },
  "time": 1500922636
}

You can then use the ReferrerCode to create unique URLs for each referral, and insert those URLs into a referral email. For example, if you had an email flow triggered by the Referred by Friend event, you could include the following block:

{{ event|lookup:'ReferrerName'}} thought you might like this,
<a href="https://www.example.com/?referral_code={{ event|lookup:'ReferrerCode}}">click here</a> 
to find out if you do!

Website activity

In addition to our standard/recommended events like Viewed Product, people can take other actions on your website which you may want to track for targeting or reporting. Below are some common examples.

Viewed category

Similar to a Viewed Product event, the Viewed Category event allows you to capture when someone views a particular category of items, and triggers when a person lands on a category page.

This event uses our JavaScript Track API to record the following information:

• The category name (string)
• The category ID (string)
• The category image URL (string)
• The category URL (string)

See the code block below for an example of what the Viewed Category event looks like:

<script type="text/javascript">
   var _learnq = _learnq || [];
   _learnq.push(["track", "Viewed Category",{
     "CategoryName": "Fantasy Books",
     "CategoryID": "01",
     "ImageURL": "http://www.example.com/path/to/category/hero/image.png",
     "URL": "http://www.example.com/path/to/category"
   }]);
</script>

Searched site

The Searched Site event allows you to track search terms users look for on your site. This event also allows you to track any suggestions your site made based off of the user’s initial search term, such as correcting their spelling or closest match.

This event should be triggered when someone submits a search query, and it uses our JavaScript Track API to record the following information:

• The exact term the user searched for (string)
• The autocorrected term (string)
• The number of results returned (integer)

See the code block below for an example of what the Searched Site event looks like:

<script type="text/javascript">
   var _learnq = _learnq || [];
   _learnq.push(["track", "Searched Site",{
     "SearchTerm": "Fantasty Boks",
     "SearchTerm (autocorrected)": "Fantasy Books",
     "ReturnedResults": 54
   }]);
</script>

Clicked banner

The Clicked Banner event is used to track when someone clicks a banner on your site, allowing you to better target the users based on their click activity. This event can be used for any kind of banner as long as the user will be directed to a specific destination.

📘

Info

Before implementing this event, make sure there’s a clear reason to track it, such as a strong marketing or reporting goal. Otherwise, it may add unnecessary clutter to your Klaviyo account.

The Clicked Banner event uses our JavaScript Track API to record the following information:

• The URL the user was at when they clicked the banner (string)
• The URL they navigated to by clicking on the banner (string)
• The banner title (string)

The example below is specifically for banner ads, but this can be extrapolated to other use-cases as well:

<script type="text/javascript">
   var _learnq = _learnq || [];
   _learnq.push(["track", "Clicked Banner",{
     "SourceURL": "https://www.example.com/home",
     "DestinationURL": "https://www.example.com/black-friday-deals",
     "BannerTitle": "Check out these awesome Black Friday sales!"
   }]);
</script>

Additional resources

• Custom integration FAQ
• Track & Identify API documentation
• Understanding segment conditions