Cloudflare Docs
Zaraz
Cloudflare Docs
Zaraz
GitHub icon
Edit this page on GitHub
Set theme to dark (⇧+D)
  1. Products
  2. Zaraz
  3. FAQ

FAQ

Below you will find answers to our most commonly asked questions. If you cannot find the answer you are looking for, refer to the community page or Discord channel to explore additional resources.

​​ General

​​ Setting up Zaraz

​​ Why is Zaraz not working?

If you are experiencing issues with Zaraz, there could be multiple reasons behind it. First, it’s important to verify that the Zaraz script is loading properly on your website.

To check if the script is loading correctly, follow these steps:

  1. Open your website in a web browser.
  2. Open your browser’s Developer Tools.
  3. In the Console, type zaraz.
  4. If you see an error message saying zaraz is not defined, it means that Zaraz failed to load.

If Zaraz is not loading, please verify the following:

​​ I’m seeing some data discrepancies. Is there a way to check what data reaches Zaraz?

Yes. You can use the metrics in Zaraz Monitoring to help you find where in the workflow the problem occurred.

​​ Can I use Zaraz with Rocket Loader?

We recommend disabling Rocket Loader when using Zaraz. While Zaraz can be used together with Rocket Loader, there’s usually no need to use both. Rocket Loader can sometimes delay data from reaching Zaraz, causing issues.

​​ Is Zaraz compatible with Content Security Policies (CSP)?

Yes. To learn more about how Zaraz works to be compatible with CSP configurations, refer to the Cloudflare Zaraz supports CSP blog post.

​​ Does Cloudflare process my HTML, removing existing scripts and then injecting Zaraz?

Cloudflare Zaraz does not remove other third-party scripts from the page. Zaraz can be auto-injected or not, depending on your configuration, but if you have existing scripts that you intend to load with Zaraz, you should remove them.

​​ Does Zaraz work with Cloudflare Page Shield?

Yes. Refer to Page Shield for more information related to this product.

​​ Is there a way to prevent Zaraz from loading on specific pages, like under /wp-admin?

To prevent Zaraz from loading on specific pages, refer to Load Zaraz selectively.

​​ How can I remove my Zaraz configuration?

Resetting your Zaraz configuration will erase all of your configuration settings, including any tools, triggers, and variables you’ve set up. This action will disable Zaraz immediately. If you want to start over with a clean slate, you can always reset your configuration.

  1. Log in to the Cloudflare dashboard, and select your account and domain.
  2. Go to Zaraz > Settings > Advanced.
  3. Click “Reset” and follow the instructions.

​​ Zaraz Web API

​​ Why would the zaraz.ecommerce() method returns an undefined error?

E-commerce tracking needs to be enabled in the Zaraz Settings page before you can start using the E-commerce Web API.

​​ How would I trigger pageviews manually on a Single Page Application (SPA)?

Zaraz comes with built-in Single Page Application (SPA) support that automatically sends pageview events when navigating through the pages of your SPA. However, if you have advanced use cases, you might want to build your own system to trigger pageviews. In such cases, you can use the internal SPA pageview event by calling zaraz.spaPageview().

​​ Tools

​​ Google Analytics

​​ After moving from Google Analytics 4 to Zaraz, I can no longer see demographics data. Why?

You probably have enabled Hide Originating IP Address in the Settings option for Google Analytics 4. This tells Zaraz to not send the IP address to Google. To have access to demographics data and anonymize your visitor’s IP, you should use Anonymize Originating IP Address instead.

​​ I see two ways of anonymizing IP address information on the third-party tool Google Analytics: one in Privacy, and one in Additional fields. Which is the correct one?

There is not a correct option, as the two options available in Google Analytics (GA) do different things.

The Hide Originating IP Address option in Tool Settings prevents Zaraz from sending the IP address from a visitor to Google. This means that GA treats Zaraz’s Worker’s IP address as the visitor’s IP address. This is often close in terms of location, but it might not be.

With the Anonymize Originating IP Address available in the Add field option, Cloudflare sends the visitor’s IP address to Google as is, and passes the aip parameter to GA. This asks GA to anonymize the data.

​​ If I set up Event Reporting (enhanced measurements) for Google Analytics, why does Zaraz only report Page View, Session Start, and First Visit?

This is not a bug. Zaraz does not offer all the automatic events the normal GA4 JavaScript snippets offer out of the box. You will need to build triggers and actions to capture those events. Refer to Get started to learn more about how Zaraz works.

​​ Can I set up custom dimensions for Google Analytics with Zaraz?

Yes. Refer to Additional fields to learn how to send additional data to tools.

​​ How do I attach a User Property to my events?

In your Google Analytics 4 action, select Add field > Add custom field… and enter a field name that starts with up. — for example, up.name. This will make Zaraz send the field as a User Property and not as an Event Property.
Zaraz has built-in support for Google Consent Mode v2. Learn more on how to use it in Google Consent Mode page.

​​ Facebook Pixel

​​ If I set up Facebook Pixel on my Zaraz account, why am I not seeing data coming through?

It can take between 15 minutes to several hours for data to appear on Facebook’s interface, due the way Facebook Pixel works. You can also use debug mode to confirm that data is being properly sent from your Zaraz account.

​​ What is the expected format for Conversion ID and Conversion Label

Conversion ID and Conversion Label are usually provided by Google Ads as a “gtag script”. Here’s an example for a $1 USD conversion:

gtag('event', 'conversion', {
   'send_to': 'AW-123456789/AbC-D_efG-h12_34-567',
   'value': 1.0,
   'currency': 'USD'
 });

The Conversion ID is the first part of send_to parameter, without the AW-. In the above example it would be 123456789. The Conversion Label is the second part of the send_to parameter, therefore AbC-D_efG-h12_34-567 in the above example. When setting up your Google Ads conversions through Zaraz, take the information from the original scripts you were asked to implement.

​​ Custom HTML

​​ Can I use Google Tag Manager together with Zaraz?

You can load Google Tag Manager using Zaraz, but it is not recommended. Tools configured inside Google Tag Manager cannot be optimized by Zaraz, and cannot be restricted by the Zaraz privacy controls. In addition, Google Tag Manager could slow down your website because it requires additional JavaScript, and its rules are evaluated client-side. If you are currently using Google Tag Manager, we recommend replacing it with Zaraz by configuring your tags directly as Zaraz tools.

​​ Why should I prefer a native tool integration instead of an HTML snippet?

Adding a tool to your website via a native Zaraz integration is always better than using an HTML snippet. HTML snippets usually depends on additional client-side requests, and require client-side code execution, which can slow down your website. They are often a security risk, as they can be hacked. Moreover, it can be very difficult to control their affect on the privacy of your visitors. Tools included in the Zaraz library are not suffering from these issues - they are fast, executed at the edge, and be controlled and restricted because they are sandboxed.

​​ How can I set my Custom HTML to be injected just once in my Single Page App (SPA) website?

If you have enabled “Single Page Application support” in Zaraz Settings, your Custom HTML code may be unnecessarily injected every time a new SPA page is loaded. This can result in duplicates. To avoid this, go to your Custom HTML action and select the “Add Field” option. Then, add the “Ignore SPA” field and enable the toggle switch. Doing so will prevent your code from firing on every SPA pageview and ensure that it is injected only once.

​​ Other tools

​​ What if I want to use a tool that is not supported by Zaraz?

The Zaraz engineering team is adding support to new tools all the time. You can also refer to the community space to ask for new integrations.

​​ I cannot get a tool to load when the website is loaded. Do I have to add code to my website?

If you proxy your domain through Cloudflare, you do not need to add any code to your website. By default, Zaraz includes an automated Pageview trigger. Some tools, like Google Analytics, automatically add a Pageview action that uses this trigger. With other tools, you will need to add it manually. Refer to Get started for more information.

​​ I am a vendor. How can I integrate my tool with Zaraz?

The Zaraz team is working with third-party vendors to build their own Zaraz integrations using the Zaraz SDK. To request a new tool integration, or to collaborate on our SDK, contact us at zaraz@cloudflare.com.
In such a case, you can change the cookie name in the Consent cookie name field in the Zaraz Consent configuration. This will cause the consent modal to reappear for all users. Make sure to use a cookie name that has not been used for Zaraz on your site.