Analytics (Flutter)

Video playback events

As follows, you could set FireworkSDK.getInstance().onVideoPlayback to receive video playback events. The event type is VideoPlaybackEvent.

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

As follows, you could set FireworkSDK.getInstance().onVideoFeedClick to receive video feed click events. The event type is VideoFeedClickEvent.

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

Live stream events

As follows, you could set FireworkSDK.getInstance().liveStream.onLiveStreamEvent to receive live stream events. The event type is LiveStreamEvent.

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;
    }
  }
};

Live stream chat events

As follows, you could set FireworkSDK.getInstance().liveStream.onLiveStreamChatEvent to receive live stream chat events. The event type is LiveStreamChatEvent.

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 PDP

If you would like to customize the product click event handling, you could use onCustomTapProductCard 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.

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 PDP

If you would like to use the SDK default behavior to handle the product click event, you could use onClickProduct 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.

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 CTA click events

You could use onShoppingCTA callback to receive shopping CTA click events.

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 CTA click events

1. If you would like to customize the overlay CTA click event handling, you could use onCustomCTAClick to receive video overlay CTA click events. For example, you could open your product detail page when the user clicks on the overlay CTA.

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 ?? '',
  });
};

1. If you would like to use the SDK default behavior to handle the overlay CTA click event, you could use onVideoPlayback(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.

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

The host app can record a purchase which will help get a full picture of the user journey flow. To do this, call FireworkSDK.getInstance().trackPurchase whenever the purchase happens. The following are the sample codes:

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:

1. onVideoFeedGetFeedId callback for VideoFeed
2. onVideoFeedGetFeedId callback for StoryBlock

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.

FireworkSDK.getInstance().dataTrackingLevel = DataTrackingLevel.all;

The API reference is dataTrackingLevel.

FireworkSDK.getInstance().dataTrackingLevel is only effective for this app launch, you need to call this API every app launch.