Firework for Developers
One-to-one Virtual ShoppingBusiness Portal
  • Welcome to Firework for Developers
  • Firework Interactive Video and One-to-many Digital Showroom
  • Web
    • Getting Started (Web)
      • Shopify
      • Magento
      • Wordpress (WooCommerce)
      • Salesforce Commerce Cloud
      • BigCommerce
    • Integration Guide for Web
      • Components
        • Hero Unit
        • Carousel / Grid
        • Storyblock (Web)
        • Player (Floating)
        • Storylink
      • Styling
      • Feed Attributes
      • Player
        • Configuration
          • Appearance
      • Video customization
        • Video Factory
        • CTA Button
        • Product cards
      • Events
        • Embed Feed and Storyblock Events
        • Video player events
        • Live stream events
        • Shopping events
      • Shopping Integration (V2)
        • Introduction
        • Shopping APIs
        • Product Hydration
        • Product Factory
        • Cart Sync
        • Tracking
          • Purchase
          • Add to cart
          • Remove from cart
          • Page viewed
        • Shopping Integration FAQ
        • Migrate from V1
      • Web SDK
      • Enhanced Picture-in-Picture
      • Privacy settings
        • Tracking settings
        • Cookies management
        • Content Security Policy
    • Telemetry console
    • Firework Service Domains
    • FAQ & Troubleshooting (Web)
  • Android SDK
    • Integration Guide for Android SDK
      • Getting Started (Android)
      • Video Feed (Android)
        • Video Feed Layouts (Android)
        • Channel Feed (Android)
        • Discover Feed (Android)
        • Playlist Feed (Android)
        • Dynamic Content Feed
        • Channel Hashtags Feed
        • Sku Feed
        • Single Content Feed
        • Configure Video Feed
      • Customization
        • CTA
      • Analytics (Android)
      • Shoppable Videos (Android)
        • Product Hydration
      • Live Stream Support (Android)
      • Video Player (Android)
      • StoryBlock (Android)
      • Share & Video Deep linking
      • Ad Support (Android)
      • Configure Video Advertisements Source (Android)
      • In-app Language Switches
      • Compose support(Android)
    • Sample App (Android)
    • FAQ & Troubleshooting (Android)
    • Changelog (Android)
  • iOS SDK
    • Integration Guide for iOS SDK
      • Getting Started (iOS)
      • ATT compliance (iOS)
      • Video Feed (iOS)
        • Discover Feed(iOS)
        • Channel Feed (iOS)
        • Playlist Feed (iOS)
        • Playlist Group Feed (iOS)
        • Dynamic Content (iOS)
        • Hashtag Playlist (iOS)
        • SKU Playlist (iOS)
        • Video Ads (iOS)
        • Video Feed Layouts (iOS)
      • Story Block (iOS)
      • Customization (iOS)
        • Video feed configurations (iOS)
        • Player configurations (iOS)
        • Shopping configurations (iOS)
          • Customize product card on videos using the custom view (iOS)
        • Customize click behaviors (iOS)
      • Shopping (iOS)
      • Live Stream Support (iOS)
      • Analytics (iOS)
      • Share & Deeplinking(iOS)
      • Ad Support (iOS)
    • Sample App (iOS)
    • FAQ & Troubleshooting (iOS)
    • Changelog (iOS)
  • React Native SDK
    • Integration Guide for React Native SDK V2
      • Getting Started (React Native)
      • ATT compliance React Native (iOS)
      • Video Feed (React Native)
      • Story Block (React Native)
      • Customization (React Native)
        • Video feed configurations (React Native)
        • Player configurations (React Native)
        • Shopping configurations (React Native)
          • Customize product card on videos using the custom view (React Native)
        • Customize click behaviors (React Native)
      • Shopping (React Native)
      • Live Stream Support (React Native)
      • Ad Support (React Native)
      • Analytics (React Native)
      • App-level Language Setting (React Native)
      • Share & Video Deeplinking (React Native)
      • Android Style (React Native)
      • Inject Android Image Loader (React Native)
      • Integrate SDKs in Hybrid React Native and native Apps
      • Reference (React Native)
      • Sample App (React Native)
      • FAQ & Troubleshooting (React Native)
      • Changelog (React Native)
  • Flutter SDK
    • Integration Guide for Flutter SDK V2
      • Getting Started (Flutter)
      • ATT compliance Flutter (iOS)
      • Video Feed (Flutter)
      • Story Block (Flutter)
      • Customization (Flutter)
        • Video feed configurations (Flutter)
        • Player configurations (Flutter)
        • Shopping configurations (Flutter)
          • Customize product card on videos using the custom view (Flutter)
        • Customize click behaviors (Flutter)
      • Live Stream Support (Flutter)
      • Shopping (Flutter)
      • Ad Support (Flutter)
      • Analytics (Flutter)
      • App-level Language Setting (Flutter)
      • Share & Video Deeplinking (Flutter)
      • Inject Android Image Loader (Flutter)
      • Android Style (Flutter)
      • Integrate SDKs in Hybrid Flutter and native Apps
      • Reference (Flutter)
      • Sample App (Flutter)
      • FAQ & Troubleshooting (Flutter)
      • Changelog (Flutter)
  • Help Articles
    • Importing Products to Firework
    • Adding products to a video
    • Displaying product videos on product pages using hashtag filtering(Web)
    • Syncing Carts
    • Encoded IDs
Powered by GitBook
On this page
  • Firework Analytics
  • Supported events
  • Video Lifecycle Playback Tracking
  • Video Analytics Events Tracking
  • Share Button Analytics Events Tracking
  • CTA Button Analytics Events Tracking
  • Livestream Analytics Events Tracking

Was this helpful?

  1. Android SDK
  2. Integration Guide for Android SDK

Analytics (Android)

PreviousCTANextShoppable Videos (Android)

Last updated 3 months ago

Was this helpful?

When using our app's SDK, it can be useful to gain deeper insights into what's happening within the SDK itself. This document serves as a guide to the analytics events available through Firework Android SDK API.

Firework Analytics

Before we dive into the analytics events, let's take a moment to review how to register and unregister for analytics tracking.

Note that not unregistering from the analytics API can lead to memory leaks

Registering and unregistering for firework analytics

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    FireworkSdk.analytics.register(this)
}

override fun onDestroy() {
    super.onDestroy()
    FireworkSdk.analytics.unregister(this)
}
@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    FireworkSdk.INSTANCE.getAnalytics().register(this);
}

@Override
protected void onDestroy() {
    super.onDestroy();
    FireworkSdk.INSTANCE.getAnalytics().unregister(this);
}

Now let's see how to subscribe to the specific analytics event

In general, when you want to register for a specific event you simply define a function with FwAnalyticCallable like below:

@FwAnalyticCallable
fun onSpecificEvent(event: SpecificEventType) {
    // Do whatever you want with the event
}
@FwAnalyticCallable
void onSpecificEvent(SpecificEventType event){

}

To register for the specific event simply add the '@FwAnalyticCallable' annotation to your function, and pass in the desired event type as a parameter. This gives you the flexibility to register for any analytics event, making it easy to capture and analyse the specific data points you need for your app.

Supported events

Video Lifecycle Playback Tracking

If the host app needs to monitor events that occur during video playback, the Firework SDK offers a simple solution. The SDK enables the host app to easily observe and track events for each video that is played by the user.

Here is the list of available playback events:

  1. OnImpression: sent when the video is viewed in full-screen player or compact story block.

  2. OnPrepared: sent when the video is prepared for playing but has not started yet.

  3. OnBuffering: sent when video is buffering.

  4. OnIdle: sent when video is buffered and prepared fully but has not started to play.

  5. OnRepeat: sent when video is repeated.

  6. OnEnded: sent when video is finished. It is not sent when the user swipes to the next video, it's only sent when the video reaches to the end of the playback progress.

  7. OnError: sent when video cannot be played due to an error.

  8. OnSeek: sent when video playback is moved to a new position.

  9. OnVideoSizeChanged: sent when the dimension of the video has been changed.

  10. OnPlaybackProgressChanged: sent during the payback and contains current progress value in seconds.

  11. OnFirstQuartile: sent when the first 25% of the video has passed

  12. OnSecondQuartile: sent when the first 50% of the video has passed

  13. OnThirdQuartile: sent when the first 75% of the video has passed

  14. OnLast90PercentOfTheVideo: sent when the first 90% of the video has passed

  15. OnStarted: sent when the content starts for the first time in the player.

  16. OnPaused: sent when the content is paused.

  17. OnResumed: When the content is resumed.

Example of subscribing to the playback event

@FwAnalyticCallable
fun onPlaybackEvent(event: PlayerLifecycleAnalyticsEvent) {
    when (event) {
        is PlayerLifecycleAnalyticsEvent.OnBuffering,
        is PlayerLifecycleAnalyticsEvent.OnEnded,
        is PlayerLifecycleAnalyticsEvent.OnError,
        is PlayerLifecycleAnalyticsEvent.OnIdle,
        is PlayerLifecycleAnalyticsEvent.OnPlaybackProgressChanged,
        is PlayerLifecycleAnalyticsEvent.OnImpression,
        is PlayerLifecycleAnalyticsEvent.OnPrepared,
        is PlayerLifecycleAnalyticsEvent.OnFirstQuartile,
        is PlayerLifecycleAnalyticsEvent.OnLast90PercentOfTheVideo,
        is PlayerLifecycleAnalyticsEvent.OnSecondQuartile,
        is PlayerLifecycleAnalyticsEvent.OnThirdQuartile,
        is PlayerLifecycleAnalyticsEvent.OnRepeat,
        is PlayerLifecycleAnalyticsEvent.OnSeek,
        is PlayerLifecycleAnalyticsEvent.OnVideoSizeChanged,
        is PlayerLifecycleAnalyticsEvent.OnStarted,
        is PlayerLifecycleAnalyticsEvent.OnPaused,
        is PlayerLifecycleAnalyticsEvent.OnResumed -> Log.i("fw-analytics-playback", event.videoInfo.toString())
    }
}
@FwAnalyticCallable
void onPlaybackEvent(PlayerLifecycleAnalyticsEvent event){
if(event instanceof PlayerLifecycleAnalyticsEvent.OnPrepared
        || event instanceof PlayerLifecycleAnalyticsEvent.OnBuffering
        || event instanceof PlayerLifecycleAnalyticsEvent.OnEnded
        || event instanceof PlayerLifecycleAnalyticsEvent.OnError
        || event instanceof PlayerLifecycleAnalyticsEvent.OnIdle
        || event instanceof PlayerLifecycleAnalyticsEvent.OnPlaybackProgressChanged
        || event instanceof PlayerLifecycleAnalyticsEvent.OnPrepared
        || event instanceof PlayerLifecycleAnalyticsEvent.OnFirstQuartile
        || event instanceof PlayerLifecycleAnalyticsEvent.OnLast90PercentOfTheVideo
        || event instanceof PlayerLifecycleAnalyticsEvent.OnSecondQuartile
        || event instanceof PlayerLifecycleAnalyticsEvent.OnThirdQuartile
        || event instanceof PlayerLifecycleAnalyticsEvent.OnRepeat
        || event instanceof PlayerLifecycleAnalyticsEvent.OnSeek
        || event instanceof PlayerLifecycleAnalyticsEvent.OnVideoSizeChanged
        || event instanceof PlayerLifecycleAnalyticsEvent.OnStarted
        || event instanceof PlayerLifecycleAnalyticsEvent.OnPaused
        || event instanceof  PlayerLifecycleAnalyticsEvent.OnResumed){
    Log.i("fw-analytics-playback", event.getVideoInfo().toString());
}
}

Video Analytics Events Tracking

We also provide data analytics callbacks that adhere to the VAST protocol. Unlike the PlayerLifecycleAnalyticsEvent, these callbacks will not repeatedly activate for the same video data analytics events during automatic playback, unless the user manually switches to a previous or next video.

Here is the list of video analysis events:

  1. OnImpression: sent when the first frame of the creative is displayed.

  2. OnStarted: this event is used to indicate that an individual creative within the ad was loaded and playback began..

  3. OnFirstQuartile: the creative played for at least 25% of the total duration

  4. OnSecondQuartile: the creative played for at least 50% of the total duration

  5. OnThirdQuartile: the creative played for at least 75% of the total duration

  6. OnLast90PercentOfTheVideo: the creative played for at least 90% of the total duration

  7. OnEnded: sent when the creative played to the end at normal speed..

  8. OnClickMute: sent when the user activated the mute control and muted the creative.

  9. OnClickUnmute: sent when the user activated the mute control and unmuted the creative.

  10. OnClickToFullScreen: sent when the user activated a control to extend the video player to the edges of the viewer’s screen

  11. OnClickToQuitFullScreen: sent when the the user activated the control to close or enter into pip mode

  12. OnClickToPlay: sent when the user clicked the start control and start the creative from beginning.

  13. OnClickToPause: sent when the user clicked the pause control and stopped the creative.

  14. OnClickToResume: sent when the user activated the resume control after the creative had been stopped or paused.

Example of subscribing to the playback event

    @FwAnalyticCallable
    fun onVideoAnalytics(event: VideoAnalyticsEvent) {
        when (event){
            is VideoAnalyticsEvent.OnImpression,
            is VideoAnalyticsEvent.OnStarted,
            is VideoAnalyticsEvent.OnFirstQuartile,
            is VideoAnalyticsEvent.OnSecondQuartile,
            is VideoAnalyticsEvent.OnThirdQuartile,
            is VideoAnalyticsEvent.OnLast90PercentOfTheVideo,
            is VideoAnalyticsEvent.OnEnded,
            is VideoAnalyticsEvent.OnClickMute,
            is VideoAnalyticsEvent.OnClickUnMute,
            is VideoAnalyticsEvent.OnClickToPlay,
            is VideoAnalyticsEvent.OnClickToPause,
            is VideoAnalyticsEvent.OnClickToResume,
            is VideoAnalyticsEvent.OnClickToFullScreen,
            is VideoAnalyticsEvent.OnClickToQuitFullScreen->
                Log.d("Video Analysis" ,"Video id: ${event.videoInfo?.id}}")
        }
    }

Share Button Analytics Events Tracking

ShareButtonAnalyticsEvent: This event will be called when the share button on the video player page is being called by the user. All the description about the VideoInfo is true here as well.

@FwAnalyticCallable
fun onShareButtonClicked(event: ShareButtonAnalyticsEvent) {
    Log.i("fw-analytics-share", event.videoInfo.toString())
}

You can simply use the VideoInfo object to obtain more details.

CTA Button Analytics Events Tracking

CtaButtonClickAnalyticsEvent: This event will be called when the CTA button is pressed by the user. By default, the SDK will open the CTA url in the default browser of the phone, however, if you set the SDK to handle CTA action in the ViewOptions true the SDK will not do anything and just report that CTA_clicked event to the host app. All the description about the VideoInfo is true here as well.

@FwAnalyticCallable
fun onCtaButtonClicked(event: CtaButtonClickAnalyticsEvent) {
    Log.i("fw-analytics-cta", event.label + " " + event.actionUrl)

    if (!isCtaHandledBySDK) {
        CtaModalActivity.start(this, event)
    }
}

val playerOptions = PlayerOption.Builder()
    .sdkHandleCtaButtonClick(true) // This value here determines whether the SDK should handle the CTA click or not
    .build()
    
ViewOptions
        .Builder()
        .playerOption(playerOptions)
        .ctaOption(ctaOptions)
        .build()

Livestream Analytics Events Tracking

LivestreamAnalyticEvent: There are multiple events which may lead to this callback:

    @FwAnalyticCallable
    fun onLivestreamEvent(event: LivestreamAnalyticEvent) {
    when (event) {
        is LivestreamAnalyticEvent.UserSentChatMessage -> {
            Log.i("fw-analytics-livestream", "User sent chat message: $event")
        }

        is LivestreamAnalyticEvent.UserJoined -> {
            Log.i("fw-analytics-livestream", "User joined: $event")
        }

        is LivestreamAnalyticEvent.UserLeft -> {
            Log.i("fw-analytics-livestream", "User left: $event")
        }

        is LivestreamAnalyticEvent.UserSentLike -> {
            Log.i("fw-analytics-livestream", "User sent like: $event")
        }
    }
}

Capturing events in smaller scopes

As you can see in the example code below it is possible to register only for OnStarted event instead of registering for all events.

@FwAnalyticCallable
fun onStartedEvent(event: PlayerLifecycleAnalyticsEvent.OnStarted) {
    Log.i("fw-analytics-playback", "OnStarted ${event.videoInfo}")
}
@FwAnalyticCallable
void onStartedEvent(PlayerLifecycleAnalyticsEvent.OnStarted event){
    Log.i("fw-analytics-playback", "OnStarted"+event.getVideoInfo());
}

Events payload

All playback analytics events contains the following info:

    val videoInfo: VideoInfo // information about the video
    val progress: Double // video progress in seconds

VideoInfo object contains the following information:

val id: String, // content id
val caption: String, // content caption (title)
val duration: Double, // duration in seconds
val badge: String?, // text of the video badge
val playerHeight: Int?, // content width
val playerWidth: Int?, // content height
val hasCta: Boolean, // true if the video has "call to aciton" button
val isAd: Boolean // true if the video is an Ad video
val hashtags: List<String>, // Hashtags list added to the video
val feedType: String, // The feed resource type
val channelId: String? // Channel ID if the feed resource has one
val playlistId: String? // Playlist ID if the feed resource has one
val autoPlay: Boolean? // Define if the video is played automatically

The Lifecycle Playback Event is triggered every time the video plays, even if there's just one video in the playlist on a loop. It pertains to the playback status of the video itself. If you need non-repetitive callbacks for data analytics, please refer to Video Analysis Events Tracking.

PlayerLifecycleAnalyticsEvent is a parent event for other playback events. If host app subscribes to this event, it will receive all playback event that are available.

For example, if a playlist video is looping, this callback is only triggered the first time the playlist plays.

❗
❗
❗
❗