Docs

Send events from anywhere that can speak HTTPS. Read these in order if you're new; jump to a section if you came here looking for one specific thing.

Quickstart

Three steps:

1. Sign up — free, no card. Your first app + API key are generated by the onboarding wizard.
2. Drop the SDK (or a curl) into your build, point it at the app's key, and ship a single event.
3. Watch it appear in the dashboard within seconds. From there, define a loop or wait for users.

One-shot from a terminal

curl -X POST https://owlsignal.dev/api/v1/events \
  -H "Authorization: Bearer pk_PASTE_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{"events":[{
    "build_version":"0.1.0",
    "session_id":"00000000-0000-0000-0000-000000000001",
    "player_hash":"0123456789abcdef0123456789abcdef",
    "ts":"2026-05-06T12:34:56Z",
    "type":"session",
    "name":"Session:Start"
  }]}'

Wire format

POST /api/v1/events with a JSON body containing an events array (1–100 events per batch). Every event has:

Response is always 200 with { accepted, rejected, errors }. Bad events in a batch are rejected but never fail the whole request — the SDK should never block the game.

Event types

Pick the one that best matches the moment. Type is purely a categorization signal — the dashboard groups things by it, but you can model nearly anything with design if unsure.

session

Session:Start / Session:End. Used to compute session duration. The SDK auto-fires these — you almost never call them by hand.

progression

Phase markers: Start:Run, Complete:Tutorial, Fail:Boss. Used by funnels and the Run analytics view.

design

Gameplay or UX signals that aren't pure phase markers: FirstTime:Combo, CTA:Clicked, Friction:DeadEnd. Default for "interesting moment, not sure what to call it."

resource

Soft-currency tracking. Convention: Source:Gold with positive value, Sink:Gold with positive value (the verb encodes direction).

error

Exceptions / critical issues. Powers the Errors page. Optional data.message, data.stack, data.scene, data.signature — signature groups identical errors.

Web SDK (JS/TS)

Lives in sdks/web in the repo. Copy the src/ contents into your project for now, or wait for the npm package release. Initialize once near the root of your client bundle:

import { OwlsignalClient } from '@owlsignal/web';

OwlsignalClient.Initialize({
  apiKey: 'pk_live_...',
  buildVersion: '1.4.0',
  // endpointUrl is optional — defaults to https://owlsignal.dev/api/v1/events
});

// Then anywhere a meaningful moment happens:
OwlsignalClient.TrackProgression('Complete:Tutorial');
OwlsignalClient.TrackDesign('CTA:Clicked', { dim01: 'pricing-pro' });
OwlsignalClient.TrackResource('Source:Coins', { value: 50 });
OwlsignalClient.TrackError('NullRef', { data: { stack: 'at foo.bar:12' } });

// Optional: identify the user (still anonymous — this is just a stable hash).
OwlsignalClient.IdentifyUser('user-abc');

// Optional: respect a user opt-out flag.
OwlsignalClient.SetOptOut(true);

Auto-events

Once initialized, the SDK fires a few events automatically:

• Session:Start on first track call after init.
• Session:End on pagehide (sent via fetch keepalive).

Events are batched (every 30s or 30 events, whichever first). 5xx responses retry with exponential backoff; 4xx drops the batch.

Unity SDK

Lives in sdks/unity in the repo, shape-equivalent to the web SDK (same OwlsignalClient.Initialize + Track* methods). The full quickstart and sample scene live in the SDK README — clone the repo or open the package directly to integrate.

Authentication

Send the API key in the Authorization header:

Authorization: Bearer pk_live_xxxxxxxxxxxxxxxxxxxxxxxx

Each key is scoped to one app inside one tenant. Generate keys in Settings → API keys. We store only a hash — the raw key is shown once when you generate it. Lost keys can be revoked + regenerated; we can't recover the raw value.

Rate limits & tier behavior

If your tenant has exceeded its monthly events budget, ingest silently drops the batch and returns 200 with { accepted: 0, rejected: N, reason: "tier_limit" }. The SDK never sees a 5xx for tier reasons; your game/app keeps working. The dashboard surfaces the cap; we email at 80% and 100% of budget.

Server-side validation rejects bad events individually (the rest of the batch goes through). The response always lists which indexes were rejected and why.

Privacy & opt-out

Events carry an anonymous player_hash only — no email, no IP, no real identity. Opt-out is a client-side contract: when the user toggles "telemetry off", call OwlsignalClient.SetOptOut(true) (web) or the Unity equivalent. The SDK then drops events at the source — the server can't detect opt-out because there's no identity to recognize.

Data residency: Postgres in eu-central-1 (Frankfurt), functions in fra1 (Frankfurt). See privacy for the full posture.