Using Cloudflare Zaraz Web API to Track Page Events

• 1. Tracking Events
• 2. Setting Variables
• E-commerce

Cloudflare Zaraz is a tag/script/third-party management tool for websites. It's very similar to Google Tag Manager (GTM), but with the goal of being much faster. It does this by offloading much of the code processing to web workers, making it much faster and achieving better Lighthouse scores and making it more likely to pass Core Web Vitals tests. If you're interested in how Zaraz compares to GTM check out our article Cloudflare Zaraz vs Google Tag Manager (GTM).

The Zaraz Web API provides a set of powerful functions to track events, set variables, identify users, and handle e-commerce on your website. Let's dive into these functionalities one by one:

¶1. Tracking Events

Zaraz provides an async function, zaraz.track(), that allows you to track custom events on your website in real time. This could include user events like successful sign-ups, clicks on calls-to-action, or purchases, as well as other events like tracking impressions of specific elements on a page, or loading a specific widget​​.

Here's how to use zaraz.track():

zaraz.track(eventName, [eventProperties])

The eventName parameter is a string and eventProperties is an optional flat object of additional context you can attach to the event using your own keys of choice. For example, tracking a purchase could look like this:

zaraz.track("purchase", {value: 450, currency: "USD"})

You can track all sorts of things with track, let's look at some other examples:

// Track contact form submissions
zaraz.track("contactform", {userId: 555, formId: 372, email: "[email protected]"})

// Track company sign ups
zaraz.track("companyRegistration", {userId: 555, company: "accreditly", website: "https://accreditly.io"})

// Track an exam being passed on accreditly
zaraz.track("examPassed", {userId: 555, examId: 321, exam: "JavaScript Fundamentals"})

Once you're tracking these items you can set triggers within Zaraz's dashboard. This aspect is a little outside of the scope of this article, but we'll cover it in the future.

¶2. Setting Variables

To make a variable available in all your events without manually setting it every time you use zaraz.track(), you can use the zaraz.set() function. This function allows you to set a key-value pair that Zaraz will then attach to all future zaraz.track() calls​.

Here's how to use zaraz.set():

zaraz.set(key, value, [options])

Let's look at some real world examples. Assume you're doing the following zaraz.track() calls (same ones as the previous example):

// Track contact form submissions
zaraz.track("contactform", {userId: 555, formId: 372, email: "[email protected]"})

// Track company sign ups
zaraz.track("companyRegistration", {userId: 555, company: "accreditly", website: "https://accreditly.io"})

// Track an exam being passed on accreditly
zaraz.track("examPassed", {userId: 555, examId: 321, exam: "JavaScript Fundamentals"})

We're setting that same userId variable in every request. Due to the nature of how Zaraz works it wouldn't be obvious during testing if we missed a userId field when setting this up, and it's just a little annoying to have to add it to every request.

Instead, we can use zaraz.set() to set it once and then it's always sent. Great. Let's take a look:

// Set the userID:
zaraz.set("userId", 555)

// Track contact form submissions
zaraz.track("contactform", {formId: 372, email: "[email protected]"})

// Track company sign ups
zaraz.track("companyRegistration", {company: "accreditly", website: "https://accreditly.io"})

// Track an exam being passed on accreditly
zaraz.track("examPassed", {examId: 321, exam: "JavaScript Fundamentals"})

zaraz.set() takes a third parameter of options. Currently the only possible key it accepts is scope, which dictates how long Zaraz will keep sending the set variable for. Options here are:

• page: To set the key for the context of the current page only.
• session: To make the key last the whole session.
• persist: To save the key across sessions. This is the default mode and uses localStorage to save the value.

So to pass it for just this page:

zaraz.set("userId", 555, {scope: 'page'})

It's likely that Zaraz will add future options to the options parameter, but for now it's just scope.

Unsetting a variable is straightforward, simply set it to undefined:

zaraz.set("userId", undefined)

¶E-commerce

Zaraz has a suite of e-commerce features available in the Web API via zaraz.ecommerce().

For any of you who have implemented e-commerce tracking in other platforms (GTM, GA4, UA, Facebook/Meta, etc), it's extremely similar. Effectively, zaraz.ecommerce() works in the same way as zaraz.track(), but where zaraz.track() is used for custom events, zaraz.ecommerce() is used for predefined events related to ecommerce actions.

Before you begin with zaraz.ecommerce() you need to ensure you've set up your Zaraz dashboard and relevant third-parties to be expecting ecommerce events:

1. Log into Zaraz, click Settings
2. Click Enable E-commerce tracking
3. Save
4. Go to Tools > Third-party Tools
5. Find the tool you want to track with, click Edit
6. Under Settings > Advanced, check E-commerce tracking
7. Save

Repeat steps 4-7 for each tool you want to track e-commerce events for.

Once that's done you can begin tracking:

zaraz.ecommerce('event', { parameters });

Here's an example of adding a product to the basket:

zaraz.ecommerce('Product Added', {
  product_id: '123',
  sku: 'ACCREDITLY-123',
  category: 'Certifications',
  name: 'JavaScript Fundamentals',
  brand: 'Accreditly',
  price: 99.99,
  currency: 'usd',
  value: 99.99,
});

There are dozens of available ecommerce events, and they're all listed on the ecommerce docs.

Once you fire these events you shouldn't need to do anything further in order to be tracking ecommerce events, there's very little setup required on the Zaraz dashboard side.