Load a Custom Managed Component

Zaraz supports loading custom third-party tools using Managed Components Open external link . These can be Managed Components that you have developed yourself or that were developed by others. Using Custom Managed Components with Zaraz is done by converting them into a Cloudflare Worker running in your account.

If you are new to Managed Components, we recommend you get started with creating your own Managed Component Open external link or check out our demo Managed Component Open external link .

​​ Prepare a Managed Component

To get started, you need have a JavaScript file ready for deployment, that exports the default Managed Component function for your Managed Component.

In this guide, we will use a simple example of a Custom Managed Component that counts user visits and logs this data in the console:

// File: index.js
export default async function (manager) {
  // Add a pageview event
  manager.addEventListener("pageview", event, () => {
    const { client } = event;

    // Get the variable "counter" from the client's cookies and increase by 1
    let counter = parseInt(client.get("counter")) || 0;
    counter += 1;

    // Log the increased number
    client.execute(`console.log('Views: ${counter}')`);

    // Store the increased number for the next visit
    client.set("counter", counter);
  });
}

​​ Deploy a Managed Component to Cloudflare

1. Open a terminal in your Managed Component’s root directory.
2. From there, run npx managed-component-to-cloudflare-worker ./index.js my-new-counter-mc, which will deploy the Managed Component to a specialized Cloudflare Worker. Change the path to your index.js. You can also rename the Component if you choose.
3. Your Managed Component should now be visible on your account Open external link as a Cloudflare Worker prefixed with custom-mc.

​​ Configure a Managed Component in Cloudflare

1. Log in to the Cloudflare dashboard Open external link and select your account and domain.
2. Select Zaraz > Tools Configuration > Third-party tools Open external link .
3. Select Add new tool and choose Custom Managed Component from the tools library page. Select Continue to confirm your selection.
4. In Select Custom MC, choose a Custom Managed Component that you have deployed to your account, such as my-new-counter-mc. Select Continue.
5. In Permissions, select the permissions you want to grant the Custom Managed Component. If you run an untrusted Managed Component, pay close attention to what permissions you are granting. Select Continue.
6. In Set up, configure the settings for your new tool. The information you need to enter will depend on the code of the Managed Component. You can add settings and default fields, as well as use variables you have previously set up.
7. Select Save.

While your tool is now configured, it does not have any actions associated with it yet. Adding new actions will tell Zaraz when to contact your Managed Component, and what information to send to it. When adding actions, make sure to verify the Action Type you are using. The types pageview and event are most commonly used, but you can add any action type to match the event listeners your Managed Component is using. Learn how to create additional actions.

If your Managed Component listens to ecommerce events, toggle E-commerce tracking in the Managed Component Settings page.

​​ Unsupported Features

As of now, Custom Managed Components do not support the use of the following methods yet:

• manager.registerEmbed
• manager.registerWidget
• manager.proxy
• manager.route
• manager.serve