Appearance
Tracker Reference
Complete reference for the Krafter Analytics JavaScript tracker (a.js). The tracker is a lightweight script that collects page views, custom events, and goal conversions.
Installation
Add the tracker script to the <head> of your website:
html
<script defer data-site="sk_YOUR_SITE_KEY" src="https://app.krafter.dev/a.js"></script>| Attribute | Required | Description |
|---|---|---|
data-site | Yes | Your site key, starting with sk_. |
defer | Recommended | Loads the script without blocking page rendering. |
TIP
The tracker is under 1 KB, loads asynchronously, and has zero impact on page load performance.
The window.ka Object
Once loaded, the tracker exposes the window.ka object with the following methods.
ka.track(name, props?)
Track a custom event.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Event name. |
props | object | No | Key-value pairs of event properties. |
Examples:
javascript
// Simple event
ka.track("signup")
// Event with properties
ka.track("signup", { plan: "pro", source: "landing-page" })
// Button click tracking
document.getElementById("cta").addEventListener("click", () => {
ka.track("cta_click", { variant: "hero", position: "above-fold" })
})ka.goal(name, revenue?)
Track a goal conversion with optional revenue.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Goal name. Must match a goal's match_value configured in the dashboard or API. |
revenue | number | No | Revenue amount for this conversion. |
Examples:
javascript
// Simple goal
ka.goal("signup")
// Goal with revenue
ka.goal("purchase", 49.99)
// After checkout completion
async function handleCheckout(order) {
await processPayment(order)
ka.goal("purchase", order.total)
}ka.page(opts?)
Manually track a page view. This is useful when automatic SPA tracking does not cover your use case.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
opts | object | No | Options object. |
opts.url | string | No | URL to record. Defaults to the current window.location.href. |
Examples:
javascript
// Track current page
ka.page()
// Track a specific URL
ka.page({ url: "https://example.com/virtual-page" })INFO
In most cases you do not need to call ka.page() manually. The tracker automatically records page views on load and during SPA navigation.
Automatic Behavior
The tracker handles the following automatically without any configuration:
Page View on Load
A page view is recorded when the script loads. No manual call is needed.
SPA Navigation
The tracker intercepts History.pushState and History.replaceState to automatically track page views in single-page applications. This works with all major SPA frameworks (React, Vue, Svelte, Angular, etc.) out of the box.
Event Buffering
Events are buffered and sent in batches. When the tab becomes hidden (via the visibilitychange event), any remaining buffered events are flushed immediately to avoid data loss.
Beacon with Fallback
The tracker uses navigator.sendBeacon when available for reliable delivery during page unload. It falls back to fetch in environments where sendBeacon is not supported.
Do Not Track
If a visitor has navigator.doNotTrack set to "1", the tracker will not collect or send any data. This check is performed on every page load.
Data Format
Events are sent to the tracking endpoint as a POST request:
POST https://app.krafter.dev/a/eThe request body is JSON with the following structure:
json
{
"s": "sk_abc123def456",
"u": "https://example.com/pricing",
"r": "https://google.com/search?q=example",
"w": 1920,
"q": [
["p"],
["t", "signup", { "plan": "pro" }],
["g", "purchase", 49.99]
]
}| Field | Description |
|---|---|
s | Site key. |
u | Current page URL. |
r | Referrer URL (the page the visitor came from). |
w | Viewport width in pixels. |
q | Event queue. Array of event tuples. |
Event Queue Format
Each entry in the q array is a tuple:
| Type | Format | Description |
|---|---|---|
| Page view | ["p"] | Automatic page view event. |
| Custom event | ["t", "name", {props}] | Custom event with optional properties. |
| Goal | ["g", "name", revenue] | Goal conversion with optional revenue. |
WARNING
The tracking endpoint (POST /a/e) is a public endpoint designed for the tracker script. It does not require authentication. Do not confuse it with the REST API endpoints under /api/v1/analytics, which require a Bearer token.
Rate limit (public)
POST /a/e uses the public bucket — 200 requests / 60 seconds per client IP, shared with form submissions, email tracking, unsubscribe, public survey writes, and webhook ingest. Visitors share their own IP so this is rarely an issue for an individual browser; backend integrations that proxy events through a single egress can hit it. The tracker script already batches the page view and any custom events from the same page into one request.
Framework Examples
jsx
// Track event in a React component
function PricingPage() {
const handleUpgrade = (plan) => {
ka.track("upgrade_click", { plan })
}
return (
<button onClick={() => handleUpgrade("pro")}>
Upgrade to Pro
</button>
)
}vue
<!-- Track event in a Vue component -->
<template>
<button @click="handleSignup">Sign Up</button>
</template>
<script setup>
function handleSignup() {
ka.track("signup", { source: "pricing-page" })
}
</script>svelte
<!-- Track event in a Svelte component -->
<script>
function handleDownload() {
ka.track("download", { file: "whitepaper.pdf" })
}
</script>
<button on:click={handleDownload}>Download</button>typescript
// Type declaration for window.ka
declare global {
interface Window {
ka: {
track: (name: string, props?: Record<string, string | number | boolean>) => void
goal: (name: string, revenue?: number) => void
page: (opts?: { url?: string }) => void
}
}
}
// Usage with types
window.ka.track("signup", { plan: "pro" })
window.ka.goal("purchase", 49.99)Next Steps
- Quickstart -- install the tracker on your site
- Custom events and goals -- set up conversion tracking
- Privacy -- understand what data is collected
- Stats API -- query your analytics data via REST