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.
This event is recorded in the following scenarios:
Whenever an Opened Story event occurs, event data for storyID
, storyTitle
, storyIndex
, storyPageCount
, storyReadStatus
, storyPlaybackMode
, openedReason
, currentCategory
and categories
is returned.
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.
This event is recorded in the following scenarios:
Whenever a Dismissed Story event occurs, event data for storyId
, storyTitle
, storyIndex
, storyPageCount
storyPlaybackMode
, pageID
, pageIndex
, pageType
dismissedReason
, durationViewed
, currentCategory
and pagesViewedCount
is returned.
This event is recorded when:
Whenever a Skipped Story event occurs, event data for storyId
, storyTitle
, storyIndex
, storyPageCount
storyPlaybackMode
, pageID
, pageIndex
, currentCategory
and pageType
is returned.
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.
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.
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.
This event is recorded in the following scenarios:
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.
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.
This event is recorded when:
DismissedStory
is fired instead)Whenever a Previous Story event occurs, event data for storyId
, storyTitle
, storyIndex
, storyPageCount
storyPlaybackMode
, pageID
, pageIndex
, currentCategory
and pageType
is returned.
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.
This event is recorded when a user:
Whenever a Share Success event occurs, event data for storyId
, storyTitle
, storyIndex
, storyPageCount
storyPlaybackMode
, pageID
, pageIndex
, pageType
, currentCategory
and shareMethod
is returned.
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.
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.
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.
This event is recorded when:
openCollection
Whenever a Opened Clip event occurs, event data for clipId
, clipTitle
, clipIndex
, clipHasAction
, openedReason
, collection
, categories
, contentLength
and categoryDetails
is returned.
This event is recorded when:
Whenever a Dismissed Clip event occurs, event data for clipId
, clipTitle
, clipIndex
, dismissedReason
, durationViewed
, clipsViewed
, collection
, categories
and loopsViewed
is returned.
This event is recorded when:
Whenever a Next Clip event occurs, event data for clipId
, clipTitle
, collection
, categories
and clipIndex
is returned.
This event is recorded when:
Whenever a Previous Clip event occurs, event data for clipId
, clipTitle
, collection
, categories
and clipIndex
is returned.
This event is recorded when:
Whenever a Completed Loop event occurs, event data for clipId
, clipTitle
, collection
, categories
and clipIndex
is returned.
This event is recorded when:
Whenever a Action Button Tapped event occurs, event data for clipId
, clipTitle
, clipIndex
, clipHasAction
, clipActionText
, collection
, categories
and clipActionUrl
is returned.
This event is recorded when:
Whenever a Share Button Tapped event occurs, event data for clipId
, clipTitle
, collection
, categories
and clipIndex
is returned.
This event is recorded when:
Whenever a Share Success event occurs, event data for clipId
, clipTitle
, clipIndex
, collection
, categories
and shareMethod
is returned.
This event is recorded when:
Whenever a Paused Clip event occurs, event data for clipId
, clipTitle
, collection
, categories
and clipIndex
is returned.
This event is recorded when:
Whenever a Resumed Clip event occurs, event data for clipId
, clipTitle
, collection
, categories
and clipIndex
is returned.
This event is recorded when:
Whenever a Liked Clip event occurs, event data for clipId
, clipTitle
, collection
, categories
and clipIndex
is returned.
This event is recorded when:
Whenever a Unliked Clip event occurs, event data for clipId
, clipTitle
, collection
, categories
and clipIndex
is returned.
This event is recorded when:
Whenever a Finished Clip event occurs, event data for clipId
, clipTitle
, clipIndex
, loopsViewed
, durationViewed
, collection
, categories
and contentLength
is returned.
This event is recorded when:
Whenever a Opened Ad event occurs, event data for advertiserName
, adId
, pageType
, openedReason
, adView
, contentLength
, pageHasAction
, pageActionText
, currentCategory
and pageActionUrl
is returned.
This event is recorded when a user:
Whenever a Dismissed Ad event occurs, event data for advertiserName
, adId
, pageType
, dismissedReason
, durationViewed
, pagesViewed
, pageHasAction
, pageActionText
, currentCategory
and pageActionUrl
is returned.
This event is recorded when a user:
Whenever a Skipped Ad event occurs, event data for advertiserName
, adId
, pageType
, contentLength
, pageHasAction
, pageActionText
, currentCategory
and pageActionUrl
is returned.
This event is recorded when a user:
Whenever a Ad Action Button Tapped event occurs, event data for advertiserName
, adId
, pageType
, pageHasAction
, pageActionText
, currentCategory
and pageActionUrl
is returned.
This event is recorded when a user:
Whenever a Previous Ad event occurs, event data for advertiserName
, adId
, pageType
, contentLength
, pageHasAction
, pageActionText
, currentCategory
and pageActionUrl
is returned.
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.
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.
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.
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.
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.
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.
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.
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
, pageIndex
and pageType
is returned.
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
, pageIndex
and pageType
is returned.
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.
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.
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:
The storyId: String?
is the ID of the Story for which the event occurred.
The storyTitle: String?
is the title of the Story for which the event occurred.
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.
The storyPageCount: Int?
is the number of Pages in the Story.
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
.
The pageId: String?
is the ID of the Page for which the event occurred.
The pageIndex: Int?
is the index of the Page in the Story for which the event occurred. Note: this value is 1-based.
The pageType: String?
is the type of the Page associated with the event. This can have the value image
, video
or poll
.
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
.
The pageHasAction: Bool?
value states whether the Page associated with the event contains a swipe up link.
The pageActionText: String?
is the text call to action if the Page has an Action.
The pageActionUrl: String?
is the URL for the link if the Page has an Action.
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.
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.
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
.
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.
The contentLength: Int?
is the total duration of the Page content in seconds.
The advertiserName: String?
is the name of the advertiser for a particular ad. This is only included for ad events.
The adId: String?
is the ad ID if an event is associated with an ad.
The shareMethod: String?
is the component name of the app which the user has selected for sharing.
The adView: View?
is the view the ad is rendered in. This is only included for OpenedAd
and FinishedAd
events.
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.
The timeSinceBufferingBegan: TimeInterval?
value is the duration the current buffering lasted for in milliseconds. This is only included for BufferingEnded
events.
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.
The pollAnswerId: String?
is the ID of the answer the user selected when voting. This is only included on VotedPoll
events.
The triviaQuizId: String?
is the ID of the Trivia Quiz that was completed or answered. This is only included on TriviaQuizQuestionAnswered
and TriviaQuizCompleted
events.
The triviaQuizTitle: String?
is the title of the Trivia Quiz that was completed or answered. This is only included on TriviaQuizQuestionAnswered
and TriviaQuizCompleted
events.
ThetriviaQuizScore: Int?
value is the score of the trivia quiz that was completed. This is only included on TriviaQuizCompleted
events.
The triviaQuizQuestionId: String?
is the ID of the trivia quiz question which was answered. This is only included on TriviaQuizQuestionAnswered
events.
The triviaQuizAnswerId: String?
is the ID of the selected trivia quiz answer. This is only included on TriviaQuizQuestionAnswered
events.
The clipId: String?
is the ID of the Clip for which the event occurred.
The clipTitle: String?
is the title of the Clip for which the event occurred.
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.
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.
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.
The clipHasAction: Bool?
value is whether the Clip associated with the event contains an action.
The clipActionText String?
is the text call to action if the Clip associated with the event has an Action link.
The clipActionUrl: String?
is the URL linked to from the action if a Clip associated with the event has an Action.
The collection
is the ID of the Collection if a Story or Clip is being played from a Collection.
The categoryDetails
is a list of Category Detail objects. The details are the name, ID, type and placement of the 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.