Shopping (Flutter)

Shopping configurations

Please refer to Shopping configurations (Flutter).

Customize shopping click behaviors

Please refer to Customize shopping click behaviors.

Product Hydration

Host app can implement onUpdateProductDetails callback to update product info in the client side, such as product name. We call this product hydration. For example, the host apps could fetch the latest product information from their own servers on the callback and return the lastest product info in the callback. The code snippets are:

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

Player Deck one-tap Add to Cart

Player Deck product cards can show a one-tap Add to Cart button that adds the exact product unit shown on the card to your cart, without opening the product detail page. The SDK does not own a cart — you perform the add and return the outcome, and the native SDK animates the button accordingly.

The button is hidden by default. To enable it you must do both of the following, before the PlayerDeck widget is created:

1. Set FireworkSDK.getInstance().shopping.onPlayerDeckAddToCart.

2. Set PlayerDeckConfiguration.showAddToCartButton to true.

// 1. Set the callback
FireworkSDK.getInstance().shopping.onPlayerDeckAddToCart =
    (PlayerDeckAddToCartEvent event) async {
  // Add exactly the unit the card represents — do not substitute another unit.
  final succeeded = await yourCart.add(
    productId: event.productId,
    unitId: event.unitId,
  );

  return succeeded
      ? PlayerDeckAddToCartResult.success
      : PlayerDeckAddToCartResult.failure;
};

// 2. Unhide the button in the player deck configuration
PlayerDeck(
  height: 481,
  source: VideoFeedSource.discover,
  playerDeckConfiguration: PlayerDeckConfiguration(
    showAddToCartButton: true,
  ),
);

PlayerDeckAddToCartEvent has the following fields:

Field	Type	Description
productId	String	The external identifier of the product.
unitId	String	The external identifier of the exact unit to add to the cart.
url	String	The URL associated with the selected product unit.
video	VideoPlaybackDetails	The video playback details for the request.

The callback must return a PlayerDeckAddToCartResult:

Value	Description
success	The selected product unit was added successfully.
failure	The selected product unit could not be added.

Return a result within 10 seconds. Otherwise the native SDK restores the button without presenting a result.

If the tapped card has no external product identifier or no external product unit identifier, the callback is not invoked; the failure is reported through Shopping error reporting instead.

The callback is read when a product card is configured, so set it during SDK setup, before the PlayerDeck widget is created. If either the callback is not set or showAddToCartButton is not true, the button is not shown.

Shopping error reporting

Set FireworkSDK.getInstance().shopping.onShoppingError to be notified when a shopping action cannot be completed. Both iOS and Android report the same errors under the same names, so you can switch on FWError.name without a platform check.

FireworkSDK.getInstance().shopping.onShoppingError = (FWError error) {
  switch (error.name) {
    case "missingProductId":
      // The product has no non-empty external identifier.
      break;
    case "missingProductUnitId":
      // The selected product unit has no non-empty external identifier.
      break;
  }
  debugPrint("Shopping error: ${error.name} - ${error.reason}");
};

FWError has the following fields:

Field	Type	Description
name	String	The error name. One of missingProductId or missingProductUnitId.
reason	String?	A human-readable description of the failure.

These errors usually mean the product data is incomplete. Use Product Hydration to supply the missing external identifiers.

Reference

VideoShopping