Skip to main content

Analytics reference

Analytics are available through real-time API requests, batch extraction, webhooks, or Workbench download. This data is also visible in the Workbench Analytics debugger.

This guide defines each Atomic event and property contained within analytics outputs. This guide does not include any custom events you might have set up.

Analytic events relate to card instances

Analytic events described below relate to card instances, not card templates.

The analytics schema defines the structure of analytics events.

We also have a page listing examples for each of the analytic events. The response payloads in your environment might look different, depending on your analytics settings.

Read the guide to Insights to learn about the out-of-the-box card metrics dashboard Atomic offers.


card-cancelledWhen card status changed to cancelled. Card status changes are explained in the Card Lifecycle Model.Platform
card-completedWhen card status changed to completed. Card status changes are explained in the Card Lifecycle Model.Platform
card-dismissedWhen a card status changed to dismissed. Card status changes are explained in the Card Lifecycle Model.Platform
card-displayedTracks on:
- customer scroll (once scrolling settles)
- first load of card list
- when new cards come in due to polling or WebSockets push.
Records an impression for all visible cards, and does not de-dupe impressions.
card-embargoedWhen card status changed to embargoed. Card status changes are explained in the Card Lifecycle Model.Platform
card-errorWhen an internal error prevents Atomic from assembling a card.Platform
card-expiredWhen card status changed to expired. Card status changes are explained in the Card Lifecycle Model.Platform
card-publishedWhen a card is successfully sent, and status changed to active. Card status changes are explained in the Card Lifecycle Model.Platform
card-snoozedWhen card status changed to snoozed.Card status changes are explained in the Card Lifecycle Model.Platform
card-subview-displayedTracks when the subview is opened.SDK
card-subview-exitedTracks when the customer leaves the subview, either by navigating back or submitting the card.SDK
card-unsnoozedWhen card status changed to unsnoozed.Card status changes are explained in the Card Lifecycle Model.Platform
card-voted-downTracks when the customer taps the “Submit” button on the card feedback screen. The message field is populated if the feedback reason is other.SDK
card-voted-upTracks when the customer taps on the “This is useful” option in the card overflow menu.SDK
notification-receivedTracks when a push notification is received on the customer’s device. This is exposed as a method in the SDK that integrators need to call.SDK
notification-sentTracks when a push notification is sent. Contains two properties:
- notificationScenario: newCard | unsnoozedCard (to indicate whether the notification was sent for a new or snoozed card)
- rescheduledBasedOnEndUserPrefs: TRUE | FALSE (to indicate if the notification was rescheduled due to user delivery preferences)
request-failedCalled when any API request to our client API fails in the SDK. Also called when the WebSockets failed to function and fall back to HTTP polling.SDK
runtime-vars-updatedTracks on a per card basis when a card containing runtime variables has one or more runtime variables resolved. The property resolvedVariables contains the values used for all runtime variables. If a variable is not resolved by the host app for a card, its default value is reported here.SDK
snooze-options-canceledTracks when the customer taps the “Cancel” button in the snooze UI.SDK
snooze-options-displayedTriggers when the snooze date/time selection UI is displayed.SDK
stream-displayedTriggers when the card list is first loaded or returned to.SDK
user-redirectedTracks when the customer: opens a URL on a link button; opens a URL after submitting a card; or taps on a link or submit button with a custom action payload.SDK
segment-enteredTracks when a customer enters a segment.Platform
segment-exitedTracks when a customer exits a segment.Platform
sdk-initializedTracks when an instance of the SDK is initialized.SDK
video-playedTracks when a user hits the play button of a video.SDK
video-completedTracks when a video finishes playing.SDK
action-flow-startedTracks when the Action Flow start step runs for a flow instance.Platform
action-flow-step-completedTracks when any Action Flow step evaluation successfully completes.Platform
action-flow-completedTracks when an Action Flow completes as explained in the Action Flow Lifecycle Model.Platform

Displaying a card - events

Not all events listed above will occur every time a card is sent, but a few of them must occur before a card is displayed in a stream container and thus becomes visible to a customer.
These events are highlighted in green in the diagram below, showing the events that occur from sending a card to the card displayed on the customer's device.
The diagram also shows what events are driven by the platform versus customer actions.

Display card events

Sequence of events that result in a card displaying on a customer's device.

Interacting with a card - events

Once a card is displayed on a customer's screen, they can interact with it in many ways, in no particular order.
Some of these interactions will only be possible for some cards (e.g. video-displayed can only occur when the card contains a video).
Some of these interactions can happen more than once for the same card (e.g. watching a video more than once).
None of these actions are required. As long as a card is displayed in the stream, a customer can keep interacting with it.

Card interaction events

Possible events when a customer interacts with a card.

Removing a card from a stream - events

There are 4 distinct actions that result in the removal of card from a stream container. Each of these actions are mutually exclusive: once a customer has completed a card, it is no longer possible to dismiss, cancel or expire this card.
Any of these actions will change the card's state to closed as explained in the card lifecycle model.

Card close events

Events that change a card's state to closed.


The following top-level properties are contained in every analytics event.

idStringA unique id for this event.
endUserIdStringThe customer identifier known to Atomic.
analyticsEventStringName of the event in snake_case.
timestampDateTimeThe UTC timestamp of when the event occurred.
propertiesObjectExtra detail about this particular event.
hostContextObjectReturns {}. Support for host-supplied customer properties is coming soon.
eventContextObjectDetails of the source that triggered the event.
sdkContextObjectInformation about the SDK related to this event.
streamContextObjectDetails of the stream at the time the event occurred.
cardContextObjectDetails of the card in context of this event.
platformContextObjectDetails of the Action Flow and payload associated with this event.


Within the properties the following sub-properties are available. Note: sub-properties are only returned when available/relevant to a specific event.

Attribute parentPropertyValueDescription
sdkContextplatformWeb | iOS | AndroidThe platform the customer is using.
sdkContextsdkVersionnumberThe version of the SDK being used.
sdkContextsdkDevicestringFor iOS and Android, reports the operating system version and the device’s model identifier. For Web, reports the browser’s user agent.
sdkContextsdkDeviceInfostringProvides detailed device info parsed from the sdkDevice string, including mobile device names where applicable.
sdkContextsdkTimezonetimezoneThe timezone of the customer, as an IANA timezone name.
sdkContextcontainerIdnumberThe container ID.
sdkContextisDnDActiveTRUE | FALSEWhether the customer’s do not disturb settings are active.
streamContextdisplayModestream | singleThe display mode of the customer: either stream or single.
streamContextstreamIdnumberThe stream ID.
streamContextstreamNamestringThe stream name.
streamContextstreamLengthVisiblenumberIn a stream: The number of cards in the stream, and is the same as streamLength. In single card view: either 0 or 1. streamLength reports the total number of cards in the stream
streamContextcardPositionInStreamnumberPosition of card in stream at the time of the event (starting from 1).
cardContextcardInstanceIdstringA unique ID that identifies this card for the user instance.
cardContextcardInstanceStatuscontextStatus of card at time of event: active | embargoed | completed | suppressed | dismissed | completed | snoozed | expired.
cardContextcardViewStatetopview | subviewWhere the customer was in the SDK when the event occurred.
cardContextcardTemplateIdstringThe card template ID used to generate this unique card instance.
cardContextcardTemplateNamestringName of the card template used to generate this unique card instance.
cardContextcardTemplateVersionnumberThe version of the card template used to generate this unique card instance.
cardContextcardPresentationbundle | individualAlways reported as ‘individual’ currently.
cardContextcardTemplateSettings{"sendNotifications": true | false }Card-template specific settings.
cardContextpublishedAttimestampThe date and time that the card instance was published.
cardContextcardPriority1-10The priority assigned to the card template.
platformContextlifecycleIdstringA unique ID associated with the card instance auto-generated by Atomic.
platformContexttargetStreamIdsarrayThe streams that are associated with this event.
platformContexttargetPlatformsarrayThe platforms that the associated card instance will display in.
platformContexttriggerEventSourcelive | testDenotes whether the event is derived from a test card sent via the Workbench.
platformContexteventDetailobjectThe data included in the request that triggered a flow or card to be created i.e. variable values.
platformContextflowConfigIdstringThe Action Flow configuration associated with this event.
platformContextflowInvocationIdstringReference to the invocation (e.g. api request) which triggered the Action Flow associated with this event.
platformContextflowInstanceIdstringThe Action Flow instance which is associated with this event.
platformContextflowVersionnumberThe version of the Action Flow that triggered this event.
platformContextmetadataobjectArbitrary metadata passed through from the originating API call.
platformContexteventNotificationDetailobjectThe event notification data.
eventContextactionSourceinternal | user | customerThe source of the event. Internal - caused by internal platform processing. Customer - caused by API request. User - caused by SDK interactions.
eventContextipstringThe IP address associated with the event.
eventContextuserLocalTimestampstringThe local timestamp of the user associated with the event.

Config id, invocation id and instance id

Take the example of one Action Flow configuration, containing two cards, that is sent to two customers. The Action Flow is sent via a single invocation (API request). In the diagram below, all separate boxes have unique identifiers. These identifiers flow through from left to right, meaning that the upper right card instance (card A for user 1) has the following identifiers:

  • its own cardInstanceId
  • the Action Flow instance id that was sent to user 1
  • the Action Flow invocation id for the Action Flow that was sent to 2 users, with a specific timestamp
  • the Action Flow config id (the blueprint of the Action Flow)

These identifiers are returned as properties or subproperties in the analytics events described above, or when querying specific API endpoints.

Note: Action Flows can only have 1 card at the moment, but this will soon be expanded to multiple cards.