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.
Events
| Event | Definition | Origin |
|---|---|---|
| card-cancelled | When card status changed to cancelled. Card status changes are explained in the Card Lifecycle Model. | Platform |
| card-completed | When card status changed to completed. Card status changes are explained in the Card Lifecycle Model. | Platform |
| card-dismissed | When a card status changed to dismissed. Card status changes are explained in the Card Lifecycle Model. | Platform |
| card-displayed | Tracks 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. | SDK |
| card-embargoed | When card status changed to embargoed. Card status changes are explained in the Card Lifecycle Model. | Platform |
| card-error | When an internal error prevents Atomic from assembling a card. | Platform |
| card-expired | When card status changed to expired. Card status changes are explained in the Card Lifecycle Model. | Platform |
| card-published | When a card is successfully sent, and status changed to active. Card status changes are explained in the Card Lifecycle Model. | Platform |
| card-snoozed | When card status changed to snoozed.Card status changes are explained in the Card Lifecycle Model. | Platform |
| card-subview-displayed | Tracks when the subview is opened. | SDK |
| card-subview-exited | Tracks when the customer leaves the subview, either by navigating back or submitting the card. | SDK |
| card-unsnoozed | When card status changed to unsnoozed.Card status changes are explained in the Card Lifecycle Model. | Platform |
| card-voted-down | Tracks 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-up | Tracks when the customer taps on the “This is useful” option in the card overflow menu. | SDK |
| card-not-sent | Tracks when a card was configured to be sent but was not delivered by the platform. Reasons for this include the card having an expiry date in the past. | Platform |
| card-first-displayed | A synthetic card-event which tracks when a specific card is displayed to the customer for the first time only. This event is emitted alongside a 'card-displayed' event. | Platform |
| card-first-snoozed | A synthetic card-event which tracks when a card is snoozed for the first time by a customer. This event is emitted in addition to a 'card-snoozed' event. | Platform |
| card-first-voted | A synthetic card-event which tracks when a card is voted up or down for the first time by a customer. This event is emitted in addition to either a 'card-voted-up' or 'card-voted-down' event. | Platform |
| user-first-redirected | A synthetic card-event which tracks when a user is redirected by a given card for the first time. This event is emitted in addition to the 'user-redirected' event. | Platform |
| notification-received | Tracks 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-sent | Tracks 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) | Platform |
| notifications-not-sent | Tracks when a push notification is configured to be sent, but is not sent for any reason on the Atomic platform side. | Platform |
| request-failed | Called 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-updated | Tracks 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-canceled | Tracks when the customer taps the “Cancel” button in the snooze UI. | SDK |
| snooze-options-displayed | Triggers when the snooze date/time selection UI is displayed. | SDK |
| stream-displayed | Triggers when the card list is first loaded or returned to. | SDK |
| user-redirected | Tracks when the customer: opens a URL on a link button; opens a URL after submitting a card; opens a URL on an image; or taps on an image, or a link or submit button with a custom action payload. | SDK |
| segment-entered | Tracks when a customer enters a segment. | Platform |
| segment-exited | Tracks when a customer exits a segment. | Platform |
| sdk-initialized | Tracks when an instance of the SDK is initialized. | SDK |
| video-played | Tracks when a user hits the play button of a video. | SDK |
| video-completed | Tracks when a video finishes playing. | SDK |
| action-flow-started | Tracks when the Action Flow start step runs for a flow instance. | Platform |
| action-flow-step-completed | Tracks when any Action Flow step evaluation successfully completes. | Platform |
| action-flow-step-failed | Tracks when any Action Flow step evaluation fails to complete. | Platform |
| action-flow-completed | Tracks when an Action Flow completes as explained in the Action Flow Lifecycle Model. | Platform |
| action-flow-failed | Tracks when an Action Flow fails as explained in the Action Flow Lifecycle Model. | Platform |
| action-flow-cancelled | Tracks when an Action Flow is cancelled. Detailed behaviour is explained in the Action Flow Lifecycle Model. | Platform |
| action-flow-not-started | Tracks when an Action Flow was not initiated as expected. Possible reasons include the payload being invalid or re-use of an invocation id. | Platform |
| action-flow-trigger-request-failed | Called when a trigger request for an Action Flow fails, preventing the flow from starting. This usually occurs when the payload doesn't match the expected format. | Platform |
| action-flow-trigger-successful | Tracks when a trigger successfully initiates an Action Flow. This doesn't guarantee that the flow will complete successfully. | Platform |
| action-flow-wait-completed | Tracks when a wait step in an Action Flow completes successfully, allowing the flow to proceed. | 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.
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.
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.
Properties
The following top-level properties are contained in every analytics event.
| Attribute | Format | Description |
|---|---|---|
| id | String | A unique id for this event. |
| endUserId | String | The customer identifier known to Atomic. |
| analyticsEvent | String | Name of the event in snake_case. |
| timestamp | DateTime | The UTC timestamp of when the event occurred. |
| properties | Object | Extra detail about this particular event. |
| hostContext | Object | Returns . Support for host-supplied customer properties is coming soon. |
| eventContext | Object | Details of the source that triggered the event. |
| sdkContext | Object | Information about the SDK related to this event. |
| streamContext | Object | Details of the stream at the time the event occurred. |
| cardContext | Object | Details of the card in context of this event. |
| platformContext | Object | Details of the Action Flow and payload associated with this event. |
Sub-properties
Within the properties the following sub-properties are available. Note: sub-properties are only returned when available/relevant to a specific event.
| Attribute parent | Property | Value | Description |
|---|---|---|---|
| sdkContext | platform | Web | iOS | Android | The platform the customer is using. |
| sdkContext | sdkVersion | number | The version of the SDK being used. |
| sdkContext | sdkDevice | string | For iOS and Android, reports the operating system version and the device’s model identifier. For Web, reports the browser’s user agent. |
| sdkContext | sdkDeviceInfo | string | Provides detailed device info parsed from the sdkDevice string, including mobile device names where applicable. |
| sdkContext | sdkTimezone | timezone | The time zone of the customer, as an IANA time zone name. |
| sdkContext | containerId | number | The container ID. |
| sdkContext | isDnDActive | TRUE | FALSE | Whether the customer’s do not disturb settings are active. |
| streamContext | displayMode | stream | single | The display mode of the customer: either stream or single. |
| streamContext | streamId | number | The stream ID. |
| streamContext | streamName | string | The stream name. |
| streamContext | streamLengthVisible | number | In 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 |
| streamContext | cardPositionInStream | number | Position of card in stream at the time of the event (starting from 1). |
| cardContext | cardInstanceId | string | A unique ID that identifies this card for the user instance. |
| cardContext | cardInstanceStatus | context | Status of card at time of event: active | embargoed | completed | suppressed | dismissed | completed | snoozed | expired. |
| cardContext | cardViewState | topview | subview | Where the customer was in the SDK when the event occurred. |
| cardContext | cardTemplateId | string | The card template ID used to generate this unique card instance. |
| cardContext | cardTemplateName | string | Name of the card template used to generate this unique card instance. |
| cardContext | cardTemplateVersion | number | The version of the card template used to generate this unique card instance. |
| cardContext | cardPresentation | bundle | individual | Always reported as ‘individual’ currently. |
| cardContext | cardTemplateSettings | {"sendNotifications": true | false } | Card-template specific settings. |
| cardContext | publishedAt | timestamp | The date and time that the card instance was published. |
| cardContext | cardPriority | 1-10 | The priority assigned to the card template. |
| platformContext | lifecycleId | string | A unique ID associated with the card instance auto-generated by Atomic. |
| platformContext | targetStreamIds | array | The streams that are associated with this event. |
| platformContext | targetPlatforms | array | The platforms that the associated card instance will display in. |
| platformContext | triggerEventSource | live | test | Denotes whether the event is derived from a test card sent via the Workbench. |
| platformContext | eventDetail | object | The data included in the request that triggered a flow or card to be created i.e. variable values. |
| platformContext | flowConfigId | string | The Action Flow configuration associated with this event. |
| platformContext | flowInvocationId | string | Reference to the invocation (e.g. api request) which triggered the Action Flow associated with this event. |
| platformContext | flowInstanceId | string | The Action Flow instance which is associated with this event. |
| platformContext | flowVersion | number | The version of the Action Flow that triggered this event. |
| platformContext | cardCreationStepId | string | For card-centric events, the Id of the Action Flow step which created the card |
| platformContext | stepId | string | The ID of the Action Flow step which generated, or is causally tied to this event. |
| platformContext | stepType | string | The type of the Action Flow step which generated, or is causally tied to this event e.g. 'create-card' or 'condition'. |
| platformContext | metadata | object | Arbitrary metadata passed through from the originating API call. |
| platformContext | eventNotificationDetail | object | The event notification data. |
| eventContext | actionSource | internal | user | customer | The source of the event. Internal - caused by internal platform processing. Customer - caused by API request. User - caused by SDK interactions. |
| eventContext | ip | string | The IP address associated with the event. |
| eventContext | userLocalTimestamp | string | The 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.
