> For the complete documentation index, see [llms.txt](https://docs.amply.tools/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.amply.tools/concepts/sessions-and-events.md).

# Sessions and events

Amply reasons about users through two units: sessions (when the app was in use) and events (what happened during that use). Everything else — targeting rules, campaign triggers, frequency caps — is built on top of these two ideas.

## What a session is

A session is a continuous period of app usage. The SDK starts a session when the app comes to the foreground and ends it when the app goes to the background. A user with ten app-opens across a day has ten sessions.

Two kinds of session start:

* **Cold start** — the app was launched fresh (not running before).
* **Warm start** — the app was already running and returned to the foreground.

Short background trips are merged back into the same session rather than starting a new one, so a quick switch to another app and back does not inflate your session count.

On each session start the SDK emits the `SessionStarted` standard event. On session end it emits `SessionFinished`.

### Session counter

Amply keeps a running counter of how many sessions a user has had. The SDK uses it for delivery and frequency logic. The rule builder doesn't expose session count as a first-class targeting attribute — if you need to target on it, set it as a custom property from your app and reference that in the **Who** step. See [User attributes](/concepts/user-attributes.md) for how custom properties work, and [Campaign delivery](/concepts/campaign-delivery.md) for how the counter feeds frequency rules.

## What an event is

An event is a named thing that happened inside a session. It has:

* A **name** (a short string — `PurchaseCompleted`, `OnboardingStepViewed`).
* A **timestamp** (synchronized with Amply's server clock so events from different devices are comparable).
* Optional **properties** — a flat map of primitive values that describe the specifics of this occurrence (`plan: "annual"`, `price: 29.99`).

Events are what campaign triggers watch for. When an event arrives, the SDK checks every active campaign to see if that event matches the campaign's trigger.

## Standard events vs. custom events

Events fall into two buckets.

### Standard events (SDK-emitted)

The SDK emits these automatically — session start/finish, config fetch, campaign shown, custom-property changes, and more. You can target and trigger campaigns against them without writing any tracking code. For the complete list with each event's exact properties, see the [Events reference](/reference/events.md).

Standard events have the event type `system` in the dashboard and in triggering rules.

{% hint style="info" %}
Not every standard event is available as a dashboard trigger today — if you need one for campaign targeting, confirm it appears in the trigger picker before relying on it.
{% endhint %}

### Custom events (developer-emitted)

Custom events are the ones your app decides to track. They are the vocabulary your product team uses to describe what users do: `OnboardingCompleted`, `PaywallViewed`, `SearchPerformed`, `TrialStarted`.

Custom events are recorded through the SDK's `track()` API. The PM picks the name and which properties are useful; the developer wires up the call at the right moment in the app.

Plain-English example of how it lands in the dashboard:

> When a user fires the `PurchaseCompleted` event with property `plan = "annual"`, and it's their first time this session, open the thank-you deeplink.

See [Tracking events](/developer-guide/tracking-events.md) for how to call `track()` on each platform.

## Properties on events

Events carry properties. Properties take primitive values — strings, numbers, booleans. Keep property maps flat; nested objects are not supported.

A good property map describes the instance:

* `product_id: "sku_123"`
* `category: "widgets"`
* `price: 29.99`
* `source: "search_results"`

A campaign trigger can condition on property values: "fire only when `plan = annual`". See [Targeting and audiences](/concepts/targeting-and-audiences.md) for the condition vocabulary.

## Naming conventions

Consistency is more valuable than cleverness.

* Event names use `PascalCase`, property keys use `snake_case`. Keep both consistent across all custom events.
* Name events as things-that-happened, not screens: `PurchaseCompleted` beats `PurchaseScreen`.
* Keep names specific: `OnboardingStepCompleted` with a `step` property is better than `OnboardingStep1Completed`, `OnboardingStep2Completed`, etc.

## Events feed triggers

Every event, standard or custom, is available to the rule builder as a **trigger** — "when this event fires, evaluate this campaign". The trigger picker reads from the live Events catalog (see [Sessions and events (user guide)](/user-guide/sessions-and-events.md)).

To target on prior behavior — "users who already did X" — track an event when X happens and **also** set a custom property on the user (for example, `has_completed_onboarding = true`). The rule builder targets on the custom property; the event is what your app sets it from. See [User attributes](/concepts/user-attributes.md).

## What Amply does not promise about events

* Amply is not your primary product analytics tool. It records enough to evaluate rules and power targeting; it does not replace Amplitude, Mixpanel, or PostHog.
* Event delivery is best-effort and batched. Exact arrival ordering across devices is not guaranteed.

## Related

* [Tracking events](/developer-guide/tracking-events.md) — how to call `track()` in iOS, Android, and React Native
* [Targeting and audiences](/concepts/targeting-and-audiences.md) — how events become audience rules
* [Campaign delivery](/concepts/campaign-delivery.md) — how standard and custom events drive triggers and frequency
* [User attributes](/concepts/user-attributes.md) — the other half of what Amply knows about a user
* [Sessions and events (user guide)](/user-guide/sessions-and-events.md) — reading the event stream in the dashboard