> 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 --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.amply.tools/concepts/sessions-and-events.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.