<!-- Kind: Integration guide. Status: Preview. Maintained with: sdk/event-collection and internal/eventcollection. Served at /user-metrics/concepts and /user-metrics/concepts.md. -->

# Shared concepts

These concepts apply whether you use an SDK or send HTTP requests yourself. Start with [Events and metrics](/user-metrics/event-design) for the collection purpose, event plan and inputs required by each daily metric.

## Collector address

All games use Coal’s shared hosted collector at `https://coal-events.fly.dev`. The ingestion key identifies the game and its owning organization. SDK integrations normally supply only the key, consent, and their app version.

All hosted games use `https://coal-events.fly.dev`; the SDK supplies this address automatically. For a local or separately hosted collector, override it explicitly:

```js
const events = await CoalEvents.init({
  consent: true,
  key: 'yourkey',
  endpoint: 'https://collector.example.com',
  appVersion: '1.0.0',
});
```

Keep the public collector URL stable when moving collector machines or databases. If the URL itself changes, existing builds need an updated endpoint/default, and the SDK uses a new local identity/queue namespace. Omitting the endpoint preserves the same namespace as explicitly supplying the default URL. Keys authorize event ingestion for the game.
## Keys and collection access

An organization administrator with access to the game manages ingestion keys in **User metrics → Setup**. **Create key** activates collection and adds an independent public key for the game, while preserving other keys and their expiry dates. New keys stay active until revoked. Deploy a new key in your game, then revoke the old key when older builds no longer need it. Revocation immediately stops delivery from builds using that key. Control event delivery through the SDK’s consent and `disable()` controls, or revoke keys in Coal to stop accepting their events. Account eligibility still determines whether ingestion is permitted.

Use the public ingestion key from Setup in your game client. Coal manages collection access for the owning organization.
## Read metrics in Coal

Open **User metrics → Setup** for the game's write-only public key. The SDK uses the shared collector automatically; its optional `endpoint` override is documented above for local or separately hosted collectors. Organization administrators create and revoke individual keys here. Use the [example integration](/static/event-collection-demo/) to grant consent, initialize the browser SDK and send a session, custom event and progression attempt. SDK diagnostics confirm accepted delivery immediately. Daily charts update after the collector's next dbt run (about 15 minutes).

Overview, Retention and Progression show daily UTC aggregates. Installation cohorts start at first observed activity. Exact-day D1/D7/D30 retention appears after the return day has ended. Sessions use maximum cumulative foreground duration, attributed to their first observed UTC day. Outstanding progression attempts appear as unresolved. Today is provisional; offline delivery can update earlier summaries.
## Aggregate access

Coal reads account/game-scoped daily metrics computed by the collector’s dbt worker. Your game client sends events using its ingestion key; users view the resulting metrics in Coal.