Setting Up API-based Website Activity Events

read
Last updated at:

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:

  • Wishlists
    • Added to Wishlist
    • Wishlist sharing
    • Wishlist items
  • 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 or reach out to our Support Team for help.

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 - You'll make requests as soon as an action is taken
  • Batch - You’ll write a script that will run at least once an hour to send all events that occurred in that past hour

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.

Wishlists

If you track a wishlist for customers/users of your website, here are some events you may want to consider implementing to enable different types of wishlist messaging within your Klaviyo account.

Added to Wishlist

By tracking an event for when someone adds something to their wishlist, you can send messaging about special promotions or similar products to items they’ve previously wishlisted or run a segment or report on previously wishlisted items to inform potential discounts or promotions you might want to run.

The tracking of the current wishlist for a given person should still take place on your server, but by tracking an event to Klaviyo when this action occurs you can enable the type of targeting and reporting mentioned above. An Added to Wishlist event can be sent via our Javascript Track API should look something like this:

<script type="text/javascript">
   _learnq.push(["track", "Added to Wishlist", {
     "$value": 29.98,
     "ProductName": "A Tale of Two Cities",
     "ProductID": "1112",
     "SKU": "TALEOFTWO",
     "Categories": ["Fiction", "Classics"],
     "ImageURL": "http://www.example.com/path/to/product/image2.png",
     "URL": "http://www.example.com/path/to/product2",
     "Price": 19.99,
     "Quantity": 1
   }]);
</script>

Wishlist Sharing

When someone shares their wishlist, there are two types of events that you will probably want to generate:

  • one event for the person who shared their wishlist, and
  • one event per person with whom they shared it

Once someone enters the email address(es) with whom they’d like to share their wishlist, send a Shared Wishlist event that looks something like this:

<script type="text/javascript">
   _learnq.push(["track", "Shared Wishlist", {
     "Recipients": ["email.on.list@email.com","email.2.on.list@email.com"],
     "Quantity": 2,
     "Item IDs": ["1111","1112","1113"],
     "WishlistItems": [
      {
        "Name": "Item 1",
        "ID": "1111",
        "URL": "https://www.store.com/Item1",
        "ImageURL": "https://www.store.com/Item1.png"
      },
      {
        "Name": "Item 2",
        "ID": "1112",
        "URL": "https://www.store.com/Item2",
        "ImageURL": "https://www.store.com/Item2.png"
      },
      {
        "Name": "Item 3",
        "ID": "1113",
        "URL": "https://www.store.com/Item3",
        "ImageURL": "https://www.store.com/Item3.png"
      }
    ]
   }]);
</script>

While the Added to Wishlist and Shared Wishlist events can be sent using Javascript, a Received Wishlist event will require a server-side Track request for each person on the list that the person would like to share the wishlist with. Note, each $event_id will need to be different. One way to achieve this, as an example, would be to base64 encode the email address of the recipient and concatenate the current UNIX timestamp:

{
  "token": "PUBLIC_API_KEY",
  "event": "Received Wishlist",
  "customer_properties": {
    "$email": "email.on.list@email.com"
  },
  "properties": {
    "$event_id": "ZW1haWwub24ubGlzdEBlbWFpbC5jb20=_1500922636",
    "SharerName": "Person Name",
    "WishlistItems": [
      {
        "Name": "Item 1",
        "ID": "1111",
        "URL": "https://www.store.com/Item1",
        "ImageURL": "https://www.store.com/Item1.png"
      },
      {
        "Name": "Item 2",
        "ID": "1112",
        "URL": "https://www.store.com/Item2",
        "ImageURL": "https://www.store.com/Item2.png"
      },
      {
        "Name": "Item 3",
        "ID": "1113",
        "URL": "https://www.store.com/Item3",
        "ImageURL": "https://www.store.com/Item3.png"
      }
    ]
  },
  "time": 1500922636
}

Wishlist Items

If you want an up-to-date record of the items in a given person’s wishlist, you can send this to Klaviyo using our server-side Identify API and our Catalog Feed feature.

If you are using one of our pre-built integrations that already syncs your catalog, you’re all set! If not, please reach out to our Support Team who will pass along the documentation and examples for this setup. Support will also need to be notified once the setup is complete in order to activate the feed on your account.

In order to keep an up-to-date record of wishlisted items on a person’s profile, send us a server-side Identify request with a list of the IDs of the items in a person’s wishlist. This should be sent on either a periodic basis or whenever a person updates their wishlist. The IDs sent should correspond to the IDs of items in your catalog feed in Klaviyo. The payload for this request should look something like this:

{
   "token": "PUBLIC_API_KEY",
   "properties": {
     "$email": "john.smith@test.com",
     "Wishlist Item Ids": ["1111","1112","1113"],
     "Wishlist Item Names": ["Winnie the Pooh","A Tale of Two Cities","Alice in Wonderland"]
   }
}

You can use these IDs to set up a catalog lookup tag within an email template to display the items on the person’s wishlist in any campaign or flow email. You can use the names or IDs to segment based on which items are in a person’s wishlist.

Referrals and Shares

Referrals and shares can be a good source of brand awareness and lead generation. If your browsers/users are able to refer a friend to your website or send them a link to particular pages/products, it would be a good idea to implement some events around these scenarios.

Send to a friend

Similar to the idea of sharing a wishlist, there are two types of events you can track when someone sends something (a product, an article, a page, etc) to a friend:

  • one event for the person who sent the item, and
  • one event per person to whom they sent it

The first can be 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.

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.on.list@email.com","email.2.on.list@email.com"],
     "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>

A similar concept can be used for when someone shares something to social media; just track a similar event once they click the share button or you’ve confirmed that they shared the content.

Because the Received Article Share event is being sent to people who are not cookied on the front-end at the time of this action, this event will require a server-side Track request for each person on the list that the browser would like to send the article to. Note, each $event_id will need to be different. One way to achieve this, as an example, would be to base64 encode the email address of the recipient and concatenate the current UNIX timestamp:

{
  "token": "PUBLIC_API_KEY",
  "event": "Received Article Share",
  "customer_properties": {
    "$email": "email.on.list@email.com"
  },
  "properties": {
    "$event_id": "ZW1haWwub24ubGlzdEBlbWFpbC5jb20=_1500922636",
    "Sharer name": "John Smith",
    "Sharer email": "john.smith@test.com",
    "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
}

Refer a friend

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 (described above,) the first event should be sent with our Javascript Track API while the second event should be sent with our server-side track API for each referred friend. 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.

When someone refers a friend(s), send something like this for the referrer:

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

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.on.list@email.com",
    "Referrer name": "John Smith",
    "Referrer email": "john.smith@test.com",
    "Referrer code": "123abc456def"
  },
  "properties": {
    "$event_id": "ZW1haWwub24ubGlzdEBlbWFpbC5jb20=_1500922636",
  },
  "time": 1500922636
}

The Referrer code can then be used in a followup email to the referred people to create a unique link with the code in it. For example, in an email flow triggered by this Referred by Friend event, you could include this type of link:

{{ event|lookup:'Referrer name'}} thought you might like this,
<a href="https://www.example.com/?referral_code={{ event|lookup:'Referrer code}}">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 tracking when someone views a product, it may sometimes be helpful to capture when someone shows interest by viewing a particular category of items. This can be done with an event which triggers when a person lands on a category page. For example:

<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

Another high-level display of interest can be tracked when someone searches a particular term on your website. One consideration regarding this event is that people don’t always spell things correctly or search for the phrase you might expect. It may be useful to track someone's exact search phrase. It may also be useful to track a best guess of what someone may have been searching for as well as an autocorrected version of what your site might return as a result.  Tracking someone's exact search could potentially help you gain a better understanding of what people are searching for in a literal sense, while tracking a best guess and/or autocorrected version will make it easier to segment uniformly across searches people perform.

An event like this should be triggered when someone submits a search query and may look something like this:

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

Clicked Banner

When you have a carousel-style front-page banner or some other on-site display that a user can click on (to be directed to a specific destination,) it could be useful to track the clicking activity for reporting purposes and so that you can target the user based on their clicking activity.

 

The example below is for banner-ads but this can be extrapolated to other use-cases as well. Before you track clicking activity, it is important to ask the following question: “what is the marketing or reporting goal of tracking a click on this item.” 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 that more data tends to be better, but useless data can add unneeded cognitive overhead and detract from the user-friendliness of your account.

<script type="text/javascript">
   var _learnq = _learnq || [];
   _learnq.push(["track", "Clicked Banner",{
     "Source URL": "https://www.example.com/home",
     "Destination URL": "https://www.example.com/black-friday-deals",
     "Banner Title": "Check out these awesome Black Friday sales!"
   }]);
</script>
x
Was this article helpful?
0 out of 0 found this helpful