The VideoPlaybackEventName enum defines various events related to video playback and user interactions.
impression
Definition: The video is shown to the user. This event is typically triggered when the video player becomes visible in the viewport.
start
Definition: Video playback has started. This event is triggered when the video begins playing for the first time or after being reloaded.
pause
Definition: Video playback has been paused, either by the user or programmatically.
resume
Definition: Video playback has resumed after being paused.
firstQuartile
Definition: Video playback has reached 25% of its total duration.
midpoint
Definition: Video playback has reached 50% (the midpoint) of its total duration.
thirdQuartile
Definition: Video playback has reached 75% of its total duration.
complete
Definition: Video playback has reached 100% of its total duration
adStart
Definition: An advertisement video has started playing.
adEnd
Definition: An advertisement video has finished playing.
clickCTA
Definition: A visitor (user) has clicked on a Call-To-Action (CTA) button associated with the video (if available). eg: "Show Now" Button
clickShare
Definition: A user has clicked on a "Share" button associated with the video.
FireworkSDK.getInstance().onVideoPlayback = (event) {
if (event != null) {
// Get feed id
final feedId = event.info.feedId ?? "";
// Get video id
final videoId = event.info.videoId ?? "";
// Get video type, the possible values for videoType
// are: VideoType.ad, VideoType.video, and VideoType.livestream.
final videoType = event.info.videoType;
// Get live stream status, the possible values for livestreamStatus
// are: LiveStreamStatus.idle, LiveStreamStatus.live, LiveStreamStatus.completed,
// and LiveStreamStatus.replay
final livestreamStatus = event.info.liveStreamStatus;
// The possible values for widgetType
// are: FWWidgetType.videoFeed and FWWidgetType.storyBlock
final widgetType = FireworkSDK.getInstance().getWidgetType(feedId);
switch (event.eventName) {
case VideoPlaybackEventName.impression:
/// When video is shown to the user.
break;
case VideoPlaybackEventName.start:
/// Video started.
break;
case VideoPlaybackEventName.pause:
/// Video paused.
break;
case VideoPlaybackEventName.resume:
/// Video resume.
break;
case VideoPlaybackEventName.firstQuartile:
/// Video reached 25%.
break;
case VideoPlaybackEventName.midpoint:
/// Video reached 50%.
break;
case VideoPlaybackEventName.thirdQuartile:
/// Video reached 75%.
break;
case VideoPlaybackEventName.complete:
/// Video reached 100% or video was closed manually.
break;
case VideoPlaybackEventName.adStart:
/// When ad video start playing.
break;
case VideoPlaybackEventName.adEnd:
/// When ad video finishes playing.
break;
case VideoPlaybackEventName.clickCTA:
/// When a visitor clicks on CTA button (if available).
break;
case VideoPlaybackEventName.clickShare:
/// When user clicks on "Share" button.
break;
}
}
};
Video Feed Click Events
This callback is to provide that for your application react to user interactions within video feeds, retrieve details about the clicked video and its feed, and understand the context (like video type or live stream status) to perform custom actions.
FireworkSDK.getInstance().onVideoFeedClick = (event) {
// Get feed id
final feedId = event?.info.feedId ?? "";
// Get video id
final videoId = event?.info.id ?? "";
// Get video type, the possible values for videoType
// are: VideoType.ad, VideoType.video, and VideoType.livestream.
final videoType = event?.info.videoType;
// Get live stream status, the possible values for livestreamStatus
// are: LiveStreamStatus.idle, LiveStreamStatus.live, LiveStreamStatus.completed,
// and LiveStreamStatus.replay
final livestreamStatus = event?.info.liveStreamStatus;
// The possible values for widgetType
// are: FWWidgetType.videoFeed and FWWidgetType.storyBlock
final widgetType = FireworkSDK.getInstance().getWidgetType(feedId);
};
Livestream User Events
Definitions
userDidjoin
Definition: This event is triggered when a user successfully joins the live stream session. It signifies a new participant has entered the viewing experience.
userDidLeave
Definition: This event is triggered when a user leaves the live stream session. This could be due to the user actively closing the stream, navigating away, or a disconnection.
userSendLike
Definition: This event is triggered when a user sends a "like" within the live stream interface. It indicates user engagement and appreciation for the content.
FireworkSDK.getInstance().liveStream.onLiveStreamEvent = (event) {
if (event != null) {
// Get feed id
final feedId = event.info.feedId ?? "";
// Get video id
final videoId = event.info.id ?? "";
// Get video type, the possible values for videoType
// are: VideoType.ad, VideoType.video, and VideoType.livestream.
final videoType = event.info.videoType;
// Get live stream status, the possible values for livestreamStatus
// are: LiveStreamStatus.idle, LiveStreamStatus.live, LiveStreamStatus.completed,
// and LiveStreamStatus.replay
final livestreamStatus = event.info.liveStreamStatus;
// The possible values for widgetType
// are: FWWidgetType.videoFeed and FWWidgetType.storyBlock
final widgetType = FireworkSDK.getInstance().getWidgetType(feedId);
switch (event.eventName) {
case LiveStreamEventName.userDidjoin:
print("User joins the livestream");
break;
case LiveStreamEventName.userDidLeave:
print("User leaves the livestream");
break;
case LiveStreamEventName.userSendLike:
print("User sends like in the livestream");
break;
}
}
};
Livestream Chat Event
This event is to provide for your application react to user chat behavior. It will be invoked when user sent a message on the livestream.
FireworkSDK.getInstance().liveStream.onLiveStreamChatEvent = (event) {
if (event != null) {
// Get feed id
final feedId = event.liveStreamfeedId ?? "";
// Get video id
final videoId = event.liveStream.id ?? "";
// Get video type, the possible values for videoType
// are: VideoType.ad, VideoType.video, and VideoType.livestream.
final videoType = event.liveStream.videoType;
// Get live stream status, the possible values for livestreamStatus
// are: LiveStreamStatus.idle, LiveStreamStatus.live, LiveStreamStatus.completed,
// and LiveStreamStatus.replay
final livestreamStatus = event.liveStream.liveStreamStatus;
// The possible values for widgetType
// are: FWWidgetType.videoFeed and FWWidgetType.storyBlock
final widgetType = FireworkSDK.getInstance().getWidgetType(feedId);
switch (event.eventName) {
case LiveStreamChatEventName.userSendChat:
print("User sends chat message in the livestream");
break;
}
}
};
Product Click Events
Outstream Product Description Page
FireworkSDK.getInstance().shopping.onCustomTapProductCard =
(CustomTapProductCardEvent? event) async {
// Get feed id
final feedId = event?.video.feedId ?? "";
// Get video id
final videoId = event?.video.videoId ?? "";
// Get video type, the possible values for videoType
// are: VideoType.ad, VideoType.video, and VideoType.livestream.
final videoType = event?.video.videoType;
// Get live stream status, the possible values for livestreamStatus
// are: LiveStreamStatus.idle, LiveStreamStatus.live, LiveStreamStatus.completed,
// and LiveStreamStatus.replay
final livestreamStatus = event?.video.liveStreamStatus;
// The possible values for widgetType
// are: FWWidgetType.videoFeed and FWWidgetType.storyBlock
final widgetType = FireworkSDK.getInstance().getWidgetType(feedId);
final result =
await FireworkSDK.getInstance().navigator.startFloatingPlayer();
if (!result) {
// When the result is false, the current fullscreen player may not
// enable the floating player. In that case, we could call the
// following method to close the fullscreen player.
await FireworkSDK.getInstance().navigator.popNativeContainer();
}
// If the context is available, you could also call
// Navigator.of(context).pushNamed to push the Flutter link content page.
globalNavigatorKey.currentState?.pushNamed('/link_content', arguments: {
"url": event?.url,
});
};
Instream Product Description Page
FireworkSDK.getInstance().shopping.onClickProduct =
(ClickProductEvent? event) async {
// Get feed id
final feedId = event?.video.feedId ?? "";
// Get video id
final videoId = event?.video.videoId ?? "";
// Get video type, the possible values for videoType
// are: VideoType.ad, VideoType.video, and VideoType.livestream.
final videoType = event?.video.videoType;
// Get live stream status, the possible values for livestreamStatus
// are: LiveStreamStatus.idle, LiveStreamStatus.live, LiveStreamStatus.completed,
// and LiveStreamStatus.replay
final livestreamStatus = event?.video.liveStreamStatus;
// The possible values for widgetType
// are: FWWidgetType.videoFeed and FWWidgetType.storyBlock
final widgetType = FireworkSDK.getInstance().getWidgetType(feedId);
};
Shopping Call-To-Action Click Events
When visitor (user) has clicked on a Call-To-Action (CTA) button on the shopping panel, this event will be trigged.
FireworkSDK.getInstance().shopping.onShoppingCTA =
(ShoppingCTAEvent? event) async {
// Get feed id
final feedId = event?.video.feedId ?? "";
// Get video id
final videoId = event?.video.videoId ?? "";
// Get video type, the possible values for videoType
// are: VideoType.ad, VideoType.video, and VideoType.livestream.
final videoType = event?.video.videoType;
// Get live stream status, the possible values for livestreamStatus
// are: LiveStreamStatus.idle, LiveStreamStatus.live, LiveStreamStatus.completed,
// and LiveStreamStatus.replay
final livestreamStatus = event?.video.liveStreamStatus;
// The possible values for widgetType
// are: FWWidgetType.videoFeed and FWWidgetType.storyBlock
final widgetType = FireworkSDK.getInstance().getWidgetType(feedId);
final result =
await FireworkSDK.getInstance().navigator.startFloatingPlayer();
if (!result) {
// When the result is false, the current fullscreen player may not
// enable the floating player. In that case, we could call the
// following method to close the fullscreen player.
await FireworkSDK.getInstance().navigator.popNativeContainer();
}
Future.delayed(const Duration(seconds: 0), () {
// If the context is available, you could also call
// Navigator.of(context).pushNamed to push the Flutter link content page.
globalNavigatorKey.currentState?.pushNamed('/link_content', arguments: {
"url": event?.url,
});
});
return ShoppingCTAResult(
res: ShoppingCTARes.success,
);
};
Video Overlay Call-To-Action Click Event
FireworkSDK.getInstance().onCustomCTAClick =
(CustomCTAClickEvent? event) async {
// Get feed id
final feedId = event?.video.feedId ?? "";
// Get video id
final videoId = event?.video.videoId ?? "";
// Get video type, the possible values for videoType
// are: VideoType.ad, VideoType.video, and VideoType.livestream.
final videoType = event?.video.videoType;
// Get live stream status, the possible values for livestreamStatus
// are: LiveStreamStatus.idle, LiveStreamStatus.live, LiveStreamStatus.completed,
// and LiveStreamStatus.replay
final livestreamStatus = event?.video.liveStreamStatus;
// The possible values for widgetType
// are: FWWidgetType.videoFeed and FWWidgetType.storyBlock
final widgetType = FireworkSDK.getInstance().getWidgetType(feedId);
final result =
await FireworkSDK.getInstance().navigator.startFloatingPlayer();
if (!result) {
// When the result is false, the current fullscreen player may not
// enable the floating player. In that case, we could call the
// following method to close the fullscreen player.
await FireworkSDK.getInstance().navigator.popNativeContainer();
}
// If the context is available, you could also call
// Navigator.of(context).pushNamed to push the Flutter link content page.
globalNavigatorKey.currentState?.pushNamed('/link_content', arguments: {
"url": event?.url ?? '',
});
};
FireworkSDK.getInstance().onVideoPlayback =
(VideoPlaybackEvent? event) async {
if (event != null) {
final eventName = event.eventName;
// Get feed id
final feedId = event.info.feedId ?? "";
// Get video id
final videoId = event.info.videoId ?? "";
// Get video type, the possible values for videoType
// are: VideoType.ad, VideoType.video, and VideoType.livestream.
final videoType = event.info.videoType;
// Get live stream status, the possible values for livestreamStatus
// are: LiveStreamStatus.idle, LiveStreamStatus.live, LiveStreamStatus.completed,
// and LiveStreamStatus.replay
final livestreamStatus = event.info.liveStreamStatus;
// The possible values for widgetType
// are: FWWidgetType.videoFeed and FWWidgetType.storyBlock
final widgetType = FireworkSDK.getInstance().getWidgetType(feedId);
switch (eventName) {
case VideoPlaybackEventName.clickCTA:
/// When a visitor clicks on CTA button (if available).
break;
default:
break;
}
}
};
Purchase Tracking
FireworkSDK.getInstance().trackPurchase(
TrackPurchaseParameters(
orderId: "<Order ID of User Purchase>",
value: "total purchase value",
currencyCode: "e.g. USD",
countryCode: "e.g. US",
additionalInfo: <String, String>{
"additionalKey1": "additionalValue1",
"additionalKey2": "additionalValue2",
"additionalKey3": "additionalValue3"
},
),
);
Conversion Tracking
Sample use case
When a user clicks the "Shop now" button on the product card, we aim to track the specific entry they interacted with. This entry includes details such as the widget type (video feed or story block) and the widget title.
Get feed id for VideoFeed and StoryBlock during widget initialization
You could use onVideoFeedGetFeedId callback to get feed id for VideoFeed and StoryBlock during widget initialization. The related reference links are:
Map<String, String> globalMap = <String, String>{};
VideoFeed(
height: 200,
source: VideoFeedSource.discover,
onVideoFeedGetFeedId: (feedId) {
// The host app could store some custom info based on the feed id,
// such as widget name.
globalMap[feedId] = "VideoFeed Widget1";
},
);
VideoFeed(
height: 200,
source: VideoFeedSource.discover,
onVideoFeedGetFeedId: (feedId) {
// The host app could store some custom info based on the feed id,
// such as widget name.
globalMap[feedId] = "VideoFeed Widget2";
},
);
StoryBlock(
height: 200,
source: StoryBlockSource.discover,
onStoryBlockGetFeedId: (feedId) {
// The host app could store some custom info based on the feed id,
// such as widget name.
globalMap[feedId] = "StoryBlock Widget1";
},
);
StoryBlock(
height: 200,
source: StoryBlockSource.discover,
onStoryBlockGetFeedId: (feedId) {
// The host app could store some custom info based on the feed id,
// such as widget name.
globalMap[feedId] = "StoryBlock Widget2";
},
);
Get data from onShoppingCTA callback
Then, the host app could get feed id, video id, video type, live stream status, widget type and custom info(such as widget name) from onShoppingCTA callback. For example:
FireworkSDK.getInstance().shopping.onShoppingCTA = async (event: ShoppingCTAEvent) => {
// Get feed id
final feedId = event?.video.feedId ?? "";
// Get custom info based on the feed id
final widgetName = globalMap[feedId];
// Get widget type based on feed id
// The possible values for widgetType
// are: FWWidgetType.videoFeed and FWWidgetType.storyBlock
final widgetType = FireworkSDK.getInstance().getWidgetType(feedId);
// Get video id
final videoId = event?.video.videoId ?? "";
// Get video type, the possible values for videoType
// are: VideoType.ad, VideoType.video, and VideoType.livestream.
final videoType = event?.video.videoType;
// Get live stream status, the possible values for livestreamStatus
// are: LiveStreamStatus.idle, LiveStreamStatus.live, LiveStreamStatus.completed,
// and LiveStreamStatus.replay
final livestreamStatus = event?.video.liveStreamStatus;
}
In addition to onShoppingCTA callback, we could also get feed id, video id, video type, live stream status, widget type and custom info(such as widget name) from other event callbacks, such as:
FireworkSDK.getInstance().onVideoPlayback = (event) {
if (event != null) {
// Get feed id
final feedId = event.info.feedId ?? "";
// Get widget type based on feed id
// The possible values for widgetType
// are: FWWidgetType.videoFeed and FWWidgetType.storyBlock
final widgetType = FireworkSDK.getInstance().getWidgetType(feedId);
// Get custom info based on the feed id
final widgetName = globalMap[feedId];
// Get video id
final videoId = event.info.videoId ?? "";
// Get video type, the possible values for videoType
// are: VideoType.ad, VideoType.video, and VideoType.livestream.
final videoType = event.info.videoType;
// Get live stream status, the possible values for livestreamStatus
// are: LiveStreamStatus.idle, LiveStreamStatus.live, LiveStreamStatus.completed,
// and LiveStreamStatus.replay
final livestreamStatus = event.info.liveStreamStatus;
}
};
FireworkSDK.getInstance().onVideoFeedClick = (event) {
// Get feed id
final feedId = event?.info.feedId ?? "";
// Get widget type based on feed id
// The possible values for widgetType
// are: FWWidgetType.videoFeed and FWWidgetType.storyBlock
final widgetType = FireworkSDK.getInstance().getWidgetType(feedId);
// Get custom info based on the feed id
final widgetName = globalMap[feedId];
// Get video id
final videoId = event?.info.id ?? "";
// Get video type, the possible values for videoType
// are: VideoType.ad, VideoType.video, and VideoType.livestream.
final videoType = event?.info.videoType;
// Get live stream status, the possible values for livestreamStatus
// are: LiveStreamStatus.idle, LiveStreamStatus.live, LiveStreamStatus.completed,
// and LiveStreamStatus.replay
final livestreamStatus = event?.info.liveStreamStatus;
};
FireworkSDK.getInstance().liveStream.onLiveStreamEvent = (event) {
if (event != null) {
// Get feed id
final feedId = event.info.feedId ?? "";
// Get widget type based on feed id
// The possible values for widgetType
// are: FWWidgetType.videoFeed and FWWidgetType.storyBlock
final widgetType = FireworkSDK.getInstance().getWidgetType(feedId);
// Get custom info based on the feed id
final widgetName = globalMap[feedId];
// Get video id
final videoId = event.info.id ?? "";
// Get video type, the possible values for videoType
// are: VideoType.ad, VideoType.video, and VideoType.livestream.
final videoType = event.info.videoType;
// Get live stream status, the possible values for livestreamStatus
// are: LiveStreamStatus.idle, LiveStreamStatus.live, LiveStreamStatus.completed,
// and LiveStreamStatus.replay
final livestreamStatus = event.info.liveStreamStatus;
}
};
FireworkSDK.getInstance().liveStream.onLiveStreamChatEvent = (event) {
if (event != null) {
// Get feed id
final feedId = event.liveStreamfeedId ?? "";
// Get widget type based on feed id
// The possible values for widgetType
// are: FWWidgetType.videoFeed and FWWidgetType.storyBlock
final widgetType = FireworkSDK.getInstance().getWidgetType(feedId);
// Get custom info based on the feed id
final widgetName = globalMap[feedId];
// Get video id
final videoId = event.liveStream.id ?? "";
// Get video type, the possible values for videoType
// are: VideoType.ad, VideoType.video, and VideoType.livestream.
final videoType = event.liveStream.videoType;
// Get live stream status, the possible values for livestreamStatus
// are: LiveStreamStatus.idle, LiveStreamStatus.live, LiveStreamStatus.completed,
// and LiveStreamStatus.replay
final livestreamStatus = event.liveStream.liveStreamStatus;
}
};
FireworkSDK.getInstance().shopping.onCustomTapProductCard =
(CustomTapProductCardEvent? event) async {
// Get feed id
final feedId = event?.video.feedId ?? "";
// Get widget type based on feed id
// The possible values for widgetType
// are: FWWidgetType.videoFeed and FWWidgetType.storyBlock
final widgetType = FireworkSDK.getInstance().getWidgetType(feedId);
// Get custom info based on the feed id
final widgetName = globalMap[feedId];
// Get video id
final videoId = event?.video.videoId ?? "";
// Get video type, the possible values for videoType
// are: VideoType.ad, VideoType.video, and VideoType.livestream.
final videoType = event?.video.videoType;
// Get live stream status, the possible values for livestreamStatus
// are: LiveStreamStatus.idle, LiveStreamStatus.live, LiveStreamStatus.completed,
// and LiveStreamStatus.replay
final livestreamStatus = event?.video.liveStreamStatus;
};
FireworkSDK.getInstance().shopping.onClickProduct =
(ClickProductEvent? event) async {
// Get feed id
final feedId = event?.video.feedId ?? "";
// Get widget type based on feed id
// The possible values for widgetType
// are: FWWidgetType.videoFeed and FWWidgetType.storyBlock
final widgetType = FireworkSDK.getInstance().getWidgetType(feedId);
// Get custom info based on the feed id
final widgetName = globalMap[feedId];
// Get video id
final videoId = event?.video.videoId ?? "";
// Get video type, the possible values for videoType
// are: VideoType.ad, VideoType.video, and VideoType.livestream.
final videoType = event?.video.videoType;
// Get live stream status, the possible values for livestreamStatus
// are: LiveStreamStatus.idle, LiveStreamStatus.live, LiveStreamStatus.completed,
// and LiveStreamStatus.replay
final livestreamStatus = event?.video.liveStreamStatus;
};
FireworkSDK.getInstance().onCustomCTAClick =
(CustomCTAClickEvent? event) async {
// Get feed id
final feedId = event?.video.feedId ?? "";
// Get widget type based on feed id
// The possible values for widgetType
// are: FWWidgetType.videoFeed and FWWidgetType.storyBlock
final widgetType = FireworkSDK.getInstance().getWidgetType(feedId);
// Get custom info based on the feed id
final widgetName = globalMap[feedId];
// Get video id
final videoId = event?.video.videoId ?? "";
// Get video type, the possible values for videoType
// are: VideoType.ad, VideoType.video, and VideoType.livestream.
final videoType = event?.video.videoType;
// Get live stream status, the possible values for livestreamStatus
// are: LiveStreamStatus.idle, LiveStreamStatus.live, LiveStreamStatus.completed,
// and LiveStreamStatus.replay
final livestreamStatus = event?.video.liveStreamStatus;
};
Opt out of Firework data tracking while still accessing Firework videos
We add a feature that allows users to opt out of Firework data tracking. Firework data tracking is enabled by default. You could use the following codes to disable Firework data tracking.
// As this API call is only effective for this app launch,
// you need to call this API every app launch.
FireworkSDK.getInstance().dataTrackingLevel = DataTrackingLevel.none;
After you disable Firework data tracking, you can also enable Firework tracking by using the following codes.
As follows, you could set FireworkSDK.getInstance().onVideoPlayback to receive video playback events. The event type is .
As follows, you could set FireworkSDK.getInstance().onVideoFeedClick to receive video feed click events. The event type is .
As follows, you could set FireworkSDK.getInstance().liveStream.onLiveStreamEvent to receive live stream events. The event type is .
As follows, you could set FireworkSDK.getInstance().liveStream.onLiveStreamChatEvent to receive live stream chat events. The event type is .
If you would like to customize the product click event handling, you could use to support this use case. For example, you could open your product detail page when the user clicks on the product. We call this outstream PDP.
If you would like to use the SDK default behavior to handle the product click event, you could use to support this use case. The SDK default behavior is opening Firework product detail page when the user clicks on the product. We call this instream PDP.
You could use callback to receive shopping CTA click events.
If you would like to customize the overlay CTA click event handling, you could use to receive video overlay CTA click events. For example, you could open your product detail page when the user clicks on the overlay CTA.
If you would like to use the SDK default behavior to handle the overlay CTA click event, you could use (eventName is VideoPlaybackEventName.clickCTA) to receive video overlay CTA click events. The SDK default behavior is opening the CTA link using the SDK webview or system browser when the user clicks the overlay CTA.
The host app can record a purchase which will help get a full picture of the user journey flow. To do this, call whenever the purchase happens. The following are the sample codes: