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 for how custom properties work, and Campaign delivery 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.

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

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.

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 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 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)).

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.

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 — how to call track() in iOS, Android, and React Native

• Targeting and audiences — how events become audience rules

• Campaign delivery — how standard and custom events drive triggers and frequency

• User attributes — the other half of what Amply knows about a user

• Sessions and events (user guide) — reading the event stream in the dashboard