API Reference

Complete JavaScript API documentation for the Klar tracker.

Global Object

The Klar tracker is available as window.klar after the script loads.

Methods

klar.trackPageview(url?, title?)

Manually track a pageview. Useful for custom routing implementations.

Parameters

  • url (optional) — Page URL (defaults to window.location.href)
  • title (optional) — Page title (defaults to document.title)

Example

// Track current page
klar.trackPageview();

// Track custom URL
klar.trackPageview('/custom-page', 'Custom Page Title');

klar.track(eventName, properties?)

Track a custom event with optional properties.

Parameters

  • eventName (required) — Event name (string)
  • properties (optional) — Event data (object)

Example

// Simple event
klar.track('button_click');

// Event with properties
klar.track('purchase', {
  product: 'Pro Plan',
  price: 29,
  currency: 'USD'
});

// Form submission
klar.track('form_submit', {
  form: 'contact',
  fields: ['name', 'email', 'message']
});

Property Limits

  • Max 50 properties per event
  • Property names: max 64 characters
  • Property values: max 256 characters
  • Nested objects are flattened

klar.setProperty(key, value)

Set a global property that will be sent with all future events.

Parameters

  • key (required) — Property name
  • value (required) — Property value

Example

// Set user tier
klar.setProperty('user_tier', 'pro');

// All future events will include user_tier: 'pro'
klar.track('feature_used', { feature: 'export' });

klar.identify(userId)

Associate events with a user ID (while maintaining privacy).

Parameters

  • userId (required) — Anonymous user identifier

Example

// Identify user (use hashed/anonymous IDs)
klar.identify('user_abc123');

// All future events will be associated with this user

Privacy Note

⚠️ Do not use personally identifiable information (email, name, etc.). Use hashed or anonymous IDs only.

klar.reset()

Clear all stored properties and user identification.

Example

// User logs out
klar.reset();

Configuration

Configure Klar using data attributes on the script tag:

data-site-id

Required. Your site ID from the Klar dashboard.

<script 
  src="https://your-klar-instance.com/klar.js" 
  data-site-id="abc123"
  defer
></script>

data-auto-track

Enable/disable automatic pageview tracking. Default: true

<script 
  src="https://your-klar-instance.com/klar.js" 
  data-site-id="abc123"
  data-auto-track="false"
  defer
></script>

When disabled, manually call klar.trackPageview().

data-honor-dnt

Respect browser's Do Not Track setting. Default: false

<script 
  src="https://your-klar-instance.com/klar.js" 
  data-site-id="abc123"
  data-honor-dnt="true"
  defer
></script>

When enabled, no tracking occurs if DNT is set.

data-api-host

Custom API endpoint for data collection. Default: same origin as script.

<script 
  src="https://cdn.example.com/klar.js" 
  data-site-id="abc123"
  data-api-host="https://analytics.example.com"
  defer
></script>

REST API

Server-side tracking using the HTTP API.

POST /api/collect

Send a pageview or event.

Headers

Content-Type: application/json

Body

{
  "site_id": "your-site-id",
  "url": "https://example.com/page",
  "title": "Page Title",
  "referrer": "https://google.com",
  "screen_width": 1920,
  "utm_source": "twitter",
  "utm_medium": "social",
  "utm_campaign": "launch",
  "event_name": "custom_event",
  "event_data": {
    "property": "value"
  }
}

Response

{
  "success": true
}

Example (cURL)

curl -X POST https://your-klar-instance.com/api/collect \
  -H "Content-Type: application/json" \
  -d '{
    "site_id": "abc123",
    "url": "https://example.com",
    "title": "Home"
  }'

Event Types

Common event names and their properties:

button_click

klar.track('button_click', {
  button: 'signup',
  location: 'header'
});

form_submit

klar.track('form_submit', {
  form: 'contact',
  fields: ['name', 'email']
});

purchase

klar.track('purchase', {
  product: 'Pro Plan',
  price: 29,
  currency: 'USD'
});

video_play

klar.track('video_play', {
  video_id: '123',
  duration: 45,
  provider: 'youtube'
});

search

klar.track('search', {
  query: 'analytics',
  results: 42
});

Browser Support

Klar supports all modern browsers:

  • Chrome / Edge (last 2 versions)
  • Firefox (last 2 versions)
  • Safari (last 2 versions)
  • Mobile browsers (iOS Safari, Chrome Mobile)

IE11 and older browsers are not supported.