1# Zaraz Web API
2 
3Client-side JavaScript API for tracking events, setting properties, and managing consent.
4 
5## zaraz.track()
6 
7```javascript
8zaraz.track('button_click');
9zaraz.track('purchase', { value: 99.99, currency: 'USD', item_id: '12345' });
10zaraz.track('pageview', { page_path: '/products', page_title: 'Products' }); // SPA
11```
12 
13**Params:** `eventName` (string), `properties` (object, optional). Fire-and-forget.
14 
15## zaraz.set()
16 
17```javascript
18zaraz.set('userId', 'user_12345');
19zaraz.set({ email: '[email protected]', plan: 'premium', country: 'US' });
20```
21 
22Properties persist for page session. Use for user identification and segmentation.
23 
24## zaraz.ecommerce()
25 
26```javascript
27zaraz.ecommerce('Product Viewed', { product_id: 'SKU123', name: 'Widget', price: 49.99 });
28zaraz.ecommerce('Product Added', { product_id: 'SKU123', quantity: 2, price: 49.99 });
29zaraz.ecommerce('Order Completed', {
30  order_id: 'ORD-789', total: 149.98, currency: 'USD',
31  products: [{ product_id: 'SKU123', quantity: 2, price: 49.99 }]
32});
33```
34 
35**Events:** `Product Viewed`, `Product Added`, `Product Removed`, `Cart Viewed`, `Checkout Started`, `Order Completed`
36 
37Tools auto-map to GA4, Facebook CAPI, etc.
38 
39## System Properties (Triggers)
40 
41```
42{{system.page.url}}   {{system.page.title}}   {{system.page.referrer}}
43{{system.device.ip}}  {{system.device.userAgent}}  {{system.device.language}}
44{{system.cookies.name}}  {{client.__zarazTrack.userId}}
45```
46 
47## zaraz.consent
48 
49```javascript
50// Check
51const purposes = zaraz.consent.getAll(); // { analytics: true, marketing: false }
52 
53// Set
54zaraz.consent.modal = true; // Show modal
55zaraz.consent.setAll({ analytics: true, marketing: false });
56zaraz.consent.set('marketing', true);
57 
58// Listen
59zaraz.consent.addEventListener('consentChanged', () => {
60  if (zaraz.consent.getAll().marketing) zaraz.track('marketing_consent_granted');
61});
62```
63 
64**Flow:** Configure purposes in dashboard → Map tools to purposes → Show modal/set programmatically → Tools fire when allowed
65 
66## zaraz.debug
67 
68```javascript
69zaraz.debug = true;
70zaraz.track('test_event');
71console.log(zaraz.tools); // View loaded tools
72```
73 
74## Cookie Methods
75 
76```javascript
77zaraz.getCookie('session_id');  // Zaraz namespace
78zaraz.readCookie('_ga');        // Any cookie
79```
80 
81## Async Behavior
82 
83All methods fire-and-forget. Events batched and sent asynchronously:
84 
85```javascript
86zaraz.track('event1');
87zaraz.set('prop', 'value');
88zaraz.track('event2'); // All batched
89```
90 
91## TypeScript Types
92 
93```typescript
94interface Zaraz {
95  track(event: string, properties?: Record<string, unknown>): void;
96  set(key: string, value: unknown): void;
97  set(properties: Record<string, unknown>): void;
98  ecommerce(event: string, properties: Record<string, unknown>): void;
99  consent: {
100    getAll(): Record<string, boolean>;
101    setAll(purposes: Record<string, boolean>): void;
102    set(purpose: string, value: boolean): void;
103    addEventListener(event: 'consentChanged', callback: () => void): void;
104    modal: boolean;
105  };
106  debug: boolean;
107  tools?: string[];
108  getCookie(name: string): string | undefined;
109  readCookie(name: string): string | undefined;
110}
111declare global { interface Window { zaraz: Zaraz; } }
112```
113