Cloudflare users leverage Zaraz for loading their third-party JavaScript tools. Tools like analytics, conversion pixels, widgets and alike, load faster and safer when loaded through Zaraz.
When configuring a tool in Zaraz, users can specify the payload to be included when sending information to it. This allows for the transmission of more detailed data. For example, when sending the "Button Clicked" event to Google Analytics, users can include additional information such as the ID of the button element and the content of the user_id cookie at the time of the button press. In Zaraz, users have the flexibility to add as many fields as desired when configuring the action.
Typically, information reaches Zaraz through the execution of zaraz.track("event name", { properties }) within the website's code. The properties object can contain relevant details that will be sent to third-party tools, such as the button ID in the previous example. However, there are cases where users may need to process and manipulate the information before sending it to their third-party tools.
To address this requirement, we recently introduced Worker Variables, which enables users to send information to a Cloudflare Worker, perform manipulations on it, and return a modified value. This feature offers immense power and flexibility. For instance, users can communicate with their backend server to retrieve data and leverage JavaScript to perform necessary calculations. With Worker Variables, users have access to a fully-featured Worker, opening up endless possibilities.
However, feedback from our users highlighted the need for a middle-ground solution. Sometimes, the data manipulation required is minor, and employing a Cloudflare Worker might feel like overkill. It is in response to this feedback that we decided to integrate with JSONata.
What is JSONata?
JSONata calls itself a JSON query and transformation language. While some developers may already be familiar with jq, the command-line JSON processor, JSONata offers similar features with a syntax that we believe is more intuitive and easier to understand. Since JSONata is a JavaScript library, it was very easy to integrate into Cloudflare Zaraz.
Let’s say we have JSON document like the following:
{
"name": "Jane Smith",
"address": {
"street": "123 High St",
"city": "London"
},
"pets": [
{ "type": "hamster", "name": "Rex" },
{ "type": "parrot", "name": "Milo" },
{ "type": "parrot", "name": "Alfie" }
]
}
With JSONata, with JSONata, one can run interesting queries on the document:
$count(pets) // 3
address.city // London
pets[type="parrot"].name // ["Alfie", "Milo"]
The JSONata documentation includes many examples for what you do with it, and there’s even a playground where you can try your JSONata queries live.
Using JSONata with Zaraz
JSONata has been tightly integrated with Cloudflare Zaraz, allowing you to leverage its capabilities in the fields of all Actions, Triggers, and Variables. Before diving into writing your JSONata expressions, it's essential to understand the JSON document you'll be working with.
Similar to Worker Variables or the HTTP Request tool, JSONata has access to the Zaraz Context. This object contains information from your zaraz.track() and zaraz.ecommerce() calls, as well as automatically gathered data by Zaraz, such as the current page URL, cookies, page title, user-agent string, and more. You can find the complete reference for this object in the Zaraz documentation.
Using your JSONata query is straightforward once you are familiar with it. To incorporate the query into your field content, simply enclose it within double curly brackets. The expression will be passed to JSONata along with the Zaraz Context object, and the resulting value will be used for the field.
Let's explore two examples from our documentation. Often, there's a need to convert a string to lowercase, such as when comparing it to another value in a regular expression. Suppose the original string is derived from a cookie named loggedIn, that specifies if the current user is logged in. In that case, we can use JSONata to transform the value to lowercase using the expression $lowercase(system.cookies.loggedIn). If we want to use this expression within a trigger, we navigate to the Zaraz dashboard and choose our trigger, locate the relevant match rule, and enter {{ $lowercase(system.cookies.loggedIn) }} as the value. Now, the cookie value will be compared in its lowercase format.
You can also run simple calculations. Assuming you are using zaraz.track() to send the cart content like this:
zaraz.track("Cart Viewed",
{ products:
[
{
sku: '2671033',
name: 'V-neck T-shirt',
price: 14.99,
quantity: 3
},{
sku: '2671034',
name: 'T-shirt',
price: 10.99,
quantity: 2
},
],
}
);
If the field in which you want to include the total sum of all products, you will enter {{ $sum(client.products.(price * quantity)) }}. This will multiply the price of each product by its quantity, and then sum up the total.
Start using JSONata today
JSONata support is available to all Zaraz users at no cost, and it is enabled automatically for all websites. Start using JSONata today to send finely tuned data to your providers or APIs with minimal code and zero maintenance for your data infrastructure. If you need any help - join our Discord channel!