Analytics

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

Kotlin

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

override fun onDestroy() {
    super.onDestroy()
    FireworkSdk.analytics.unregister(this)
}

Java

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

Kotlin

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

Java

@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 Playback Analytics Events 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, providing valuable insights into user engagement and behavior.

List of video playback events:

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

Here is the list of available playback events:

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

2. OnBuffering: sent when video is buffering.

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

4. OnRepeat: sent when video is repeated.

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

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

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

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

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

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

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

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

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

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

15. OnPaused: sent when the content is paused.

16. OnResumed: When the content is resumed.

Example of subscribing to the playback event

Kotlin

@FwAnalyticCallable
fun onPlaybackEvent(event: PlayerLifecycleAnalyticsEvent) {
    when (event) {
        is PlayerLifecycleAnalyticsEvent.OnBuffering,
        is PlayerLifecycleAnalyticsEvent.OnEnded,
        is PlayerLifecycleAnalyticsEvent.OnError,
        is PlayerLifecycleAnalyticsEvent.OnIdle,
        is PlayerLifecycleAnalyticsEvent.OnPlaybackProgressChanged,
        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())
    }
}

Java

@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());
}
}

Capturing events in smaller scopes

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

Kotlin

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

Java

@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

Share Button Click Tracking

ShareButtonClickListener: This listener will be called when the share button on the video player page is being called by the user.

Kotlin

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

Java

@FwAnalyticCallable
void onShareButtonClicked(ShareButtonAnalyticsEvent event){
    Log.i("fw-analytics-share", "OnShare"+event.getVideoInfo());
}

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

CTA Button Click Tracking

CtaButtonClickHandler: This handler is 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.

Kotlin

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

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

Java

@FwAnalyticCallable
        void onCtaButtonClicked(CtaButtonClickAnalyticsEvent event){
        Log.i("fw-analytics-cta", "OnCTA"+event.getVideoInfo());
}

PlayerOption playerOptions = new PlayerOption.Builder()
    .sdkHandleCtaButtonClick(false) // This value here determines whether the SDK should handle the CTA click or not
    .build();
    
CtaOption ctaOptions = new CtaOption.Builder()
        .ctaDelay(new CtaDelay(2.0f, CtaDelayUnit.SECONDS)).build();
    
ViewOptions viewOptions = new ViewOptions.Builder()j
                .playerOption(playerOptions)
                .ctaOption(ctaOptions)
                .build();