Custom Events and Goals

Track user actions beyond page views. Custom events let you measure button clicks, form submissions, and any other interaction. Goals let you define conversion targets with optional revenue tracking.

Custom Events

Use the ka.track() method to send custom events from your website.

Basic Event

// Track a simple event
ka.track("signup")

// Track an event with properties
ka.track("signup", { plan: "pro", source: "landing-page" })

Common Examples

// Newsletter subscription
document.getElementById("subscribe-form").addEventListener("submit", () => {
  ka.track("newsletter_signup")
})

// Button click
document.getElementById("cta-button").addEventListener("click", () => {
  ka.track("cta_click", { variant: "hero" })
})

// File download
document.querySelectorAll("a[download]").forEach((link) => {
  link.addEventListener("click", () => {
    ka.track("download", { file: link.getAttribute("href") })
  })
})

Events are sent to the tracking endpoint (POST /a/e) as part of the event queue, batched automatically for performance.

TIP

Event names are case-sensitive. Use consistent naming conventions like snake_case to keep your dashboard organized.

Goals

Goals let you define conversion targets and track how well your site achieves them. Goals can optionally track revenue.

Track a Goal

// Track a goal conversion
ka.goal("purchase")

// Track a goal with revenue (in your site's currency)
ka.goal("purchase", 49.99)

// Track a subscription goal
ka.goal("subscription", 29.00)

Goal Types

Type	Description	Example
pageview	Triggers when a specific page is visited	User visits /thank-you
event	Triggers when a custom event fires	User triggers signup event
custom	Triggers via explicit ka.goal() call	User completes a purchase

Match Types

Goals use match types to determine when a conversion occurs:

Match Type	Description	Example
exact	Value must match exactly	/thank-you matches only /thank-you
contains	Value must contain the string	signup matches newsletter_signup and signup_complete
regex	Value must match the regex pattern	/products/\d+ matches /products/123

Creating Goals

Via Dashboard

1. Navigate to Analytics > Your Site > Goals.
2. Click Add Goal.
3. Enter a name, select the type and match type, and provide the match value.
4. Optionally set a currency for revenue tracking.

Via API

curl -X POST https://app.krafter.dev/api/v1/analytics/sites/sk_abc123def456/goals \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Purchase",
    "type": "custom",
    "match_type": "exact",
    "match_value": "purchase",
    "currency": "USD"
  }'

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Purchase",
    "type": "custom",
    "match_type": "exact",
    "match_value": "purchase",
    "currency": "USD"
  }
}

See the Goals API reference for the full CRUD API.

Goal Statistics

Each goal tracks three metrics:

Metric	Description
conversions	Total number of times the goal was triggered
unique_conversions	Number of unique visitors who triggered the goal
revenue	Total revenue attributed to the goal (if configured)

Query Goal Stats via API

curl "https://app.krafter.dev/api/v1/analytics/sites/sk_abc123def456/goals/GOAL_ID/stats?period=30d" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

{
  "data": {
    "conversions": 342,
    "unique_conversions": 298,
    "revenue": 16758.00
  }
}

Examples

Track Newsletter Signup

Create a pageview goal that triggers when a visitor reaches the confirmation page:

curl -X POST https://app.krafter.dev/api/v1/analytics/sites/sk_abc123def456/goals \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Newsletter Signup",
    "type": "pageview",
    "match_type": "exact",
    "match_value": "/newsletter/confirmed"
  }'

Track Purchase with Revenue

Create a custom goal and trigger it from your checkout flow:

curl -X POST https://app.krafter.dev/api/v1/analytics/sites/sk_abc123def456/goals \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Purchase",
    "type": "custom",
    "match_type": "exact",
    "match_value": "purchase",
    "currency": "USD"
  }'

Then in your checkout code:

// After successful payment
ka.goal("purchase", orderTotal)

Next Steps

• Tracker reference -- full JavaScript API documentation
• Goals API -- manage goals programmatically
• Stats API -- query event and goal data