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

EventDefinitionOrigin
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.
SDK
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-sentContains two properties:
- notificationScenario: newCard | unsnoozedCard
- rescheduledBasedOnEndUserPrefs: TRUE | FALSE
Platform
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

Properties

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

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

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