Analytics

Table of Contents

1. Event Types
2. Story Events
3. Clip Events
4. Ad Events
5. Event Data

Event Types

These are the various events which are triggered from within the SDK. Each event is a member of the UserActivity.EventType enumeration. Please see the StorytellerDelegate page for details on how to bind to these events.

In the below discussion, "completing" a Page refers to allowing the timer to expire - so this would correspond to watching all of an Image Page for the duration set for it (default 15s) or watching all of a video.

Story Events

Opened Story

This event is recorded in the following scenarios:

• When a user taps on a row item to open a Story
• When a Story is loaded because the previous Story finished
• When a Story is loaded because the user tapped to skip the last Page of the previous Story
• When a user swipes left on a Story to go to the next Story
• When a user swipes right on a Story to go to the previous Story
• When a user is sent directly to a Story via a deeplink

Whenever an Opened Story event occurs, event data for storyID, storyTitle, storyIndex, storyPageCount, storyReadStatus, storyPlaybackMode, openedReason, currentCategory and categories is returned.

Opened Page

This event is recorded whenever a user views content from a Page.

Opened Page is one of the most important events to track as it is equal to a video start, one of the most important measures of engagement. By tracking this event, you can monitor valuable information about user engagement with your app.

Whenever an Opened Page event occurs, event data for pageID, pageIndex, pageType, storyPlaybackMode, pageHasAction, pageActionText, pageActionUrl contentLength, storyID, storyTitle, storyIndex, storyPageCount, currentCategory and openedReason is returned.

Dismissed Story

This event is recorded in the following scenarios:

• When a user taps the close button to dismiss the Story
• When a user swipes down to dismiss the Story
• When a user taps to skip the last Page of the final Story - this dismisses the Story and exits the Story View
• When a user swipes left on the final Story to dismiss the Story
• When a user swipes right on the first Story to dismiss the Story
• When a user completes the final Page of the final Story and the Story view is dismissed

Whenever a Dismissed Story event occurs, event data for storyId, storyTitle, storyIndex, storyPageCount storyPlaybackMode, pageID, pageIndex, pageType dismissedReason, durationViewed, currentCategory and pagesViewedCount is returned.

Skipped Story

This event is recorded when:

• a user swipes left to go to the next Story
• a user skips the last Page of a Story to go to the next Story

Whenever a Skipped Story event occurs, event data for storyId, storyTitle, storyIndex, storyPageCount storyPlaybackMode, pageID, pageIndex, currentCategory and pageType is returned.

Skipped Page

This event is recorded when a user taps to go to the next Page before completing the current Page.

Whenever a Skipped Page event occurs, event data for storyId, storyTitle, storyIndex, storyPageCount storyPlaybackMode, pageID, pageIndex, currentCategory and pageType is returned.

Completed Story

This event is recorded at the same time as OpenedPage for the final Page in a Story.

Whenever a Completed Story event occurs, event data for storyId, storyTitle, storyIndex, storyPageCount storyPlaybackMode, pageID, pageIndex, currentCategory and pageType is returned.

Completed Page

This event is recorded when a user watches a Page to completion (i.e. the timer for that Page finishes.)

Whenever a Completed Page event occurs, event data for storyId, storyTitle, storyIndex, storyPageCount storyPlaybackMode, pageID, pageIndex, pageType, currentCategory and contentLength is returned.

Action Button Tapped

This event is recorded in the following scenarios:

• When a user taps an Action Button on a Page to open a link

Whenever a Action Button Tapped event occurs, event data for storyId, storyTitle, storyIndex, storyPageCount storyPlaybackMode, pageID, pageIndex, pageType, pageHasAction, pageActionText, currentCategory and pageActionUrl is returned.

Share Button Tapped

This event is recorded when a user taps the share button on a Page.

Whenever a Share Button Tapped event occurs, event data for shareMethod, storyId, storyTitle, storyIndex, storyPageCount storyPlaybackMode, pageID, pageIndex, currentCategory and pageType is returned.

Previous Story

This event is recorded when:

• a user swipes right to go to the previous Story (unless this is the first Story - in which case DismissedStory is fired instead)
• a user taps back on the first Page in a Story (and this is not the first Page is the first Story)

Whenever a Previous Story event occurs, event data for storyId, storyTitle, storyIndex, storyPageCount storyPlaybackMode, pageID, pageIndex, currentCategory and pageType is returned.

Previous Page

This event is recorded when a user taps back to go to a previous Page in the Story.

Whenever a Previous Page event occurs, event data for storyId, storyTitle, storyIndex, storyPageCount storyPlaybackMode, pageID, pageIndex, currentCategory and pageType is returned.

Share Success

This event is recorded when a user:

• selects a sharing method from the system dialog.

Whenever a Share Success event occurs, event data for storyId, storyTitle, storyIndex, storyPageCount storyPlaybackMode, pageID, pageIndex, pageType, currentCategory and shareMethod is returned.

Voted Poll

This event is recorded when user votes in a poll.

Whenever a Voted Poll event occurs, event data for storyId, storyTitle, storyIndex, pageId, pageIndex, pageType, currentCategory and pollAnswerId is returned.

Trivia Quiz Question Answered

This event is recorded when a user answers a question in a trivia quiz.

Whenever a Trivia Quiz Question Answered event occurs, event data for storyId, storyTitle, storyIndex, storyPlaybackMode, pageID, pageIndex, pageType, triviaQuizId, triviaQuizTitle, triviaQuizQuestionId, currentCategory and triviaQuizAnswerId is returned.

Trivia Quiz Completed

This event is recorded when a user completes a trivia quiz.

Whenever a Trivia Quiz Completed event occurs, event data for storyId, storyTitle, storyIndex, storyPlaybackMode, pageID, pageIndex, pageType, triviaQuizId, triviaQuizTitle, triviaQuizScore and currentCategory is returned.

Clip Events

Opened Clip

This event is recorded when:

• a user taps on a row or grid item to open a Clip
• a user swipes up to the next Clip
• a user swipes down to the previous Clip
• a user is sent directly to a Clip via a call to openCollection
• a user is sent directly to a Clip via a deep link

Whenever a Opened Clip event occurs, event data for clipId, clipTitle, clipIndex, clipHasAction, openedReason, collection, categories, contentLength and categoryDetails is returned.

Dismissed Clip

This event is recorded when:

• a user taps on the back button in the top-left to exit the Clips player

Whenever a Dismissed Clip event occurs, event data for clipId, clipTitle, clipIndex, dismissedReason, durationViewed, clipsViewed, collection, categories and loopsViewed is returned.

Next Clip

This event is recorded when:

• a user swipes up to go to the next Clip

Whenever a Next Clip event occurs, event data for clipId, clipTitle, collection, categories and clipIndex is returned.

Previous Clip

This event is recorded when:

• a user swipes down to go to the previous Clip

Whenever a Previous Clip event occurs, event data for clipId, clipTitle, collection, categories and clipIndex is returned.

Completed Loop

This event is recorded when:

• a user completes a loop of a Clip

Whenever a Completed Loop event occurs, event data for clipId, clipTitle, collection, categories and clipIndex is returned.

Action Button Tapped

This event is recorded when:

• a user taps the action button at the bottom of a Clip
• a user swipes left on a Clip to open the relevant action

Whenever a Action Button Tapped event occurs, event data for clipId, clipTitle, clipIndex, clipHasAction, clipActionText, collection, categories and clipActionUrl is returned.

Share Button Tapped

This event is recorded when:

• a user taps the share button on a Clip

Whenever a Share Button Tapped event occurs, event data for clipId, clipTitle, collection, categories and clipIndex is returned.

Share Success

This event is recorded when:

• a user selects and successfully shares a page from the system dialog

Whenever a Share Success event occurs, event data for clipId, clipTitle, clipIndex, collection, categories and shareMethod is returned.

Paused Clip

This event is recorded when:

• a user taps on the screen whilst a Clip is playing to pause the Clip - it does not fire when a Clip is paused automatically by sharing or following an action

Whenever a Paused Clip event occurs, event data for clipId, clipTitle, collection, categories and clipIndex is returned.

Resumed Clip

This event is recorded when:

• a user taps a Clip that is paused to resume playback - it does not fire when a Clip is resumed automatically

Whenever a Resumed Clip event occurs, event data for clipId, clipTitle, collection, categories and clipIndex is returned.

Liked Clip

This event is recorded when:

• a user likes a Clip by tapping the like button when they do not currently like the Clip

Whenever a Liked Clip event occurs, event data for clipId, clipTitle, collection, categories and clipIndex is returned.

Unliked Clip

This event is recorded when:

• a user unlikes a Clip by tapping the like button when they currently like the Clip

Whenever a Unliked Clip event occurs, event data for clipId, clipTitle, collection, categories and clipIndex is returned.

Finished Clip

This event is recorded when:

• Dismissed Clip is fired
• Next Clip is fired
• Previous Clip is fired

Whenever a Finished Clip event occurs, event data for clipId, clipTitle, clipIndex, loopsViewed, durationViewed, collection, categories and contentLength is returned.

Ad Events

Opened Ad

This event is recorded when:

• an ad is loaded because the previous Story finished
• a user swipes left on a Story to go to the next Story and an ad appears
• a user swipes right on a Story to go to the previous Story and an ad appears

Whenever a Opened Ad event occurs, event data for advertiserName, adId, pageType, openedReason, adView, contentLength, pageHasAction, pageActionText, currentCategory and pageActionUrl is returned.

Dismissed Ad

This event is recorded when a user:

• taps close to dismiss the ad
• swipes down to dismiss the ad
• taps back on their device UI to dismiss the ad (Android only)
• taps to skip the ad if the ad is the last Page in the current set of Stories
• swipes left on the ad to skip it if the ad is the last Page in the current set of Stories
• completes the ad if the ad is the last Page in the current set of Stories

Whenever a Dismissed Ad event occurs, event data for advertiserName, adId, pageType, dismissedReason, durationViewed, pagesViewed, pageHasAction, pageActionText, currentCategory and pageActionUrl is returned.

Skipped Ad

This event is recorded when a user:

• swipes left to go to the next Story before completing the current ad
• taps to go to the next Page on an ad before completing the current ad

Whenever a Skipped Ad event occurs, event data for advertiserName, adId, pageType, contentLength, pageHasAction, pageActionText, currentCategory and pageActionUrl is returned.

Ad Action Button Tapped

This event is recorded when a user:

• swipes up on an ad to open a link
• taps on the swipe up element of an ad to open a link

Whenever a Ad Action Button Tapped event occurs, event data for advertiserName, adId, pageType, pageHasAction, pageActionText, currentCategory and pageActionUrl is returned.

Previous Ad

This event is recorded when a user:

• swipes right to go to the previous Story when viewing an ad
• taps back to go to the previous Page when viewing an ad

Whenever a Previous Ad event occurs, event data for advertiserName, adId, pageType, contentLength, pageHasAction, pageActionText, currentCategory and pageActionUrl is returned.

Finished Ad

This event is recorded at the same time as Dismissed Ad, Skipped Ad, Previous Ad and Viewed Ad Page Complete and gives an easier way to determine when an ad finishes for any reason.

Whenever a Finished Ad event occurs, event data for advertiserName, adId, pageType, adView, contentLength, pageHasAction, pageActionText, currentCategory and pageActionUrl is returned.

Paused Ad Page

This event is recorded when a user pauses a Page within an ad by pressing and holding on the Page.

Whenever a Paused Ad Page event occurs, event data for advertiserName, adId, pageType, contentLength, pageHasAction, pageActionText, currentCategory and pageActionUrl is returned.

Resumed Ad Page

This event is recorded when a user resumes playing a Page within an ad by releasing their long press which paused the ad.

Whenever a Resumed Ad Page event occurs, event data for advertiserName, adId, pageType, contentLength, pageHasAction, pageActionText, currentCategory and pageActionUrl is returned.

Viewed Ad Page First Quartile

This event is recorded when a user reaches 1/4 of the way through the duration of a Page which is within an ad.

Whenever a Viewed Ad Page First Quartile event occurs, event data for advertiserName, adId, pageType, contentLength, pageHasAction, pageActionText, currentCategory and pageActionUrl is returned.

Viewed Ad Page Midpoint

This event is recorded when a user reaches halfway through the duration of a Page which is within an ad.

Whenever a Viewed Ad Page Midpoint event occurs, event data for advertiserName, adId, pageType, contentLength, pageHasAction, pageActionText, currentCategory and pageActionUrl is returned.

Viewed Ad Page Third Quartile

This event is recorded when a user reaches 3/4 of the way through the duration of a Page which is within an ad.

Whenever a Viewed Ad Page Third Quartile event occurs, event data for advertiserName, adId, pageType, contentLength, pageHasAction, pageActionText, currentCategory and pageActionUrl is returned.

Viewed Ad Page Complete

This event is recorded when a user reaches the end of the duration for a Page which is within an ad.

Whenever a Viewed Ad Page Complete event occurs, event data for advertiserName, adId, pageType, contentLength, pageHasAction, pageActionText, currentCategory and pageActionUrl is returned.

Playback Events

Ready to Play

This event is called once per Video Page at the point when the video player has been loaded.

Whenever a Ready to Play event occurs, event data for storyId, storyTitle, storyIndex, pageID, pageIndexand pageType is returned.

Media Started

This event is called once per Video Page at the point when the video starts to play for the first time.

Whenever a Media Started event occurs, event data for storyId, storyTitle, storyIndex, pageID, pageIndexand pageType is returned.

Buffering Started

This event is called on Video Pages whenever the video starts to buffer.

Whenever a Buffering Started event occurs, event data for storyId, storyTitle, storyIndex, pageID, pageIndex, pageType and isInitialBuffering is returned.

Buffering Ended

This event is called on Video Pages whenever the video finishes buffering.

Note: There should be at most one Ready to Play event and one Media Started event for every Page. There may be multiple Buffering Started/Buffering Ended pairs of events for an individual Page. There may not always be a Buffering Ended event for every Buffering Started event as the user may choose to exit the Page during buffering.

Whenever a Buffering Ended event occurs, event data for storyId, storyTitle, storyIndex, pageID, pageIndex, pageType, isInitialBuffering and timeSinceBufferingBegan is returned.

Event Data

For each event, data is returned with details about the Story and Page involved as well as some extra properties with more information about what the user has done. The data is returned as a UserActivityData class with the following properties:

Story ID

The storyId: String? is the ID of the Story for which the event occurred.

Story Title

The storyTitle: String? is the title of the Story for which the event occurred.

Story Index

The storyIndex: Int? is the index of the Story for which the event occurred in the row from which it was opened at the point it was opened - this is only included on OpenedStory events. Note: this value is 1-based.

Story Page Count

The storyPageCount: Int? is the number of Pages in the Story.

Story Read Status

The storyReadStatus: String? is whether the Story was read or unread at the point the Story was opened - this is only included on OpenedStory events. Note this will either be read or unread.

Page ID

The pageId: String? is the ID of the Page for which the event occurred.

Page Index

The pageIndex: Int? is the index of the Page in the Story for which the event occurred. Note: this value is 1-based.

Page Type

The pageType: String? is the type of the Page associated with the event. This can have the value image, video or poll.

Story Playback Mode

The storyPlaybackMode: String? value states if the Story was opened during the list or in the single Story mode (Storyteller static method.) This is included for all events. The values for this are either list or singleStory.

Page Has Action

The pageHasAction: Bool? value states whether the Page associated with the event contains a swipe up link.

Page Action Text

The pageActionText: String? is the text call to action if the Page has an Action.

Page Action URL

The pageActionUrl: String? is the URL for the link if the Page has an Action.

Opened Reason

The openedReason: String? value states how the user opened a Story or Clip. The possible values for this are storyRowTap (the user tapped the Story in the Story row); deepLink (openStory or openPage was called to open the Story); swipe (the user swiped left or right to change the current Story); automaticPlayback (the user completed the previous Page); tap (the user tapped on the previous Page to navigate to this Page) and clipListTap (the user tapped the Clip in a Clip list).

openedReason is only included on OpenedStory and OpenedClip events.

Dismissed Reason

The dismissedReason: String? value states the way the user dismissed a Story or Clip. The possible values for this are closeButtonTapped (the user tapped close to dismiss the Story); swipedDown (the user swiped down to dismiss the Story); swipedFirstStory (the user swiped the first Story to dismiss it); swipedFinalStory (the user swiped the final Story to dismiss it); skippedFinalPage (the user tapped to skip the final Page of the final Story); completedFinalPage (the user completed the final Page of the final Story) and backButtonTapped (the user tapped the back button to dismiss the Clip).

dismissedReason is only included on DismissedStory and DismissedClip events.

Duration Viewed

The durationViewed: Float? is the duration the user viewed the Story or Clip for in milliseconds. This is measured from the most recent OpenedStory or OpenedClip event with an Opened Reason of storyRowTap, deepLink or clipsListTap.

This timer is reset after any DismissedStory or DismissedClip events.

For FinishedClip, Duration Viewed is the the duration the user viewed the Clips player for in milliseconds. This is measured from the most recent OpenedClip event with an Opened Reason of swipe.

Pages Viewed Count

The pagesViewedCount: Int? is the total number of Pages a user has viewed since the most recent OpenedStory event with an Opened Reason of storyRowTap or deepLink. This count is reset after any DismissedStory events.

Content Length

The contentLength: Int? is the total duration of the Page content in seconds.

Advertisers Name

The advertiserName: String? is the name of the advertiser for a particular ad. This is only included for ad events.

Ad ID

The adId: String? is the ad ID if an event is associated with an ad.

Share Method

The shareMethod: String? is the component name of the app which the user has selected for sharing.

Ad View

The adView: View? is the view the ad is rendered in. This is only included for OpenedAd and FinishedAd events.

Is Initial Buffering

The isInitialBuffering: Boolean? value is returned if the buffering happens at the start of playback for that Page. This is only included for BufferingStarted and BufferingEnded events.

Time Since Buffering Began

The timeSinceBufferingBegan: TimeInterval? value is the duration the current buffering lasted for in milliseconds. This is only included for BufferingEnded events.

Categories

The categories: [String]? value is the list of categories assigned to the Story for which the event occurred. This is only included on OpenedStory events.

Poll Answer

The pollAnswerId: String? is the ID of the answer the user selected when voting. This is only included on VotedPoll events.

Trivia Quiz ID

The triviaQuizId: String? is the ID of the Trivia Quiz that was completed or answered. This is only included on TriviaQuizQuestionAnswered and TriviaQuizCompleted events.

Trivia Quiz Title

The triviaQuizTitle: String? is the title of the Trivia Quiz that was completed or answered. This is only included on TriviaQuizQuestionAnswered and TriviaQuizCompleted events.

Trivia Quiz Score

ThetriviaQuizScore: Int? value is the score of the trivia quiz that was completed. This is only included on TriviaQuizCompleted events.

Trivia Quiz Question ID

The triviaQuizQuestionId: String? is the ID of the trivia quiz question which was answered. This is only included on TriviaQuizQuestionAnswered events.

Trivia Quiz Answer ID

The triviaQuizAnswerId: String? is the ID of the selected trivia quiz answer. This is only included on TriviaQuizQuestionAnswered events.

Clip ID

The clipId: String? is the ID of the Clip for which the event occurred.

Clip Title

The clipTitle: String?is the title of the Clip for which the event occurred.

Clip Index

The clipIndex: Int? is the index of the Clip in the row or grid at the point it was selected or the index of the Clip in the feed at the point it was viewed.

Clips Viewed

The clipsViewed: Int? value is the total number of Clips a user has viewed since the most recent OpenedClip event with an Opened Reason of clipListTap or deepLink. This count should be reset after any DismissedClip events.

Loops Viewed

The loopsViewed: Int? is for DismissedClip, the total number of loops (plays of an individual Clip) a user has viewed since the most recent OpenedClip event with an Opened Reason of clipListTap or deepLink.

This count should be reset after any DismissedClip events. For FinishedClip, the total number of loops.

Clip Has Action

The clipHasAction: Bool? value is whether the Clip associated with the event contains an action.

Clip Action Text

The clipActionText String? is the text call to action if the Clip associated with the event has an Action link.

Clip Action URL

The clipActionUrl: String? is the URL linked to from the action if a Clip associated with the event has an Action.

Collection

The collection is the ID of the Collection if a Story or Clip is being played from a Collection.

Category Details

The categoryDetails is a list of Category Detail objects. The details are the name, ID, type and placement of the Category.

Current Category

The currentCategory is the Category for the row that is currently being interacted with. The information provided from this is the Category title, ID and placement.

This is only included on Story and Ad events.