> For the complete documentation index, see [llms.txt](https://docs.firework.com/firework-for-developers/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.firework.com/firework-for-developers/flutter-sdk/integration-guide-v2/shopping.md).

# Shopping (Flutter)

### Shopping configurations

Please refer to [Shopping configurations (Flutter)](/firework-for-developers/flutter-sdk/integration-guide-v2/customization/shopping-configurations-flutter.md).

### Customize shopping click behaviors

Please refer to [Customize shopping click behaviors](/firework-for-developers/flutter-sdk/integration-guide-v2/customization/customize-click-behaviors-flutter.md).

### **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:

```dart
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`.

```dart
// 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.     |

{% hint style="warning" %}
Return a result within **10 seconds**. Otherwise the native SDK restores the button without presenting a result.
{% endhint %}

{% hint style="info" %}
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](#shopping-error-reporting) instead.
{% endhint %}

{% hint style="info" %}
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.
{% endhint %}

### 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.

```dart
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.                         |

{% hint style="info" %}
These errors usually mean the product data is incomplete. Use [Product Hydration](#product-hydration) to supply the missing external identifiers.
{% endhint %}

### Reference

[VideoShopping](https://eng.firework.com/fw_flutter_sdk/v2/fw_flutter_sdk/VideoShopping-class.html)