Skip to content

Client-Side JavaScript API

Full reference for the vanilla JS event bridge (about 3 KB gzipped) exposed via window.wpZbridgeBridge.

~3 KB gzipped Zero Dependencies

WP Zbridge injects a lightweight, non-blocking client-side bridge script (assets/js/zaraz-bridge.js) that safely coordinates interaction events with Cloudflare Zaraz.

The public API is exposed on the global window object as window.wpZbridgeBridge (with a backwards-compatible alias window.wpZarazBridge).


window.wpZbridgeBridge = {
track: function(eventName, payload) {},
ecommerce: function(actionName, payload) {},
flush: function() {}
};

If window.zaraz has not yet finished bootstrapping on the page, calls made to window.wpZbridgeBridge are automatically queued in an in-memory buffer and flushed once Zaraz initializes.


Dispatches a standard tracking event to Zaraz.

  • Parameters:
    • eventName (string, required): The name of the event (e.g. 'form_submit', 'file_download'). Use lowercase with underscores so GA4 accepts and reports it cleanly.
    • payload (object, optional): Key-value dictionary containing custom properties.
// Example: Custom banner interaction
window.wpZbridgeBridge.track('promo_banner_click', {
banner_id: 'summer_sale_2026',
position: 'homepage_hero'
});

Dispatches an e-commerce action conforming to Zaraz’s e-commerce event schema.

  • Parameters:
    • actionName (string, required): E-commerce action name (a Zaraz e-commerce event name, e.g. 'Product Viewed', 'Product Added', 'Product Removed', 'Order Completed', 'Order Refunded').
    • payload (object, required): Structured e-commerce payload matching the Zaraz OpenAPI schema.
// Example: Custom dynamic product view
window.wpZbridgeBridge.ecommerce('Product Viewed', {
product_id: 1042,
name: 'Anycast Edge Cloud Subscription',
price: 49.00,
currency: 'USD',
category: 'Hosting & Infrastructure'
});

Immediately flushes any buffered events to window.zaraz. Typically invoked automatically by DOM event listeners.

window.wpZbridgeBridge.flush();

The client script automatically listens for and dispatches the following browser interactions without any extra configuration. Each listener can be switched on or off under WP Zbridge → Event Tracking:

Event Tracking settings tab with interaction and search listeners

  1. Scroll Depth Tracking: scroll with percent_scrolled at 25%, 50%, 75%, and 90%.
  2. Active Time on Page: time_on_page milestones fire at 10s, 30s, 60s, 120s, and 300s of active engagement. The timer pauses automatically whenever the browser tab is hidden (document.visibilityState === 'hidden').
  3. Outbound Link Clicks: click with link_url, link_domain and outbound: 'true' for links to other domains.
  4. Email Link Clicks: click_email with only the email_domain (no address).
  5. Phone Link Clicks: click_phone, without the number.
  6. File Downloads: file_download with file_name, file_extension and link_url for .pdf, .zip, .csv, .docx, .xlsx, .mp3, .mp4 links.
  7. Site Search: the Zaraz e-commerce event Products Searched with query on search results (GA4 records view_search_results, Meta and TikTok Search), plus search_unsubmitted and search_result_click in Pro.
  8. User Lifecycle: Flash cookies capture backend login and sign_up events with user role attribution and fire on subsequent page load.
  9. WordPress Comments: Intercepts comment submissions and dispatches comment_submit with post and comment IDs.
  10. Lead Form Submissions: form_submit with form_id and form_plugin for submissions across Contact Form 7, WPForms, Gravity Forms, Fluent Forms, Elementor Forms, and custom generic HTML forms.
  11. 404 Errors: page_not_found with page_path.