Product hydration

Product hydration allows your app to supply enriched product data (pricing, images, variants, stock) to the Bambuser live player at runtime. When a live show starts, the player fires a provide-product-data event listing all products it needs data for. Your app looks up each product by SKU and pushes the data back into the player using invoke('updateProductWithData', ...).

Prerequisites

currency and locale must be set in your player configuration. Product hydration will not work without them.

<BambuserVideoView
  ref={playerRef}
  id="your-show-id"
  configuration={{
    currency: 'USD',  // Required for product hydration
    locale: 'en-US',  // Required for product hydration
  }}
  onEvent={handleEvent}
/>

Handle the provide-product-data Event

The player fires provide-product-data at show start, and again whenever a new product needs to be displayed. Handle it in your onEvent callback.

import { Platform } from 'react-native';

function handleEvent(e) {
  const { type, data } = e.nativeEvent;

  if (type === 'provide-product-data') {
    const products = Platform.OS === 'ios'
      ? data?.event?.products
      : data?.products;

    hydrate(products ?? []);
  }
}

Each entry in the products array has:

Field	Type	Description
id	string	Bambuser-generated product ID. Pass this back to the player.
ref	string	Your product SKU. Use this to look up your own data.
url	string	Product URL as set in the Bambuser dashboard.

Send Product Data Back to the Player

Call invoke('updateProductWithData', ...) for each product. The arguments string must start with the Bambuser product id in single quotes, followed by a comma and the product object:

async function hydrate(products) {
  for (const product of products) {
    const id = product.id;
    const sku = product.ref;
    if (!id || !sku) continue;

    const source = await YourProductService.product(sku);
    if (!source) continue;

    const hydrationJson = `{
      sku: '${source.sku}',
      name: '${source.name}',
      brandName: '${source.brand}',
      introduction: '${source.shortDescription}',
      description: '${source.description}',
      variations: [
        {
          sku: '${source.variationSku}',
          name: '${source.variationName}',
          colorName: '${source.colorName}',
          imageUrls: ['${source.imageUrl}'],
          sizes: [
            {
              sku: '${source.sizeSku}',
              currency: 'USD',
              current: ${source.price},
              original: ${source.originalPrice},
              name: '${source.sizeName}',
              inStock: ${source.stock},
            }
          ]
        }
      ]
    }`;

    await playerRef.current?.invoke(
      'updateProductWithData',
      `'${id}', ${hydrationJson}`,
    );
  }
}

Full Product Data Structure

The product object passed to updateProductWithData supports the following fields:

Product

Field	Type	Required	Description
sku	string	Yes	Your product SKU / identifier.
name	string	Yes	Product display name.
brandName	string	Yes	Brand name.
introduction	string	No	Short introductory text.
description	string	No	Full description, supports HTML.
variations	array	Yes	List of product variations (colors/styles).

Variation

Field	Type	Required	Description
sku	string	Yes	Variation SKU.
name	string	Yes	Variation display name.
colorName	string	Yes	Color name shown in the variation selector.
colorHexCode	string	No	Hex color code, e.g. "#000000".
imageUrls	string[]	Yes	Ordered list of image URLs for this variation.
sizes	array	Yes	List of sizes/SKUs for this variation.

Size

Field	Type	Required	Description
sku	string	Yes	Size-level SKU.
name	string	Yes	Size name, e.g. "Small", "XL".
current	number	Yes	Current (sale) price.
original	number	No	Original price, shown as strike-through.
currency	string	Yes	Three-letter currency code, e.g. "USD".
inStock	number	Yes	Available stock quantity (0 = out of stock).
perUnit	number	No	Price per unit (for bundle/multi-pack pricing).
unitAmount	number	No	Quantity per unit.
unitDisplayName	string	No	Unit label, e.g. "kg", "L", "st".

Notes

• The player may fire provide-product-data multiple times during a show as new products are highlighted. Your hydration handler must be idempotent.
• Fields not provided in your hydration response fall back to data previously scraped or manually set in the Bambuser dashboard.
• invoke is asynchronous and returns a Promise; await it when you need to chain further work or surface errors.
• If you prefer a typed builder over raw string interpolation, you can construct the hydration object in JS and JSON.stringify it, then pass `'${id}', ${json}` as the arguments string.