Shopping (Flutter)

Callbacks

Firework SDK triggers shopping callbacks when asking for product details updates, users click the cart icon or "Add to cart" button, etc. It's up to the host app developer to inject custom callbacks and return feedback in the callback body. Firework SDK does not keep any state but asks for updates via callbacks.

onUpdateProductDetails

Triggered when the video will be shown. The host app can return a Product list to update the latest product information. For example, the host apps could fetch the latest product information from their own servers.

FireworkSDK.getInstance().shopping.onUpdateProductDetails =
    (UpdateProductDetailsEvent? event) async {
  if (event == null) {
    return null;
  }

  List<Product> products = [];
  for (var productId in event.productIds) {
    // Get the latest product info from the server, such as the host app server.
    final remoteProduct = await fetchProductFromServer(productId)
    final product = Product(
      productId: productId,
      name: remoteProduct.name, // Update the product name
      description: remoteProduct.description, // Update the product description
      units: remoteProduct.variants!.map((remoteProductVariant) {
            return ProductUnit(
              unitId: remoteProductVariant.id,
              name: remoteProductVariant.name, // Update product variant name
              url: remoteProductVariant.url, // Update product variant url
              imageUrl: remoteProductVariant.imageUrl, // Update product variant image url
              isAvailable: remoteProductVariant.isAvailable, // Update product variant availability
              price: ProductPrice(
                amount: remoteProductVariant.amount,
                currencyCode: remoteProductVariant.currencyCode,
              ), // Update product variant price
            );
          }).toList(),
    );

    products.add(product);
  }
  // The above example retrieves products one by one.
  // But if the server API allows bulk retrieval of product information,
  // you can also obtain remote product information in bulk.
  // Such as: final remoteProducts = await fetchProductsFromServer(event.productIds)

  return products;
};

onShoppingCTA

Triggered when the user clicks the shopping CTA button. And we support customizing the shopping CTA button text to "Add to cart" or "Shop now". The usage codes are:

FireworkSDK.getInstance().shopping.productInfoViewConfiguration =
    ProductInfoViewConfiguration(
  ctaButton: ShoppingCTAButtonConfiguration(
    text: ShoppingCTAButtonText.shopNow, // or ShoppingCTAButtonText.addToCart
  ),
);

And host app can return a ShoppingCTAResult object to tell FireworkSDK the result. The event type is ShoppingCTAEvent.

FireworkSDK.getInstance().shopping.onShoppingCTA =
    (ShoppingCTAEvent? event) async {
  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,
  );
};

As the following, we propose wrapping the navigation codes with Future.delayed. The reason for that is ensuring Firework SDK can receive the result, such as ShoppingCTAResult(res: ShoppingCTARes.success,).

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

onCustomClickCartIcon

Triggered when the user clicks the cart icon. The cart icon is hidden by default. You could show the cart icon by the following codes:

FireworkSDK.getInstance().shopping.cartIconVisible = true;

As follows, you could close the player and push the Flutter cart page in the Flutter navigation stack when users click the cart icon.

FireworkSDK.getInstance().shopping.onCustomClickCartIcon =
                    (event) async {
  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 cart page.
  globalNavigatorKey.currentState?.pushNamed('/cart');
};

onCustomClickLinkButton

This callback is triggered when the user clicks the link button next to the shopping CTA button(e.g. "Add to card" button). The host app can customize the tap event processing logic of the link button by setting the callback. The event type is CustomClickLinkButtonEvent.

FireworkSDK.getInstance().shopping.onCustomClickLinkButton = 
    (CustomTapProductCardEvent? event) async {
  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,
  });
}

onCustomTapProductCard

This callback is triggered when the user clicks the product card. The host app can customize the click event processing logic of the product by setting the callback. The event type is CustomTapProductCardEvent.

FireworkSDK.getInstance().shopping.onCustomTapProductCard = 
    (CustomTapProductCardEvent? event) async {
  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,
  });
}

Properties

cartIconVisible

Defaults to false. You can hide the cart icon by setting this property to true.

productInfoViewConfiguration

The configuration of product info view. For example, you could customize the shopping CTA button text to "Add to cart" or "Shop now" by this property.

Customize product card

FireworkSDK.getInstance().shopping.productInfoViewConfiguration =
    ProductInfoViewConfiguration(
  productCard: ProductCardConfiguration(
    ctaButtonText:
        ProductCardCTAButtonText.buyNow, // or ProductCardCTAButtonText.shopNow
    theme: ProductCardTheme.light, // or ProductCardTheme.dark
  ),
);

For more details, please refer to ProductCardConfiguration.

We also provide a restricted API to customize product card using the custom view. Please refer to this link for more details.

Method

setCartItemCount

// The host app call this method to sycn cart item count to Firework SDK.
// The count should be greater than or equal to 0.
// We just use count to show or hide red indicator on the cart icon.
// If cound > 0, we will show the red indicator on the cart icon.
// Otherwise, we will hide the red indicator on the cart icon.
FireworkSDK.getInstance().shopping.setCartItemCount(cartItemCount);

Reference

VideoShopping