Skip to main content

Cart Integration

Cart integration lets the Bambuser Shoppable Video player communicate with your native cart. When a viewer taps Add to Cart or changes a quantity inside the player, the SDK emits an event through the onEvent callback. Your app handles the cart operation and 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 Player API › Platform differences.

Event Flow​

Player → should-add-item-to-cart  →  Your app adds item to cart
Your app → notify(callbackKey, true)  →  Player confirms success

If your cart operation fails (e.g. the item is out of stock), respond with a failure payload instead of true; the player will display an appropriate message to the viewer.

Handle Add to Cart​

When a viewer 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.

ShoppableFeedScreen.tsx
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' }",
        );
      }
    });
  }
}
note

Always read the callbackKey from the event and pass it back verbatim; the player uses this token to match your response to the pending interaction.

Handle Update Cart​

When a viewer changes the quantity of an item already in the player's cart, a should-update-item-in-cart event is emitted. Respond the same way:

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

Notify Response Reference​

Scenarioinfo valueNotes
SuccesstrueTells the player the cart action completed
Out of stock"{ success: false, reason: 'out-of-stock' }"Player shows an out-of-stock message
Custom failure"{ success: false, reason: 'your-reason' }"Replace your-reason with a meaningful string

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.

Handling Events in a Feed​

In a feed with multiple mounted players, the event's e.nativeEvent.id tells you which video emitted it. Keep a ref registry keyed by video ID so you can reply to the right player:

ShoppableFeedScreen.tsx
const playerRefs = useRef<Record<string, BambuserVideoViewRef | null>>({});

<BambuserVideoView
  ref={(r) => {
    playerRefs.current[videoId] = r;
  }}
  mode="shoppable"
  id={videoId}
  onEvent={(e) => {
    const { type, data } = e.nativeEvent;
    const callbackKey = e.nativeEvent.callbackKey ?? data?.callbackKey;

    if (
      (type === 'should-add-item-to-cart' ||
        type === 'should-update-item-in-cart') &&
      callbackKey
    ) {
      playerRefs.current[videoId]?.notify(callbackKey, true);
    }
  }}
  ...
/>

Conversion Tracking​

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

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

Next Steps​