Getting Started with Sparkl

Sparkl is an analytics platform that helps you understand how users interact with your product.

There are two ways to integrate Sparkl:

Method	Best For	Setup Time
JavaScript SDK (Recommended)	Web applications	5 minutes
Server API	Backend services, mobile apps	15 minutes

JavaScript SDK (Recommended)

The JavaScript SDK is the easiest way to get started. It automatically tracks page views, sessions, and provides a simple API for custom events.

Quick Start

Add this snippet to the <head> section of your HTML:

<script async src="https://js.sparkl.one/browser/scripts/YOUR_API_KEY/sparkl.js"></script>
<script>
  window.SPARKL_CONTEXT = {
    key: "user_123",           // Required: unique user ID
    user: {
      email: "user@example.com"
    },
    extra: {
      account_id: "acme_123",
      account_name: "Acme Corp"
    }
  };
</script>

Track Custom Events

// Track an event with properties
window.SPARKL.track('Video Played', {
  video_id: '123',
  duration: 45,
  quality: 'HD'
});

// Track a simple event
window.SPARKL.track('Feature Used');

Context Fields

Field	Required	Description
`key`	Yes	Unique identifier for the user
`user.email`	Recommended	User's email address
`extra.account_id`	Recommended	Customer account identifier
`extra.account_name`	Optional	Display name for the account

You can add any additional fields to extra for custom segmentation.

Server API

Use the Server API when you need to track events from your backend, mobile apps, or any environment where JavaScript isn't available.

Base URL: https://app.sparkl.one/api/v1
Authentication: Include your API key in the X-Api-Key header

All endpoints require a key parameter - a unique identifier for the user (e.g., user ID, email, or UUID). This links all events and context data to that user across sessions.

Track Events

Track server-side events like purchases, subscription renewals, or webhook callbacks.

curl -X POST https://app.sparkl.one/api/v1/events \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "user_123",
    "event": "subscription-renewed",
    "properties": {
      "plan": "pro",
      "amount": 99
    }
  }'

Update User Context

Keep user context in sync when their info changes in your system.

curl -X PATCH https://app.sparkl.one/api/v1/contexts \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "user_123",
    "user": {
      "email": "user@example.com",
      "name": "Jane Doe"
    },
    "extra": {
      "plan": "pro",
      "company": "Acme Inc"
    }
  }'

For complete endpoint documentation, see the API Reference.

Next Steps

Create an API key in the Sparkl dashboard
Choose your integration method
Start tracking events
Build charts and dashboards to visualize your data