CONTRACT · fidra:v1

Events

Every message the feed emits: the semantic fidra:v1 set your integration should pin to, the raw relay underneath it, the envelope, and the delivery guarantees.

LAST UPDATED 2026-07-27

Two channels, one envelope

Every message carries source: 'fidra' (from the feed) or 'fidra-host' (from you) and proto: 'fidra:v1'. Two families ride this channel:

Semantic messages — fidra:v1:<name>: a curated, contract-tested set with business-meaningful names. This is the intended integration surface.
Raw relay — fidra:v1:event: every internal analytics event, verbatim, versioned by payload.schemaVersion. Some events (e.g. card_view, breather_shown, session_end) exist only here.

Feed → host: semantic reference

message	payload	emitted when
`fidra:v1:ready`	—	frame booted; reply with `init`
`fidra:v1:session_start`	`sessionId`	once per session, before any other message
`fidra:v1:bet_placed`	`gameId, amount, roundId`	a bet was accepted
`fidra:v1:cashout`	`gameId, roundId, multiplier, win`	player cashed out
`fidra:v1:round_settled`	`gameId, roundId, payout, multiplier`	round closed — payout 0 = loss; a cashout emits this and `cashout`
`fidra:v1:open_full_mode`	`gameId`	card expanded to full mode
`fidra:v1:adapter_open`	`gameId`	a provider/catalog card opened — the attribution event
`fidra:v1:launch_request`	`ref, nonce`	feed asks you for a tokenized launch URL; echo `nonce` in your reply
`fidra:v1:catalog_report`	`report`	after catalog normalization — what was accepted/dropped and why
`fidra:v1:error`	`message`	feed-side error surfaced to host
`fidra:v1:event`	`payload: TrackedEvent`	the raw relay — every tracked event

Host → feed

message	payload	effect
`fidra:v1:init`	`{payload: config}`	apply config (reply to `ready`); no init within 5s → demo config
`fidra:v1:theme_update`	`{payload: {theme?, accent?, accent2?}}`	live re-skin
`fidra:v1:wallet_update`	`{balance}`	assert the player's displayed balance
`fidra:v1:launch_url` / `launch_error`	`{nonce, url}` / `{nonce, reason?}`	reply to `launch_request`
`fidra:v1:realtime_update`	`{channel, data}`	push live tournament/community data
`fidra:v1:currency_update`	`{payload: {code, symbol?, decimals?, position?}}`	dual-rail session-currency switch — queues during an open round (Currency)
`fidra:v1:pause`	—	RG hook: inserts a breather card now; can only add, never remove
`fidra:v1:destroy`	—	clean unmount before iframe removal

The envelope (raw relay)

field	type	notes
`seq`	number	monotonic per session, from 1 — a reliable total order within one `sessionId`
`ts`	number	epoch ms at track time
`sessionId`	string	anonymous UUID, stable for the session
`mode`	'static' \| 'engine'	which feed composition served the session
`schemaVersion`	number	the frozen contract number — branch on it if you consume raw events
`operatorId?`	string	your tenant id, present in operator embeds — the multi-tenant join key
`currency?`	string	the session currency in force at track time (dual-rail) — money fields on the event are denominated in it; stamped, never rewritten on a later switch. See Currency
`event`	FeedEvent	the event union — full catalog in `docs/integration/EVENTS.md`
`feedContext?`	object	bet-shaped events only: `cardId, cardIndex, precededBySameGame` — the recorded basis of feed-attributed GGR

Schema version. The number is CI-frozen: any field change to the envelope or any event type fails the contract test unless the version is bumped in the same commit. Read the current value from SCHEMA_VERSION in apps/web/src/analytics.ts — that file and its contract test are authoritative over any prose, including this page.

Delivery guarantees — stated plainly

Transport is postMessage, best-effort. No ack, no retry, no delivery confirmation. At-most-once, not at-least-once — do not build reconciliation that assumes redelivery.
Per-session ordering by seq within one sessionId. No cross-session ordering.
session_start fires first — no other fidra:v1:* for a session is observed before it.
One tracked event can yield 0, 1, or 2 semantic messages (a cashout yields two), plus always one raw relay message.
Messages go to the immediate parent frame only.

roundId correlation

The roundId on bet_placed is the same id used in the wallet RPC (bet_intent) — minted once per round, one open round per game. It is the single join key across analytics and money. Format: <sessionId-prefix>-<seq>.

source of truth: docs/integration/EVENTS.md · apps/web/src/analytics.ts · apps/web/src/bridge.ts fidra is a B2B software supplier — no gambling services operated, no player funds held. g.jgerenaia@tomsons.co