Referencia de la API

Documentación completa de la API de JavaScript del rastreador de Klar.

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://klar.alphabros.eu/klar.js" 
  data-site-id="abc123"
  defer
></script>

data-auto-track

Enable/disable automatic pageview tracking. Default: true

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

When disabled, manually call klar.trackPageview().

data-honor-dnt

Respect the browser's Do Not Track (DNT) and Global Privacy Control (GPC) signals. Default: true. Set to "false" to track visitors who send these signals.

<script
  src="https://klar.alphabros.eu/klar.js"
  data-site-id="abc123"
  data-honor-dnt="false"
  defer
></script>

While enabled (the default), no tracking occurs and no identifier is stored if DNT or GPC 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://klar.alphabros.eu/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.