getting started

1. Include the SDK

Add this script tag to your HTML, pointing at your deebeelog server:

<script src="https://your-server/static/deebeelog.js"></script>

2. Initialize

Call init once with your API URL and key:

deebeelog.init({
  apiUrl: 'https://your-server',
  apiKey: 'your-api-key'
});

3. Log events

Fire events anywhere with deebeelog.event(type, name, metadata):

// page view
deebeelog.event('view', 'landing', null);

// button click with metadata
deebeelog.event('click', 'signup-btn', { plan: 'pro' });

// any custom event
deebeelog.event('search', 'query', { term: 'hello' });

Event shape

Every event has three fields:

type     — category: 'view', 'click', 'submit', etc.
name     — identifier: 'landing', 'cta-button', etc.
metadata — any JSON object, or null

From other environments

You can log from any HTTP client — no JS required:

curl -X POST https://your-server/events \
  -H 'x-api-key: your-api-key' \
  -H 'Content-Type: application/json' \
  -d '{"type":"deploy","name":"backend","meta":{"version":"1.2"}}'

tables

Schema reference for all deebeelog tables.

experiments

Run A/B tests with persistent, deterministic assignment.

1. Create an experiment

Define the experiment once via the API (typically via curl or a setup script):

curl -X POST https://your-server/experiments \
  -H 'x-api-key: your-api-key' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "cta-button",
    "type": "user",
    "treatments": [
      { "name": "control", "weight": 50 },
      { "name": "green",   "weight": 50 }
    ]
  }'

2. Read the treatment in the browser

// single experiment
const variant = await deebeelog.get_treatment('cta-button');
// → 'control' or 'green'

// multiple experiments in one round trip
const t = await deebeelog.get_treatments(['cta-button', 'hero-copy']);
// → { 'cta-button': 'green', 'hero-copy': 'control' }

Randomization types

Pass as the second argument to get_treatment / get_treatments. Default is user.

user     — persistent per browser (UUID stored in localStorage)
session  — persistent for the current session
random   — fresh assignment on every call, no stickiness

await deebeelog.get_treatment('cta-button', 'session');

How assignment works

The backend hashes (experiment_id, unit_id) to deterministically pick a treatment bucket proportional to weight. For user and session types the result is stored in experiment_allocation and returned unchanged on every subsequent call for that unit.

Querying results

SELECT ea.treatment, COUNT(*) AS users
FROM experiment_allocation ea
JOIN experiment e ON e.id = ea.experiment_id
WHERE e.name = 'cta-button'
GROUP BY ea.treatment;