dotfiles/.agents/skills/cloudflare-deploy/references/zaraz/api.md

Zaraz Web API

Client-side JavaScript API for tracking events, setting properties, and managing consent.

zaraz.track()

zaraz.track('button_click');
zaraz.track('purchase', { value: 99.99, currency: 'USD', item_id: '12345' });
zaraz.track('pageview', { page_path: '/products', page_title: 'Products' }); // SPA

Params: eventName (string), properties (object, optional). Fire-and-forget.

zaraz.set()

zaraz.set('userId', 'user_12345');
zaraz.set({ email: '[email protected]', plan: 'premium', country: 'US' });

Properties persist for page session. Use for user identification and segmentation.

zaraz.ecommerce()

zaraz.ecommerce('Product Viewed', { product_id: 'SKU123', name: 'Widget', price: 49.99 });
zaraz.ecommerce('Product Added', { product_id: 'SKU123', quantity: 2, price: 49.99 });
zaraz.ecommerce('Order Completed', {
  order_id: 'ORD-789', total: 149.98, currency: 'USD',
  products: [{ product_id: 'SKU123', quantity: 2, price: 49.99 }]
});

Events: Product Viewed, Product Added, Product Removed, Cart Viewed, Checkout Started, Order Completed

Tools auto-map to GA4, Facebook CAPI, etc.

System Properties (Triggers)

{{system.page.url}}   {{system.page.title}}   {{system.page.referrer}}
{{system.device.ip}}  {{system.device.userAgent}}  {{system.device.language}}
{{system.cookies.name}}  {{client.__zarazTrack.userId}}

zaraz.consent

// Check
const purposes = zaraz.consent.getAll(); // { analytics: true, marketing: false }

// Set
zaraz.consent.modal = true; // Show modal
zaraz.consent.setAll({ analytics: true, marketing: false });
zaraz.consent.set('marketing', true);

// Listen
zaraz.consent.addEventListener('consentChanged', () => {
  if (zaraz.consent.getAll().marketing) zaraz.track('marketing_consent_granted');
});

Flow: Configure purposes in dashboard → Map tools to purposes → Show modal/set programmatically → Tools fire when allowed

zaraz.debug

zaraz.debug = true;
zaraz.track('test_event');
console.log(zaraz.tools); // View loaded tools

Cookie Methods

zaraz.getCookie('session_id');  // Zaraz namespace
zaraz.readCookie('_ga');        // Any cookie

Async Behavior

All methods fire-and-forget. Events batched and sent asynchronously:

zaraz.track('event1');
zaraz.set('prop', 'value');
zaraz.track('event2'); // All batched

TypeScript Types

interface Zaraz {
  track(event: string, properties?: Record<string, unknown>): void;
  set(key: string, value: unknown): void;
  set(properties: Record<string, unknown>): void;
  ecommerce(event: string, properties: Record<string, unknown>): void;
  consent: {
    getAll(): Record<string, boolean>;
    setAll(purposes: Record<string, boolean>): void;
    set(purpose: string, value: boolean): void;
    addEventListener(event: 'consentChanged', callback: () => void): void;
    modal: boolean;
  };
  debug: boolean;
  tools?: string[];
  getCookie(name: string): string | undefined;
  readCookie(name: string): string | undefined;
}
declare global { interface Window { zaraz: Zaraz; } }