Cart integration

Cart integration synchronizes the Bambuser player's in-player cart with your native app cart. The player emits events through the onEvent callback when users interact with products, and your app responds using the notify method on the BambuserVideoView ref.

Event payloads differ slightly between iOS and Android. On iOS the event-specific fields live under data.event.* and the callback key under data.callbackKey; on Android they are at the top level (data.* and e.nativeEvent.callbackKey). The examples below normalize both shapes. See Events › Platform differences.

Handle Add to Cart

When a user taps Add to Cart in the player, a should-add-item-to-cart event is emitted. Extract the SKU and quantity, update your cart, then call notify with the result.

import { Platform } from 'react-native';

function onEvent(e) {
  const { type, data } = e.nativeEvent;
  const callbackKey = e.nativeEvent.callbackKey ?? data?.callbackKey;

  if (type === 'should-add-item-to-cart' && callbackKey) {
    const eventData = Platform.OS === 'ios' ? data?.event : data;
    const sku = eventData?.sku;
    const quantity = eventData?.quantity ?? 1;

    YourCartService.addItem(sku, quantity).then((success) => {
      if (success) {
        playerRef.current?.notify(callbackKey, true);
      } else {
        playerRef.current?.notify(
          callbackKey,
          "{ success: false, reason: 'out-of-stock' }",
        );
      }
    });
  }
}

Handle Update Cart

When a user changes the quantity of an item already in the player's cart, a should-update-item-in-cart event is emitted.

if (type === 'should-update-item-in-cart' && callbackKey) {
  const eventData = Platform.OS === 'ios' ? data?.event : data;
  const sku = eventData?.sku;
  const quantity = eventData?.quantity;

  YourCartService.updateItem(sku, quantity).then(() => {
    playerRef.current?.notify(callbackKey, true);
  });
}

Sync Cart State

When the viewer navigates back to the player, it requests the current cart state through should-sync-cart-state. Respond with the current list of cart items so the player can reflect the correct quantities.

if (type === 'should-sync-cart-state' && callbackKey) {
  const cartItems = YourCartService.currentItems().map((item) => ({
    sku: item.sku,
    quantity: item.quantity,
  }));

  playerRef.current?.notify(callbackKey, cartItems);
}

Notify Response Reference

Example responses when calling notify:

Scenario	info value	Example
Success	true	playerRef.current?.notify(callbackKey, true)
Out of stock	"{ success: false, reason: 'out-of-stock' }"	playerRef.current?.notify(callbackKey, "{ success: false, reason: 'out-of-stock' }")
Custom failure	"{ success: false, reason: 'your-reason' }"	playerRef.current?.notify(callbackKey, "{ success: false, reason: 'your-reason' }")
List payload	Plain array or object	playerRef.current?.notify(callbackKey, [{ sku, quantity }])

notify accepts booleans, numbers, strings, plain objects/arrays, or null. Strings that already look like JS literals ({...}, [...], numbers, true/false/null) are passed through; anything else is JSON-encoded. See Player API › notify.

Conversion Tracking

After a purchase completes in your app, report it to Bambuser Analytics using BambuserSDK.track. This attributes the conversion to the live show.

import { BambuserSDK } from '@bambuser/react-native-commerce-sdk';

const sdk = new BambuserSDK({ server: 'US' });

await sdk.track('purchase', {
  transaction: {
    id: 'ORDER-12345',
    subtotal: 70.99,
    currency: 'USD',
    total: 74.98,
    tax: 4.0,
    shippingCost: 3.99,
    shippingMethod: 'Standard',
    coupon: 'SUMMER_SALE',
  },
  products: [
    {
      id: '314-7216-102',
      name: 'Tennis Shoe Classic, Size 10',
      image: 'https://example.com/images/314-7216-102.jpg',
      price: 70.99,
      currency: 'USD',
      quantity: 1,
      brand: 'Example Brand',
      category: 'Footwear > Sports > Tennis',
      location: 'https://example.com/products/314-7216',
    },
  ],
});

See Tracking for the full event data schema and supported event names.