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 event and property contained within analytics outputs.
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.
See also a reference of Insights.
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 |
| 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 | Contains two properties: - notificationScenario: newCard | unsnoozedCard - rescheduledBasedOnEndUserPrefs: TRUE | FALSE | 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; or taps on 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 |
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 timezone of the customer, as an IANA timezone 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 | 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 | 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.
