Analytics (iOS)

Event callbacks

Video playback event callbacks

To receive video playback events, conform to the FireworkVideoPlaybackDelegate protocol, see file FireworkVideoPlaybackDelegate.swift. You could assign FireworkVideoPlaybackDelegate delegate as follows:

FireworkVideoSDK.eventTracking.videoPlaybackDelegate = // Object to receive video playback events

List of video playback events:

    /// Called when a video appears on the screen but the video playback has not started
    /// - Parameter videoPlayback: The details of the video playback
    func fireworkVideoDidRecordImpression(_ videoPlayback: VideoPlaybackDetails)

    /// Called when a video has paused playback
    /// - Parameter videoPlayback: The details of the video playback
    func fireworkVideoDidPause(_ videoPlayback: VideoPlaybackDetails)

    /// Called when a video has resumed playback
    /// - Parameter videoPlayback: The details of the video playback
    func fireworkVideoDidResume(_ videoPlayback: VideoPlaybackDetails)

    /// Called when a video has started playing
    /// - Parameter videoPlayback: The details of the video playback
    func fireworkVideoDidStartPlaying(_ videoPlayback: VideoPlaybackDetails)

    /// Called when the first quarter of the video has been played
    /// - Parameter videoPlayback: The details of the video playback
    func fireworkVideoReachedFirstQuartile(_ videoPlayback: VideoPlaybackDetails)

    /// Called when the first half of the video has been played
    /// - Parameter videoPlayback: The details of the video playback
    func fireworkVideoReachedMidPoint(_ videoPlayback: VideoPlaybackDetails)

    /// Called when the third quarter of the video has been played
    /// - Parameter videoPlayback: The details of the video playback
    func fireworkVideoReachedThirdQuartile(_ videoPlayback: VideoPlaybackDetails)

    /// Called when the video reaches end of playback.
    /// - Parameter videoPlayback: The details of the video playback
    func fireworkVideoDidFinishPlaying(_ videoPlayback: VideoPlaybackDetails)

    /// Called when the user has tapped on the CTA button that appeared during the video playback
    func fireworkVideoDidTapCTAButton(_ videoPlayback: VideoPlaybackDetails)

    /// Called when the user has tapped on the share button that appeared during the video playback
    func fireworkVideoDidTapShareButton(_ videoPlayback: VideoPlaybackDetails)

    /// Called when an ad video has started playing
    /// - Parameter videoPlayback: The details of the video playback
    func fireworkVideoDidStartPlayingAd(_ videoPlayback: VideoPlaybackDetails)

    /// Called when the ad video reaches end of playback.
    /// - Parameter videoPlayback: The details of the video playback
    func fireworkVideoDidFinishPlayingAd(_ videoPlayback: VideoPlaybackDetails)
    
    /// Called when the video is muted.
    /// - Parameter videoPlayback: The details of the video playback
    func fireworkVideoDidMute(_ videoPlayback: VideoPlaybackDetails)

    /// Called when the video is unmuted.
    /// - Parameter videoPlayback: The details of the video playback
    func fireworkVideoDidUnmute(_ videoPlayback: VideoPlaybackDetails)

    /// Called when the user closes or skips to the other video manually.
    /// - Parameter videoPlayback: The details of the video playback
    func fireworkVideoDidClose(_ videoPlayback: VideoPlaybackDetails)
    
    /// Called when the video is automatically paused.
    /// - Parameter videoPlayback: The details of the video playback
    func fireworkVideoDidAutomaticallyPause(_ videoPlayback: VideoPlaybackDetails)
    
    /// Called when the video is automatically resumed.
    /// - Parameter videoPlayback: The details of the video playback
    func fireworkVideoDidAutomaticallyResume(_ videoPlayback: VideoPlaybackDetails)

Feed event callbacks

To receive feed related events, conform to the FireworkVideoFeedDelegate protocol, see file FireworkVideoFeedDelegate.swift. You could assign FireworkVideoFeedDelegate delegate as follows:

FireworkVideoSDK.eventTracking.feedDelegate = // Object to receive feed events

List of feed events:

    /// Called when the a video thumbnail is tapped by the user
    /// - Parameter eventDetails: The details of the feed event
    func fireworkVideoDidTapThumbnail(_ eventDetails: FeedEventDetails)

Live stream event callbacks

Live stream events can be observed by assigning a receiver as the FireworkLiveStreamEventDelegate. This will provide different methods that will be invoked at the time of each event. You could assign FireworkLiveStreamEventDelegate as follows:

// Assign a delegate
FireworkVideoSDK.eventTracking.liveStreamEventDelegate = // Object to receive live stream events

List of live stream events:

/// Delegate that handles live stream events
public protocol FireworkLiveStreamEventDelegate: AnyObject {
    /// Called when a live stream starts playing.
    /// - Parameter liveStream: Details about the live stream event are included.
    func fireworkLiveStreamDidStartPlaying(_ liveStream: LiveStreamEventDetails)
    /**
     Called when a user joins an active live stream.
     - Parameter liveStream: Details about the live stream event are included.
     */
    func fireworkLiveStreamUserDidJoin(_ liveStream: LiveStreamEventDetails)
    /**
     Called when the user leaves an active live stream.
     - Parameter liveStream: Details about the live stream event are included.
     */
    func fireworkLiveStreamUserDidLeave(_ liveStream: LiveStreamEventDetails)
    /**
     Called when a user sends a message to an active live stream.
     - Parameters:
       - message: Details of the chat message sent
       - liveStream: Details about the live stream event are included.
     */
    func fireworkLiveStreamUserDidSendChat(_ message: LiveStreamMessageDetails, to liveStream: LiveStreamEventDetails)
    /**
     Called when a user sends a like to an active live stream.
     - Parameter liveStream: Details about the live stream event are included.
     */
    func fireworkLiveStreamUserDidSendLike(_ liveStream: LiveStreamEventDetails)
}

Data Tracking Level

The SDK provides a way to specify the level of data tracking that should be performed. The default value is .all. To change the data tracking level, use the following API:

// Enable SDK internal tracking
FireworkVideoSDK.analytics.dataTrackingLevel = .all
// Disable SDK internal tracking
FireworkVideoSDK.analytics.dataTrackingLevel = .none

External ad tracking configuration

We always report external ad tracking by default. You can disable it by the following codes:

FireworkVideoSDK.externalAdTrackingEnabled = false

Identifying the component that triggered the event

We can retrieve the feed ID both from our components and from the event payload. Therefore, we can use it to accurately identify which component is triggering the event.

Obtain feed ID from components and cache custom data globally

// Global map
let globalMap: [String: Any] = [:]
// Custom data
let customData = [
    "location": "home",
    "widgetType": "videoFeed"
]
let channelID = "<Encoded Channel ID>"
let playlistID = "<Encoded Playlist ID>"
let feedVC = VideoFeedViewController(
    source: .channelPlaylist(
        channelID: channelID,
        playlistID: playlistID
    )
)
// Cache custom data with feed ID
globalMap[feedVC.feedID] = customData

let videoFeedView = VideoFeedView(
    source: .channelPlaylist(
        channelID: channelID,
        playlistID: playlistID
    )
)

// Cache custom data with feed ID
globalMap[feedVC.feedID] = customData

FWSVideoFeedSwiftUIView(
    source: .channelPlaylist(
        channelID: channelID,
        playlistID: playlistID
    ),
    onGetFeedID: { feedID in
        // Cache custom data with feed ID
        globalMap[feedVC.feedID] = customData
    }
)

Get custom data from global cache via feed ID in event payload

func fireworkVideoDidRecordImpression(_ videoPlayback: VideoPlaybackDetails) {
    // Get feed id from event payload
    let feedId = videoPlayback.feedId ?? ""
    // Get custom data with feed id from global map
    let customData = globalMap[feedId]
}

func fireworkShopping(
    _ fireworkShopping: FireworkVideoShopping,
    didTapProductVariant item: SelectedProductVariant,
    forVideo video: VideoDetails
) -> Bool {
    // Get feed id from event payload
    let feedId = videoPlayback.feedId ?? ""
    // Get custom data with feed id from global map
    let customData = globalMap[feedId]
    // Here, you could write codes to navigate to the host app page.

    // Return true to customize product card click behavior
    return true
}