# Analytics URL: /Analytics/ ## Task You are helping an engineer integrate Storyteller. Use this documentation to answer questions, propose improvements, and point out missing details. Be precise and call out assumptions. ## Metadata - Slug: `analytics` - Source: `public-docs/Analytics.md` - Audience: React Native SDK integrators - Platforms: `iOS`, `Android` - Related: `Storyteller.md`, `Search.md`, `Ads.md` ## Overview - `StorytellerSdk.onUserActivityOccurred(listener)` receives `{ type, data }` with the exported `EventType` values and event-specific payload fields and returns a removable subscription. - The guide enumerates all exported event values and optional payload fields, with Story/Page, Clips, tile, Search, ad, playback, Card, sheet and followable-category telemetry. - The exported type contract is broader than guaranteed event delivery. Availability depends on platform, content, tracking settings and ad integration. ## Integration Steps 1. Register once before interactions you want to measure; remove component-owned subscriptions on unmount. 1. Switch on exported `EventType` members and check optional data before forwarding to your analytics provider. 1. Respect user activity/full-video/ad tracking settings and native platform differences. ## API Cheat Sheet - `enableUserActivityTracking: false` disables host event callbacks; `enableFullVideoAnalytics: false` removes content IDs/titles. Storyteller collection is controlled separately. - `OpenedPage` is a Page impression, including images/interactive content; `MediaStarted` identifies a video playback start. - `CompletedStory` fires on reaching the final Page, rather than proving complete watch time. - Native `durationViewed` becomes RN `durationViewedMs`; viewing/buffering/scrub durations use milliseconds, while `contentLength` uses seconds. Android forwards several numeric durations as integers. - Organic heartbeats occur at five-second cumulative active-time thresholds. Organic quartiles are 25/50/75; Clip quartiles reset per pass and do not fire for live Clips. - External Search taps use `SearchResultTapped` and can include `actionType`, `searchResultId`, `searchResultTitle`, `searchResultSource` and `tileIndex`. ## Pitfalls / Notes - The generated callback payload types `metadata` as `Object`, while exported `UserActivityData.metadata` is a string map. Infer the callback type or validate/map metadata before forwarding to a service typed with `UserActivityData`. - `SdkInitialized` is an internal native event and does not reach host subscriptions on either platform. - The iOS RN bridge omits `isMuted`, `originalPosition`, `displayPosition`, device/app and SDK-initialization groups even though the TS type declares them. `airplayEnabled` is iOS-only. - Story/Page/Clip context fields and Search-origin context are optional. Listed payload fields are examples, not required event schemas. - Native reasons use `storyListTap` and `clipListTap`. Reason and category fields can appear on more event groups than just opened/dismissed content. - Page-player analytics use 1-based content indexes; Android excludes inserted ad Pages. Search-origin/native paths can use different indexes. - Live Clips do not support normal pause/resume or completed-loop analytics. Category events describe category-stack navigation, not the top-level Collection. - Paid lifecycle/revenue events require the applicable integration and callback path; provider and revenue metadata may be absent. ## Cross-References - public-docs/Storyteller.md - public-docs/Search.md - public-docs/Ads.md ## Canonical Reference # Analytics 1. [Event Types](#event-types) - [Complete React Native EventType Reference](#complete-react-native-eventtype-reference) 1. [Story Events](#story-events) 1. [Clip Events](#clip-events) 1. [List Tile Events](#list-tile-events) 1. [Search Events](#search-events) - [Opened Search](#opened-search) - [Dismissed Search](#dismissed-search) - [Performed Search](#performed-search) - [Opened Filters](#opened-filters) - [Dismissed Filters](#dismissed-filters) - [Used Suggestion](#used-suggestion) 1. [Ad Events](#ad-events) 1. [Playback Events](#playback-events) 1. [Event Data](#event-data) - [Complete React Native UserActivityData Reference](#complete-react-native-useractivitydata-reference) ## Event Types These are the various events which are triggered from within the SDK. React Native integrations receive the exported `EventType` enum and an event-specific data payload through `StorytellerSdk.onUserActivityOccurred()`. Register the listener before the interactions you want to measure. The callback receives `{ type, data }` and registration returns a subscription with `remove()`. For a component-owned listener: ```tsx import { useEffect } from 'react'; import StorytellerSdk, { EventType } from '@getstoryteller/react-native-storyteller-sdk'; export function AnalyticsListener() { useEffect(() => { const subscription = StorytellerSdk.onUserActivityOccurred(({ type, data }) => { if (type === EventType.OpenedStory && data.storyId !== undefined) { console.log('Story opened', data.storyId); } }); return () => subscription.remove(); }, []); return null; } ``` Mount this listener once for the area of your app that owns tracking. Multiple listeners each receive the events. `enableUserActivityTracking: false` disables the host callback. With `enableFullVideoAnalytics: false`, native SDKs remove content-identifying fields such as Story/Page/Clip/Card IDs and titles before forwarding data. Ad events also depend on ad tracking and the configured ad integration. `enableStorytellerTracking` controls Storyteller collection separately from your listener. 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. ### Complete React Native `EventType` Reference The table below is the complete `EventType` enum exported by `@getstoryteller/react-native-storyteller-sdk`. This is the exported type contract, not a promise that each member reaches your listener. `SdkInitialized` is internal to native analytics and is not forwarded to the host on either platform. Not every other event is emitted on every platform, content type, tenant configuration, or native SDK path; handle events by enum member and treat payload fields as event-dependent. | Group | Enum member | Emitted value | | ------------ | ----------------------------------------------------- | ------------------------------------------- | | story | `EventType.Unsupported` | `unsupported` | | story | `EventType.OpenedStory` | `openedStory` | | story | `EventType.StoryHeartbeat` | `storyHeartbeat` | | story | `EventType.StoryPageQuartile` | `storyPageQuartile` | | story | `EventType.DismissedStory` | `dismissedStory` | | story | `EventType.SkippedStory` | `skippedStory` | | story | `EventType.CompletedStory` | `completedStory` | | story | `EventType.PreviousStory` | `previousStory` | | story | `EventType.MutedStory` | `mutedStory` | | story | `EventType.UnmutedStory` | `unmutedStory` | | story | `EventType.ActionButtonTapped` | `actionButtonTapped` | | sharing | `EventType.ShareButtonTapped` | `shareButtonTapped` | | sharing | `EventType.ShareSuccess` | `shareSuccess` | | page | `EventType.CompletedPage` | `completedPage` | | page | `EventType.PreviousPage` | `previousPage` | | page | `EventType.OpenedPage` | `openedPage` | | page | `EventType.SkippedPage` | `skippedPage` | | ad | `EventType.OpenedAd` | `openedAd` | | ad | `EventType.DismissedAd` | `dismissedAd` | | ad | `EventType.SkippedAd` | `skippedAd` | | ad | `EventType.AdActionButtonTapped` | `adActionButtonTapped` | | ad | `EventType.PreviousAd` | `previousAd` | | ad | `EventType.MutedAd` | `mutedAd` | | ad | `EventType.UnmutedAd` | `unmutedAd` | | ad | `EventType.PausedAdPage` | `pausedAdPage` | | ad | `EventType.ResumedAdPage` | `resumedAdPage` | | ad | `EventType.ViewedAdPageStart` | `viewedAdPageStart` | | ad | `EventType.ViewedAdPageFirstQuartile` | `viewedAdPageFirstQuartile` | | ad | `EventType.ViewedAdPageMidpoint` | `viewedAdPageMidpoint` | | ad | `EventType.ViewedAdPageThirdQuartile` | `viewedAdPageThirdQuartile` | | ad | `EventType.ViewedAdPageComplete` | `viewedAdPageComplete` | | ad | `EventType.FinishedAd` | `finishedAd` | | ad | `EventType.AdOpportunity` | `adOpportunity` | | ad | `EventType.AdRequested` | `adRequested` | | ad | `EventType.AdLoaded` | `adLoaded` | | ad | `EventType.AdFailedToLoad` | `adFailedToLoad` | | ad | `EventType.AdPaid` | `adPaid` | | ad | `EventType.AdSessionSummary` | `adSessionSummary` | | playback | `EventType.ReadyToPlay` | `readyToPlay` | | playback | `EventType.MediaStarted` | `mediaStarted` | | playback | `EventType.BufferingStarted` | `bufferingStarted` | | playback | `EventType.BufferingEnded` | `bufferingEnded` | | playback | `EventType.CurrentVideoPlayerChanged` | `onCurrentVideoPlayerChanged` | | playback | `EventType.TileVisible` | `tileVisible` | | poll | `EventType.VotedPoll` | `votedPoll` | | trivia quiz | `EventType.TriviaQuizQuestionAnswered` | `triviaQuizQuestionAnswered` | | trivia quiz | `EventType.TriviaQuizCompleted` | `triviaQuizCompleted` | | clips | `EventType.OpenedClip` | `openedClip` | | clips | `EventType.ClipVideoHeartbeat` | `clipVideoHeartbeat` | | clips | `EventType.ClipVideoQuartile` | `clipVideoQuartile` | | clips | `EventType.PausedClip` | `pausedClip` | | clips | `EventType.ResumedClip` | `resumedClip` | | clips | `EventType.MutedClip` | `mutedClip` | | clips | `EventType.UnmutedClip` | `unmutedClip` | | clips | `EventType.CompletedLoop` | `completedLoop` | | clips | `EventType.NextClip` | `nextClip` | | clips | `EventType.PreviousClip` | `previousClip` | | clips | `EventType.DismissedClip` | `dismissedClip` | | clips | `EventType.FinishedClip` | `finishedClip` | | clips | `EventType.LikedClip` | `likedClip` | | clips | `EventType.UnlikedClip` | `unlikedClip` | | clips | `EventType.OpenedCategory` | `openedCategory` | | clips | `EventType.DismissedCategory` | `dismissedCategory` | | clips | `EventType.FollowableCategoryTapped` | `followableCategoryTapped` | | clips | `EventType.FollowCategory` | `followCategory` | | clips | `EventType.UnfollowCategory` | `unfollowCategory` | | clips | `EventType.EnabledClipCaptions` | `enabledClipCaptions` | | clips | `EventType.DisabledClipCaptions` | `disabledClipCaptions` | | clips | `EventType.ScrubbedClip` | `scrubbedClip` | | search | `EventType.OpenedSearch` | `openedSearch` | | search | `EventType.DismissedSearch` | `dismissedSearch` | | search | `EventType.PerformedSearch` | `performedSearch` | | search | `EventType.SearchResultTapped` | `searchResultTapped` | | search | `EventType.OpenedFilters` | `openedFilters` | | search | `EventType.DismissedFilters` | `dismissedFilters` | | search | `EventType.UsedSuggestion` | `usedSuggestion` | | sheet | `EventType.OpenedSheet` | `openedSheet` | | sheet | `EventType.DismissedSheet` | `dismissedSheet` | | instructions | `EventType.StoryInstructionScreenViewed` | `storyInstructionScreenViewed` | | card | `EventType.CardTapped` | `cardTapped` | | card | `EventType.CardViewed` | `cardViewed` | | card | `EventType.CardVideoStarted` | `cardVideoStarted` | | card | `EventType.CardVideoHeartbeat` | `cardVideoHeartbeat` | | card | `EventType.CardVideoCompleted` | `cardVideoCompleted` | | card | `EventType.CardAudioToggled` | `cardAudioToggled` | | sdk | `EventType.SdkInitialized` | `sdkInitialized` | | sdk | `EventType.FollowableCategoryLimitShown` | `followableCategoryLimitShown` | | sdk | `EventType.FollowableCategoryLimitActionButtonTapped` | `followableCategoryLimitActionButtonTapped` | | sdk | `EventType.FollowableCategoryLimitDismissed` | `followableCategoryLimitDismissed` | | sdk | `EventType.EnabledStoryCaptions` | `enabledStoryCaptions` | | sdk | `EventType.DisabledStoryCaptions` | `disabledStoryCaptions` | ## 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 deep link For Opened Story, the payload can include `storyId`, `storyTitle`, `storyIndex`, `storyPageCount`, `storyReadStatus`, `storyPlaybackMode`, `openedReason`, `currentCategory` and `categories`. ### Opened Page This event is recorded whenever a user views content from a page. `OpenedPage` is a page impression and also applies to images and interactive pages. Use `MediaStarted` to measure the start of video playback; opening a page does not prove that its video started. For Opened Page, the payload can include `pageId`, `pageIndex`, `pageType`, `storyPlaybackMode`, `pageHasAction`, `pageActionText`, `pageActionUrl`, `contentLength`, `storyId`, `storyTitle`, `storyIndex`, `storyPageCount`, `currentCategory` and `openedReason`. ### 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 Android does not emit `DismissedStory` from the Search-origin content scope. For Dismissed Story, the payload can include `storyId`, `storyTitle`, `storyIndex`, `storyPageCount`, `storyPlaybackMode`, `pageId`, `pageIndex`, `pageType`, `dismissedReason`, `durationViewedMs`, `currentCategory` and `pagesViewedCount`. ### Skipped Story This event is recorded when: - a user advances from a Story before reaching its final page. Reaching the final page is counted as `CompletedStory`; skipping that final page is not an additional `SkippedStory`. For Skipped Story, the payload can include `storyId`, `storyTitle`, `storyIndex`, `storyPageCount`, `storyPlaybackMode`, `pageId`, `pageIndex`, `currentCategory` and `pageType`. ### Skipped Page This event is recorded when a user taps to go to the next page before completing the current page. For Skipped Page, the payload can include `storyId`, `storyTitle`, `storyIndex`, `storyPageCount`, `storyPlaybackMode`, `pageId`, `pageIndex`, `currentCategory` and `pageType`. ### Completed Story This event is recorded at the same time as `OpenedPage` for the final page in a story. For Completed Story, the payload can include `storyId`, `storyTitle`, `storyIndex`, `storyPageCount`, `storyPlaybackMode`, `pageId`, `pageIndex`, `currentCategory` and `pageType`. ### Completed Page This event is recorded when a user watches a page to completion (i.e. the timer for that page finishes.) For Completed Page, the payload can include `storyId`, `storyTitle`, `storyIndex`, `storyPageCount`, `storyPlaybackMode`, `pageId`, `pageIndex`, `pageType`, `currentCategory` and `contentLength`. ### Action Button Tapped This event is recorded when a user taps an action button on a page to open a link For Action Button Tapped, the payload can include `storyId`, `storyTitle`, `storyIndex`, `storyPageCount`, `storyPlaybackMode`, `pageId`, `pageIndex`, `pageType`, `pageHasAction`, `pageActionText`, `currentCategory` and `pageActionUrl`. ### Share Button Tapped This event is recorded when a user taps the share button on a page. For Share Button Tapped, the payload can include `storyId`, `storyTitle`, `storyIndex`, `storyPageCount`, `storyPlaybackMode`, `pageId`, `pageIndex`, `currentCategory` and `pageType`. ### 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) For Previous Story, the payload can include `storyId`, `storyTitle`, `storyIndex`, `storyPageCount`, `storyPlaybackMode`, `pageId`, `pageIndex`, `currentCategory` and `pageType`. ### Previous Page This event is recorded when a user taps back to go to a previous page in the story. For Previous Page, the payload can include `storyId`, `storyTitle`, `storyIndex`, `storyPageCount`, `storyPlaybackMode`, `pageId`, `pageIndex`, `currentCategory` and `pageType`. ### Share Success Android records this event when the user selects a sharing target. iOS records it when the system sharing activity reports completion. For Share Success, the payload can include `storyId`, `storyTitle`, `storyIndex`, `storyPageCount`, `storyPlaybackMode`, `pageId`, `pageIndex`, `pageType`, `currentCategory` and `shareMethod`. ### Voted Poll This event is recorded when user votes in a poll. For Voted Poll, the payload can include `storyId`, `storyTitle`, `storyIndex`, `pageId`, `pageIndex`, `pageType`, `currentCategory` and `pollAnswerId`. ### Trivia Quiz Question Answered This event is recorded when a user answers a question in a trivia quiz. For Trivia Quiz Question Answered, the payload can include `storyId`, `storyTitle`, `storyIndex`, `storyPlaybackMode`, `pageId`, `pageIndex`, `pageType`, `triviaQuizId`, `triviaQuizTitle`, `triviaQuizQuestionId`, `currentCategory` and `triviaQuizAnswerId`. ### Trivia Quiz Completed This event is recorded when a user completes a trivia quiz. For Trivia Quiz Completed, the payload can include `storyId`, `storyTitle`, `storyIndex`, `storyPlaybackMode`, `pageId`, `pageIndex`, `pageType`, `triviaQuizId`, `triviaQuizTitle`, `triviaQuizScore` and `currentCategory`. ## 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 - a user opens a Category and navigates to a new Clip or moves back to a previous Category. - a user dismisses the last Category (by pressing back or swiping right) and returns to the top-level Collection. - a user opens embedded Clips for the first time. - a user pulls to refresh at the top of Embedded Clips. - a user is viewing a Collection with “For You/Following” enabled and switches between "For You" and "Following". For Opened Clip, the payload can include `clipId`, `clipTitle`, `clipIndex`, `clipHasAction`, `openedReason`, `collection`, `categories`, `contentLength`, `clipFeedType` (values: `default`, `forYou`, `following`) and `categoryDetails`. ### Dismissed Clip This event is recorded when: - a user taps on the back button in the top-left to exit the Clips player (and is at the top of the stack of Clip Categories) This event does not fire when the user is not at the top of the Clip Category stack. For Dismissed Clip, the payload can include `clipId`, `clipTitle`, `clipIndex`, `dismissedReason`, `durationViewedMs`, `clipsViewed`, `collection`, `categories`, `clipFeedType` and `loopsViewed`. ### Next Clip This event is recorded when: - a user swipes up to go to the next clip For Next Clip, the payload can include `clipId`, `clipTitle`, `collection`, `categories`, `clipFeedType` and `clipIndex`. ### Previous Clip This event is recorded when: - a user swipes down to go to the previous clip For Previous Clip, the payload can include `clipId`, `clipTitle`, `collection`, `categories`, `clipFeedType` and `clipIndex`. ### Completed Loop This event is recorded when: - a user completes a loop of a clip For Completed Loop, the payload can include `clipId`, `clipTitle`, `collection`, `categories`, `clipFeedType` and `clipIndex`. > Note: For live clips this event will never be fired. ### 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 For Action Button Tapped, the payload can include `clipId`, `clipTitle`, `clipIndex`, `clipHasAction`, `clipActionText`, `collection`, `categories`, `clipFeedType` and `clipActionUrl`. ### Share Button Tapped This event is recorded when: - a user taps the share button on a clip For Share Button Tapped, the payload can include `clipId`, `clipTitle`, `collection`, `categories`, `clipFeedType` and `clipIndex`. ### Share Success Android records this event when the user selects a sharing target. iOS records it when the system sharing activity reports completion. For Share Success, the payload can include `clipId`, `clipTitle`, `clipIndex`, `collection`, `categories`, `clipFeedType` and `shareMethod`. ### 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 For Paused Clip, the payload can include `clipId`, `clipTitle`, `collection`, `categories`, `clipFeedType` and `clipIndex`. > Note: For live clips this event will never be fired, as pausing/resuming live clips is not supported. ### 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 For Resumed Clip, the payload can include `clipId`, `clipTitle`, `collection`, `categories`, `clipFeedType` and `clipIndex`. > Note: For live clips this event will never be fired, as pausing/resuming live clips is not supported. ### 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 For Liked Clip, the payload can include `clipId`, `clipTitle`, `collection`, `categories`, `clipFeedType` and `clipIndex`. ### Unliked Clip This event is recorded when: - a user unlikes a clip by tapping the like button when they currently like the clip For Unliked Clip, the payload can include `clipId`, `clipTitle`, `collection`, `categories`, `clipFeedType` and `clipIndex`. ### Finished Clip This event is recorded when: - Dismissed Clip is fired - Next Clip is fired - Previous Clip is fired - At the same time as OpenedCategory - A user is viewing a Collection with “For You/Following” enabled and switches between "For You" and "Following". For Finished Clip, the payload can include `clipId`, `clipTitle`, `clipIndex`, `loopsViewed`, `durationViewedMs`, `collection`, `categories`, `clipFeedType` and `contentLength`. ### Opened Category This event is recorded when: - a user taps a category at the bottom of the Clips Player to open a new Category - a user opens a category by navigating back from another category This event is not fired when opening the top level of a collection - only when navigating to a specific category. For Opened Category, the payload can include `clipId`, `clipTitle`, `clipIndex`, `collection`, `categories`, `categoryId`, `clipFeedType` and `categoryName`. ### Dismissed Category This event is recorded when: - a user navigates back using the back button (or system back on Android) to the previous category. This event does not fire when dismissing the top level collection. For Dismissed Category, the payload can include `clipId`, `clipTitle`, `clipIndex`, `collection`, `categories`, `categoryId`, `clipFeedType` and `categoryName`. ### Follow Category This event is recorded when: - a user taps the plus button under the follow category button of the Clips Player - a user taps the follow button at the top right of the Followable Category screen and the category was not followed For Follow Category, the payload can include `clipId`, `clipTitle`, `clipIndex`, `collection`, `categories`, `categoryId`, `clipFeedType` and `categoryName`. ### Unfollow Category This event is recorded when: - a user taps the checkmark button under the follow category button of the Clips Player - a user taps the follow button at the top right of the Followable Category screen and the category was followed For Unfollow Category, the payload can include `clipId`, `clipTitle`, `clipIndex`, `collection`, `categories`, `categoryId`, `clipFeedType` and `categoryName`. ### Followable Category Tapped This event is recorded when: - a user taps the follow category button of the Clips Player to open the Followable Category screen - a user swipes left from the right edge of the screen on a Clip with a Followable Category and opens the Followable Category screen For Followable Category Tapped, the payload can include `clipId`, `clipTitle`, `clipIndex`, `collection`, `categories`, `categoryId`, `clipFeedType` and `categoryName`. ## List Tile Events ### Tile Visible This event is recorded when a Story or Clip tile becomes visible in a row or grid. For Tile Visible, event data includes `tileIndex`. Story tile events include `storyId`, `storyTitle`, `categories`, and `context` when available. Clip tile events include `clipId`, `clipTitle`, `collection`, `categories`, and `context` when available. ## Search Events ### Opened Search This event is recorded when: - a user open Search screen For Opened Search, the payload can include `storyId`, `storyTitle`, `storyDisplayTitle`, `storyIndex`, `storyPageCount`, `storyReadStatus`, `pageId`, `pageTitle`, `pageIndex`, `pageType`, `storyPlaybackMode`, `pageHasAction`, `pageActionText`, `pageActionUrl`, `categories`, `categoryDetails`, `collection`, `currentCategory`, `clipId`, `clipTitle`, `clipIndex`, `clipActionText` and `searchFrom`. ### Dismissed Search This event is recorded when: - a user exits the Search screen For Dismissed Search, the payload can include `storyId`, `storyTitle`, `storyDisplayTitle`, `storyIndex`, `storyPageCount`, `storyReadStatus`, `pageId`, `pageTitle`, `pageIndex`, `pageType`, `storyPlaybackMode`, `pageHasAction`, `pageActionText`, `pageActionUrl`, `dismissedReason`, `categories`, `categoryDetails`, `collection`, `currentCategory`, `clipId`, `clipTitle`, `clipIndex`, `clipActionText` and `searchFrom`. ### Performed Search This event is recorded when: - a user clicks on the Search button after entering the search term For Performed Search, the payload can include `storyId`, `storyTitle`, `storyDisplayTitle`, `storyIndex`, `storyPageCount`, `storyReadStatus`, `pageId`, `pageTitle`, `pageIndex`, `pageType`, `storyPlaybackMode`, `pageHasAction`, `pageActionText`, `pageActionUrl`, `categories`, `categoryDetails`, `collection`, `currentCategory`, `clipId`, `clipTitle`, `clipIndex`, `clipActionText`, `searchFilter`, `searchSort`, `searchTerm`, `searchFrom`, `isSuggestion`, and `initialInput`. ### Opened Filters This event is recorded when: - a user taps the filter button to open the sheet containing filter options For Opened Filters, the payload can include `storyId`, `storyTitle`, `storyDisplayTitle`, `storyIndex`, `storyPageCount`, `storyReadStatus`, `pageId`, `pageTitle`, `pageIndex`, `pageType`, `storyPlaybackMode`, `pageHasAction`, `pageActionText`, `pageActionUrl`, `categories`, `categoryDetails`, `collection`, `currentCategory`, `clipId`, `clipTitle`, `clipIndex`, `clipActionText`, `searchFilter`, `searchSort`, `searchTerm`, `searchFrom`, `isSuggestion`, and `initialInput`. ### Dismissed Filters This event is recorded when: - a user closes the sheet containing filter options For Dismissed Filters, the payload can include `storyId`, `storyTitle`, `storyDisplayTitle`, `storyIndex`, `storyPageCount`, `storyReadStatus`, `pageId`, `pageTitle`, `pageIndex`, `pageType`, `storyPlaybackMode`, `pageHasAction`, `pageActionText`, `pageActionUrl`, `categories`, `categoryDetails`, `collection`, `currentCategory`, `clipId`, `clipTitle`, `clipIndex`, `clipActionText`, `searchFilter`, `searchSort`, `searchTerm`, `searchFrom`, `isSuggestion`, and `initialInput`. ### Used Suggestion This event is recorded when: - a user taps on a search suggestion For Used Suggestion, the payload can include `storyId`, `storyTitle`, `storyDisplayTitle`, `storyIndex`, `storyPageCount`, `storyReadStatus`, `pageId`, `pageTitle`, `pageIndex`, `pageType`, `storyPlaybackMode`, `pageHasAction`, `pageActionText`, `pageActionUrl`, `categories`, `categoryDetails`, `collection`, `currentCategory`, `clipId`, `clipTitle`, `clipIndex`, `clipActionText`, `searchTerm`, `searchFrom`, `isSuggestion`, and `initialInput`. ## Ad Events ### Opened Ad #### Stories 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 For Opened Ad, the payload can include `advertiserName`, `adId`, `adType`, `adPlacement`, `adFormat`, `adResponseIdentifier`, `pageType`, `openedReason`, `contentLength`, `pageHasAction`, `pageActionText`, `currentCategory` and `pageActionUrl`. #### Clips This event is recorded when: - a user swipes up on a clip to go to the next clip and an ad should appear next - a user swipes down on a clip to go to the previous clip and an ad should appear next - an ad completes a loop and begins playing again from the start React Native exposes the analytics payload; it does not include the native ad view object. For Opened Ad, the payload can include `advertiserName`, `adId`, `adType`, `adPlacement`, `adFormat`, `adResponseIdentifier`, `pageType`, `openedReason`, `contentLength`, `pageHasAction`, `clipHasAction`, `pageActionText`, `clipActionText`, `pageActionUrl`, `clipActionUrl`, `currentCategory`, `collection`. ### Dismissed Ad #### Stories 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 For Dismissed Ad, the payload can include `advertiserName`, `adId`, `adType`, `adPlacement`, `adFormat`, `adResponseIdentifier`, `pageType`, `dismissedReason`, `durationViewedMs`, `pagesViewedCount`, `pageHasAction`, `pageActionText`, `currentCategory` and `pageActionUrl`. #### Clips This event is recorded when a user: - taps the back button to exit the clips player when an ad is being shown - (Android only) presses the system back button to exit the clips player when an ad is being shown For Dismissed Ad, the payload can include `advertiserName`, `adId`, `adType`, `adPlacement`, `adFormat`, `adResponseIdentifier`, `pageType`, `dismissedReason`, `durationViewedMs`, `pagesViewedCount`, `clipsViewed`, `loopsViewed`, `pageHasAction`, `clipHasAction`, `pageActionText`, `clipActionText`, `pageActionUrl`, `clipActionUrl`, `currentCategory`, `collection`. ### Skipped Ad #### Stories 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 For Skipped Ad, the payload can include `advertiserName`, `adId`, `adType`, `adPlacement`, `adFormat`, `adResponseIdentifier`, `pageType`, `contentLength`, `pageHasAction`, `pageActionText`, `currentCategory` and `pageActionUrl`. #### Clips This event is recorded when: - a user swipes up to go to the next clip - a user swipes down to go the previous clip For Skipped Ad, the payload can include `advertiserName`, `adId`, `adType`, `adPlacement`, `adFormat`, `adResponseIdentifier`, `pageType`, `contentLength`, `pageHasAction`, `clipHasAction`, `pageActionText`, `clipActionText`, `pageActionUrl`, `clipActionUrl`, `currentCategory`, `collection`. ### Ad Action Button Tapped #### Stories 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 For Ad Action Button Tapped, the payload can include `advertiserName`, `adId`, `adType`, `adPlacement`, `adFormat`, `adResponseIdentifier`, `pageType`, `pageHasAction`, `pageActionText`, `currentCategory` and `pageActionUrl`. #### Clips This event is recorded when a user: - taps the action button at the bottom of an ad displayed in clips - swipes left on a clip to open the relevant action For Ad Action Button Tapped, the payload can include `advertiserName`, `adId`, `adType`, `adPlacement`, `adFormat`, `adResponseIdentifier`, `pageType`, `pageHasAction`, `clipHasAction`, `pageActionText`, `clipActionText`, `pageActionUrl`, `clipActionUrl`, `currentCategory`, `collection`. ### Finished Ad #### Stories This event is recorded at the same time as Dismissed Ad, Skipped Ad and Viewed Ad Page Complete and gives an easier way to determine when an ad finishes for any reason. For Finished Ad, the payload can include `advertiserName`, `adId`, `adType`, `adPlacement`, `adFormat`, `adResponseIdentifier`, `pageType`, `contentLength`, `pageHasAction`, `pageActionText`, `currentCategory` and `pageActionUrl`. #### Clips This event is recorded at the same time as DismissedAd, or SkippedAd. For Finished Ad, the payload can include `advertiserName`, `adId`, `adType`, `adPlacement`, `adFormat`, `adResponseIdentifier`, `pageType`, `contentLength`, `pageHasAction`, `clipHasAction`, `pageActionText`, `clipActionText`, `pageActionUrl`, `clipActionUrl`, `currentCategory`, `collection`. ### Paused Ad #### Stories This event is recorded when a user pauses a page within an ad by pressing and holding on the page. For Paused Ad Page, the payload can include `advertiserName`, `adId`, `adType`, `adPlacement`, `adFormat`, `adResponseIdentifier`, `pageType`, `contentLength`, `pageHasAction`, `pageActionText`, `currentCategory` and `pageActionUrl`. #### Clips This event is recorded when a user pauses a clip which is an ad by tapping the screen. It does not fire when a clip is paused automatically for sharing or following an action For Paused Ad Clip, the payload can include `advertiserName`, `adId`, `adType`, `adPlacement`, `adFormat`, `adResponseIdentifier`, `pageType`, `contentLength`, `pageHasAction`, `clipHasAction`, `pageActionText`, `clipActionText`, `pageActionUrl`, `clipActionUrl`, `currentCategory`, `collection`. ### Resumed Ad #### Stories This event is recorded when a user resumes playing a page within an ad by releasing their long press which paused the ad. For Resumed Ad Page, the payload can include `advertiserName`, `adId`, `adType`, `adPlacement`, `adFormat`, `adResponseIdentifier`, `pageType`, `contentLength`, `pageHasAction`, `pageActionText`, `currentCategory` and `pageActionUrl`. #### Clips This event is fired when a clip which is an ad is paused and a user taps the screen to resume playback. It does not fire when a clip is resumed automatically For Resumed Ad Clip, the payload can include `advertiserName`, `adId`, `adType`, `adPlacement`, `adFormat`, `adResponseIdentifier`, `pageType`, `contentLength`, `pageHasAction`, `clipHasAction`, `pageActionText`, `clipActionText`, `pageActionUrl`, `clipActionUrl`, `currentCategory`, `collection`. ### Viewed Ad Page First Quartile This event is recorded when a user reaches 1/4 of the way through the duration of a page or clip which is an ad. For clip ads (which loop), it fires for each loop of the clip. For Viewed Ad Page First Quartile, the payload can include `advertiserName`, `adId`, `adType`, `adPlacement`, `adFormat`, `adResponseIdentifier`, `pageType`, `contentLength`, `pageHasAction`, `clipHasAction`, `pageActionText`, `clipActionText`, `pageActionUrl`, `clipActionUrl`, `currentCategory`, `collection`. ### Viewed Ad Page Midpoint This event is recorded when a user reaches halfway through the duration of a page or clip which is an ad. For clip ads (which loop), it fires for each loop of the clip. For Viewed Ad Page Midpoint, the payload can include `advertiserName`, `adId`, `adType`, `adPlacement`, `adFormat`, `adResponseIdentifier`, `pageType`, `contentLength`, `pageHasAction`, `clipHasAction`, `pageActionText`, `clipActionText`, `pageActionUrl`, `clipActionUrl`, `currentCategory`, `collection`. ### Viewed Ad Page Third Quartile This event is recorded when a user reaches 3/4 of the way through the duration of a page or clip which is an ad. For clip ads (which loop), it fires for each loop of the clip. For Viewed Ad Page Third Quartile, the payload can include `advertiserName`, `adId`, `adType`, `adPlacement`, `adFormat`, `adResponseIdentifier`, `pageType`, `contentLength`, `pageHasAction`, `clipHasAction`, `pageActionText`, `clipActionText`, `pageActionUrl`, `clipActionUrl`, `currentCategory`, `collection`. ### Viewed Ad Page Complete This event is recorded when a user reaches the end of the duration for a page or clip which is an ad. For clip ads (which loop), it fires for each loop of the clip. For Viewed Ad Page Complete, the payload can include `advertiserName`, `adId`, `adType`, `adPlacement`, `adFormat`, `adResponseIdentifier`, `pageType`, `contentLength`, `pageHasAction`, `clipHasAction`, `pageActionText`, `clipActionText`, `pageActionUrl`, `clipActionUrl`, `currentCategory`, `collection`. ### Paid ad lifecycle events These events require the matching paid-ad integration and callback path; a custom ad implementation does not guarantee revenue telemetry. | Event | Meaning | Optional payload examples | | ------------------ | ------------------------------------------ | ----------------------------------------------------- | | `AdOpportunity` | Player has an opportunity to request an ad | `playerSessionId`, `adSlotType`, `adPlacement` | | `AdRequested` | Ad request begins | `adRequestId`, `adUnitId`, `adSource` | | `AdLoaded` | Ad loads | request context and available source/adapter metadata | | `AdFailedToLoad` | Ad request fails | `adErrorCode`, `adErrorDomain`, `adErrorMessage` | | `AdPaid` | Provider reports a paid impression | `adValueMicros`, `adCurrencyCode`, `adValuePrecision` | | `AdSessionSummary` | Paid-ad player session is summarized | `adSession*` counters, revenue and currency | `AdOpportunity` and `AdSessionSummary` do not identify a single requested ad unit. Treat provider fields and paid-impression values as optional. ## Playback Events ### Ready to Play This event indicates that the video player is ready to play. A Page revisit or a new player load can create another readiness event. For Ready to Play, the payload can include `storyId`, `storyTitle`, `storyIndex`, `pageId`, `pageIndex` and `pageType`. ### Media Started This event indicates that the video starts playback for the current player load. For Media Started, the payload can include `storyId`, `storyTitle`, `storyIndex`, `pageId`, `pageIndex` and `pageType`. ### Buffering Started This event is called on video pages whenever the video starts to buffer. For Buffering Started, the payload can include `storyId`, `storyTitle`, `storyIndex`, `pageId`, `pageIndex`, `pageType` and `isInitialBuffering`. ### Buffering Ended This event is called on video pages whenever the video finishes buffering. > Note: Readiness and media-start events describe a playback load, not a unique content ID across all visits. 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. For Buffering Ended, the payload can include `storyId`, `storyTitle`, `storyIndex`, `pageId`, `pageIndex`, `pageType`, `isInitialBuffering` and `timeSinceBufferingBegan`. ## Other exported event groups - Mute and captions events report the corresponding user-visible state change for Stories, Clips or ads. `ScrubbedClip` can include `startPosition`, `endPosition` and `scrubDirection`. - `OpenedSheet` and `DismissedSheet` identify SDK sheets with optional `sheetId`, `sheetTitle` and `sheetSize`, plus originating content when known. - `StoryInstructionScreenViewed` identifies a displayed Story instruction screen. - `CardViewed` and `CardTapped` describe Card visibility and interaction. `CardVideoStarted`, `CardVideoHeartbeat`, and `CardVideoCompleted` describe Card playback; `CardAudioToggled` can include `audioToggleFrom`, `audioToggleTo` and mute state where forwarded. - Followable-category limit events describe the limit dialogue being shown, dismissed or its action being tapped. Related copy and action fields are optional. - `CurrentVideoPlayerChanged` identifies a native player transition. Its RN analytics payload does not expose the native video player object. ## Event Data For each event, data is returned with details about the content involved and additional information about what the user has done. The exported `UserActivityData` type lists the payload fields. The callback uses a generated event type whose `metadata` is currently declared as `Object`, whereas `UserActivityData.metadata` is a string map. Keep the callback parameter inferred; when forwarding it to a typed analytics service, derive that service's input from the callback type or validate and map the metadata first. ### React Native payload differences The following implementation notes were checked against the React Native integration source with Android 12.1.1 and iOS 11.8.0: - Android suppresses Story and ad dismissal events in Search-origin content scopes; iOS also suppresses Story-ad dismissal in that scope. - Missing native values are omitted; do not expect every field listed for an event. Search payloads contain originating Story or Clip context only when Search was opened from that content. - Native `durationViewed` is renamed to `durationViewedMs` by both bridges. `contentLength` is in seconds; viewing and buffering durations and scrub positions are in milliseconds. Android converts content length, viewed duration and scrub positions to integers when forwarding them. - `isMuted`, `originalPosition`, and `displayPosition` are declared in `UserActivityData` but are currently omitted by the iOS RN bridge. `airplayEnabled` is iOS-only. - Device/app and SDK-initialization fields remain part of the TypeScript type. The iOS RN bridge does not forward these groups, and `SdkInitialized` never reaches the host subscription on either platform. - `metadata` and `context` are string-keyed objects. `categoryDetails` contains category objects with `name`, `id`, `type`, and `placement`; `currentCategory` contains `name`, `id`, and `placement` when supplied. ### Complete React Native `UserActivityData` Reference All fields are optional because the native SDK only supplies data relevant to the event and platform. The table is the complete React Native payload type; the detailed sections below explain common fields and event-specific behavior. | Group | Optional fields | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | story | `storyId` (string), `storyIndex` (number), `storyTitle` (string), `storyReadStatus` (string), `storyPageCount` (number), `storyDisplayTitle` (string) | | clip | `clipId` (string), `clipTitle` (string), `clipIndex` (number), `tileIndex` (number), `clipHasAction` (boolean), `clipActionUrl` (string), `clipActionText` (string), `clipActionType` (string), `clipFeedType` (string), `clipsViewed` (number), `loopsViewed` (number), `originalPosition` (number), `displayPosition` (number), `tappedClipActionText` (string), `tappedClipActionUrl` (string), `tappedClipActionType` (string), `clipHasSecondaryActions` (boolean), `clipSecondaryActionsText` (string array), `clipSecondaryActionUrls` (string array), `clipSecondaryActionTypes` (string array), `categoryId` (string), `categoryName` (string), `categoryType` (string) | | search | `searchFilter` (string), `searchSort` (string), `searchTerm` (string), `searchFrom` (string), `isSuggestion` (boolean), `initialInput` (string), `actionType` (string), `searchResultId` (string), `searchResultTitle` (string), `searchResultSource` (string) | | organic watch time | `quartile` (number) | | page | `pageId` (string), `pageTitle` (string), `pageType` (string), `pageIndex` (number), `pageHasAction` (boolean), `pageActionText` (string), `pageActionType` (string), `pageActionUrl` (string), `pagesViewedCount` (number), `contentLength` (number) | | playback | `storyPlaybackMode` (string), `openedReason` (string), `videoStartReason` (string), `dismissedReason` (string), `isInitialBuffering` (boolean), `timeSinceBufferingBegan` (number), `durationViewedMs` (number), `isMuted` (boolean), `captionsEnabled` (boolean), `airplayEnabled` (boolean), `startPosition` (number), `endPosition` (number), `scrubDirection` (string), `completionType` (string) | | ad | `advertiserName` (string), `adId` (string), `adType` (string), `adPlacement` (string), `adStrategy` (string), `adFormat` (string), `adIndex` (number), `adResponseIdentifier` (string), `playerSessionId` (string), `adRequestId` (string), `adSlotType` (string), `adUnitId` (string), `adSource` (string), `adSourceName` (string), `adSourceId` (string), `adSourceInstanceName` (string), `adSourceInstanceId` (string), `adMediationGroupName` (string), `adMediationAbTestName` (string), `adMediationAbTestVariant` (string), `adAdapterLatencyMillis` (number), `adErrorCode` (number), `adErrorDomain` (string), `adErrorMessage` (string), `adValueMicros` (number), `adCurrencyCode` (string), `adValuePrecision` (string), `adSessionOpportunitiesCount` (number), `adSessionRequestsCount` (number), `adSessionLoadsCount` (number), `adSessionFailedToLoadCount` (number), `adSessionPaidCount` (number), `adSessionRevenueMicros` (number), `adSessionCurrencyCode` (string) | | poll | `pollAnswerId` (string) | | trivia quiz | `triviaQuizAnswerId` (string), `triviaQuizId` (string), `triviaQuizQuestionId` (string), `triviaQuizTitle` (string), `triviaQuizScore` (number) | | sharing | `shareMethod` (string) | | sheet | `sheetId` (string), `sheetTitle` (string), `sheetSize` (number) | | action | `actionClass` (string), `actionIndex` (number), `actionText` (string), `actionLinkId` (string) | | card | `cardActionType` (string), `cardActionUrl` (string), `cardAspectRatio` (string), `cardBackgroundType` (string), `cardCollectionId` (string), `cardId` (string), `cardIndex` (number), `cardSubtitle` (string), `cardTitle` (string), `audioToggleFrom` (string), `audioToggleTo` (string), `hasButton` (boolean) | | device/app | `appName` (string), `appId` (string), `appVersion` (string), `deviceModel` (string), `deviceBrand` (string), `deviceType` (string), `screenResolution` (string), `operatingSystem` (string), `osVersion` (string), `minOsVersion` (string), `targetOsVersion` (string), `languageVersion` (string) | | SDK initialization | `initializationSucceeded` (boolean), `enablePersonalization` (boolean), `enableStorytellerTracking` (boolean), `enableUserActivityTracking` (boolean), `enableAdTracking` (boolean), `enableFullVideoAnalytics` (boolean), `enableRemoteViewingStore` (boolean) | | followable category | `followableCategoryLimitActionText` (string), `followableCategoryLimitActionUrl` (string), `followableCategoryLimitDialogue` (string) | | categories | `categories` (string array), `categoryDetails` (`CategoryDetail` array), `currentCategory` (`CurrentCategoryData`) | | collection | `collection` (string), `collectionClipCount` (number) | | miscellaneous | `location` (string), `locale` (string), `itemTitle` (string), `containerTitle` (string), `metadata` (string map), `context` (string map), `isLive` (boolean) | ### 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 Display Title The `storyDisplayTitle?: string` is the display title of the Story for which the event occurred. ### Story Index The `storyIndex?: number` identifies the Story in the player/list analytics context and can accompany multiple Story and playback events. Story-player analytics use 1-based indexes; this is not limited to `OpenedStory`. ### Story Page Count The `storyPageCount?: number` 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. 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?: number` is the 1-based content Page index for Story-player events. Android excludes inserted ad pages from this content index. Search-origin and other payloads can use native source indexes; do not use it as a universal UI-array offset. ### Page Type The `pageType?: string` is the type of the page associated with the event. Examples include `image`, `video` and `poll`; other native content types can also supply a string value. ### 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.) It is supplied for relevant Story events and may be omitted for other event groups. The values for this are either `list` or `singleStory`. ### Page Has Action The `pageHasAction?: boolean` value states whether the page associated with the event contains an action. ### 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. ### Page Action Type The `pageActionType?: string` defines the type of action associated with a page, native values include `inApp`, `web`, `store`, `externalApp`, `share`, `sheet`, `story`, `storyCategory`, `clip`, `clipCollection` and `none`. ### Opened Reason The `openedReason?: string` value states how the user opened a story or clip. Common values include `storyListTap` (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` can also accompany Page, ad, sheet and instruction events when native supplies it. The values above are common examples; programmatic open reasons and other native paths can supply additional strings. ### Dismissed Reason The `dismissedReason?: string` value states the way the user dismissed a story or clip. Common values include `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` can also accompany ad and Search dismissals. Treat it as an optional string, including a custom reason passed by the host when dismissing content. ### Duration Viewed The `durationViewedMs?: number` is the native viewing duration for the Story or Clip session in milliseconds. Story dismissal duration is measured from the opening session; Android accumulates intervals marked as viewing, while iOS Story dismissal uses elapsed session time. Use the organic heartbeat events for active watch-time measurement. A new content-viewing session resets the relevant timer. For `FinishedClip`, Duration Viewed describes the Clip viewing session being finished, in milliseconds. It is not restricted to Clips entered by a swipe. ### Pages Viewed Count The `pagesViewedCount?: number` is the total number of pages a user has viewed since the most recent `OpenedStory` event with an Opened Reason of `storyListTap` or `deepLink`. This count is reset after any `DismissedStory` events. ### Content Length The `contentLength?: number` is the total duration of the page content in seconds. ### Share Method The `shareMethod?: string` is the component name of the app which the user has selected for sharing. ### 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. ### Ad Type The `adType?: string` is the type of component on which the ad is displayed. This can have values `stories` or `clips`. ### Ad Format The `adFormat?: string` represents the format of the Ad that was displayed. Examples include `customNative`, `native` and `banner`; the value depends on the ad source and format. ### Ad Placement The `adPlacement?: string` represents the placement of the ad. Full-screen examples are `Between Stories`, `Between Pages` and `Between Clips`; paid banner telemetry can use `Bottom Banner`. This is only included for ad events. ### Ad Response Identifier The `adResponseIdentifier?: string` represents the response identifier attached to the ad that was received from the ad provider. Used for debugging ad targeting. ### 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?: number` value is the duration the current buffering lasted for in milliseconds. This is only included for `BufferingEnded` events. ### Categories The `categories?: Array` value is the list of categories assigned to the story for which the event occurred. It can accompany Story, Clip, tile, Search and other content events when available. ### 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 The `triviaQuizScore?: number` 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?: number` is the native analytics index for the Clip in its row/grid or player feed. Player analytics use 1-based indexes. It can change when the feed changes; use `clipId` as the stable content identifier. ### Tile Index The `tileIndex?: number` is the 1-based index of the Story or Clip tile in the row or grid at the point it became visible. It is supplied for `TileVisible` and can also accompany external Search result taps. ### Clips Viewed The `clipsViewed?: number` 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?: number` 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?: boolean` 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. ### Clip Action Type The `clipActionType?: string` defines the type of action associated with a clip, native values include `inApp`, `web`, `store`, `externalApp`, `share`, `sheet`, `story`, `storyCategory`, `clip`, `clipCollection` and `none`. ### Clip Feed Type The `clipFeedType?: string` indicates the type of feed the clip is in, possible values are: `default`, `forYou`, `following`. ### Is Live The `isLive?: boolean` indicates if the Clip is live. ### Category Type The `categoryType?: string` specifies the type of the Clip category. ### Collection The `collection?: string` is the ID of the collection if a Story or Clip is being played from a collection. ### Collection Clip Count The `collectionClipCount?: number` represents the number of Clips in a collection. ### Location The `location?: string` represents the location of a Clip, possible values are: `On Clip` and `Category Screen`. ### Category Details The `categoryDetails?: Array` is a list of Category Detail objects. The details are the name, ID, type and placement of the category. ### Category Name The `categoryName?: string` of the category being navigated to or dismissed. ### Category ID The `categoryId?: string` of the category being navigated to or dismissed. ### Current Category The `currentCategory?: CurrentCategoryData` is the category for the row that is currently being interacted with. The information provided from this is the category title, ID and placement. It can also accompany list-tile and Search events when a current category is known. ### Locale The `locale?: string` indicates the locale setting when the event occurred. ### Item Title The `itemTitle?: string` represents the title of the item involved in the event, for Stories that's a page title, for Clips it's a Clip title. ### Action Text The `actionText?: string` represents the text on the action button of the item involved in the event. ### Container Title The `containerTitle?: string` represents the title of the container that current item is in, for Stories that's a Story title, for Clips it's a collection name. ### Metadata The `metadata?: { [key: string]: string }` contains additional metadata associated with the event. ## RN 12 organic watch-time and Search events RN 12 exposes the following values from Android 12.0.0+ and iOS 11.7.0+ through the existing `onUserActivityOccurred` subscription. Availability depends on content and tracking settings. | Enum member | Emitted value | Meaning | | ------------------------------ | -------------------- | ------------------------------------------------------------- | | `EventType.StoryHeartbeat` | `storyHeartbeat` | Cumulative active-viewing threshold for an organic Story Page | | `EventType.StoryPageQuartile` | `storyPageQuartile` | Organic Story Page progress milestone | | `EventType.ClipVideoHeartbeat` | `clipVideoHeartbeat` | Cumulative actual-playback threshold for an organic Clip | | `EventType.ClipVideoQuartile` | `clipVideoQuartile` | Fixed-duration organic Clip playback milestone | | `EventType.SearchResultTapped` | `searchResultTapped` | Configured external Search result tapped | Organic heartbeats occur at five-second cumulative active-viewing thresholds. Story tracking resets for each Page view; Clip heartbeat time continues across natural loops, while Clip quartiles reset per playback pass. Live Clips can emit heartbeats but not organic quartiles. `UserActivityData.quartile` is optional and contains `25`, `50` or `75` for the two organic quartile events. External Search-result payloads can additionally contain optional `actionType`, `searchResultId`, `searchResultTitle` and `searchResultSource`. Missing native fields are omitted. Existing event names and payload fields are unchanged.