Configuration

Oddlytics has three places to configure: the Worker, the dashboard build, and the Swift package in each app.

Worker

The Worker reads its settings from packages/worker/wrangler.toml and from Cloudflare secrets.

Setting	Where	Default	What it does
AUTH_KEY	Secret (npx wrangler secret put AUTH_KEY), or .dev.vars locally	none	The API key. POST /track, renaming events, changing app settings and every delete need it in the X-API-KEY header.
DB	[[d1_databases]] binding in wrangler.toml	oddlytics-db	The D1 database that holds events. Set database_id to the ID from wrangler d1 create.
ENVIRONMENT	[vars] in wrangler.toml	production	When it is anything other than production, error responses include the underlying error message.
name	wrangler.toml	oddlytics-worker	The Worker's name, which is part of its workers.dev address.

WARNING

Only POST /track, the alias and app settings writes, and the delete endpoints check AUTH_KEY. The read endpoints under /stats and GET /aliases answer anyone who knows the Worker's address. See Privacy & Data.

The Worker also enforces these limits on every event:

Limit	Value
Events per request	100
event, app_id, session_id length	255 characters each
metadata size	10 KB as JSON

Dashboard

The dashboard reads two variables at build time. Set them in packages/dashboard/.env.local, or in your hosting provider's build settings.

Variable	Default	What it does
NEXT_PUBLIC_API_URL	http://localhost:8787	The Worker's address.
NEXT_PUBLIC_API_KEY	oddlytics-local-key	Sent as X-API-KEY with every request. Must match the Worker's AUTH_KEY.

Because these are compiled into the static files, rebuild and redeploy the dashboard after changing them.

The dashboard's own preferences (pretty event names, default time range, compact mode) are kept in your browser. See Dashboard.

Swift Package

Each app passes its settings to Analytics.configure at launch:

Analytics.configure(
    endpoint: "https://oddlytics-worker.<your-subdomain>.workers.dev",
    apiKey: "your-auth-key",
    appId: "MyApp",
    batchSize: 10,
    batchInterval: 5.0,
    debugMode: false
)

Parameter	Default	What it does
endpoint	required	The Worker's address. Events are posted to <endpoint>/track. An address that isn't a valid URL stops the app with a fatal error.
apiKey	required	The Worker's AUTH_KEY.
appId	required	The name this app's events are stored under. The dashboard lists one app per appId.
batchSize	10	Send as soon as this many events are queued. Keep it at 100 or less, the most the Worker accepts in one request.
batchInterval	5.0	Seconds between automatic sends.
debugMode	false	Prints what the package does to the Xcode console, prefixed with [Oddlytics].

Use a different appId for each app. Two apps that share an appId show up as one app in the dashboard.