Configuration and Functions

To find the detailed configuration and functions please refer to Bambuser Player API Reference.

The configuration prop on <BambuserVideoView /> is a plain object that is forwarded to the underlying native SDK. Memoize this object (with useMemo or by hoisting it to module scope), since changing its reference rebuilds the player.

<BambuserVideoView
  id="your-show-id"
  configuration={{
    buttons: { /* ... */ },
    ui: { /* ... */ },
    autoplay: true,
    currency: 'USD',
    locale: 'en-US',
  }}
/>

Button Configurations

Each button type has different modes of operation:

• none: hides the button, no events emitted.
• event: emits an event to be captured by your onEvent handler.
• auto: uses the SDK's default behavior.

Dismiss Button

Property Name	Value	Description
dismiss	none	Hides the button, no events emitted.
dismiss	event	Emits an event that can be handled by your onEvent handler.
dismiss	minimize	Not applicable in the Mobile SDK.

Product Button

Property Name	Value	Description
product	none	Emits an event, implement your own product view logic.
product	event	Emits an event that can be handled by your custom handler.
product	auto	Default behavior, opens the product detail modal.

Checkout Button

Property Name	Value	Description
checkout	none	Emits an event, implement your own checkout flow.
checkout	auto	Default behavior, opens the product detail modal.

Action Card Button

Property Name	Value	Description
actionCard	none	Emits an event, handle navigation in your app.
actionCard	auto	Default behavior, opens the configured link in a webview. ⚠️ Recommended: use none and handle redirection from your app.

configuration={{
  buttons: {
    dismiss: 'none',     // 'none' | 'event' | 'auto'
    product: 'none',     // 'none' | 'event' | 'auto'
    checkout: 'none',    // 'none' | 'auto'
    actionCard: 'none',  // 'none' | 'auto'
  },
}}

---

UI Configurations

⚠️ All UI flags must be nested under a ui object, not at the top level of configuration.

configuration={{
  ui: {
    hideEmojiOverlay: true,
    hideActionBar: false,
    hideShareButton: false,
    hideShareFromTimestampButton: false,
    hideVolumeButton: false,
    hideClosedCaptionsButton: false,
    hidePlaybackRateButton: false,
    hidePromotedShows: false,
  },
}}

Property Name	Type	Description
hideActionBar	boolean	Hides the full action bar. No button will be displayed.
hideCartView	boolean	Hides the cart view in the modal, showing only product listing.
hideChatOverlay	boolean	Hides the chat overlay.
hideEmojiOverlay	boolean	Hides the emoji overlay on the player.
hideProductList	boolean	Hides the product list.
hideShareButton	boolean	Hides the share button.
hideShareFromTimestampButton	boolean	Hides the share button with timestamp.
hideShareView	boolean	Hides the share view.
hideVolumeButton	boolean	Hides the volume control button.
hideClosedCaptionsButton	boolean	Hides the closed captions / subtitles button.
hidePlaybackRateButton	boolean	Hides the playback speed button.
hidePromotedShows	boolean	Hides the promoted shows carousel inside the player.

---

Tracking Configurations

Property Name	Type	Description
enableTrackingPoint	boolean	Sends all tracking information. You will receive notifications through your onEvent callback.

---

Player Behavior

Property Name	Type	Default	Description
autoplay	boolean	true	Automatically starts playback when the player is presented. When false, call playerRef.current?.play() manually.
currency	string	none	Three-letter currency code (e.g. 'USD'). Required for product hydration.
locale	string	none	Locale tag (e.g. 'en-US'). Required for product hydration.

configuration={{
  autoplay: false, // Player will not start automatically; call playerRef.current?.play() when ready.
}}

Video Scale Mode

Requires package version 2.1.0 or later.

videoScaleMode controls how the video is scaled inside the player view. It is a prop on <BambuserVideoView />, not a key inside the configuration object.

The video's aspect ratio is always preserved. The mode only decides what happens when the player view and the video have different aspect ratios.

The prop is optional. Leave it out and the player uses 'fit', so existing integrations keep their current behavior. The mode is baked in when the player is created, so changing the prop rebuilds the player.

Value	Default	Description
'fit'	✅	The whole video fits inside the player view, leaving empty space on the axis where the ratios differ.
'fill'		The video covers the player view and the overflowing axis is cropped.

<BambuserVideoView
  id="your-show-id"
  configuration={{ autoplay: true }}
  videoScaleMode="fill"
/>

No phone screen matches the 9:16 aspect ratio most live shows are recorded in, so a full-screen player using 'fit' always leaves empty space above and below the video. Use 'fill' when the video should cover the player view instead.

Full Screen

'fill' covers the player view minus any safe-area edge the player still respects. To let the video run under the status bar and home indicator, ignore those edges with ignoredSafeAreaEdges, and make sure your layout gives the player view the full screen:

<BambuserVideoView
  style={StyleSheet.absoluteFill}
  videoScaleMode="fill"
  ignoredSafeAreaEdges={['all']} // or ['top'], ['top', 'bottom']
  ...
/>

On Android, also hide the status bar and the navigation bar for the best full-screen experience. The player lays its own controls out edge to edge, so with the bars visible the show title renders behind the clock and the seek bar sits under the navigation bar.

---

Imperative Functions

Beyond configuration, the player exposes imperative methods through the component ref. The full reference lives on the Player API page; the most commonly used are:

Method	Purpose
play() / pause()	Start or pause playback.
mute() / unMute()	Mute or unmute audio.
startPiP() / stopPiP() / setPiPEnabled(boolean)	Control Picture-in-Picture.
invoke(fn, args)	Call a function on the player (e.g. updateProductWithData).
notify(callbackKey, info)	Respond to a callback event surfaced through onEvent.
cleanup()	Tear down the player and release native resources.

---

Full Configuration Example

import { useMemo, useRef } from 'react';
import {
  BambuserVideoView,
  type BambuserVideoViewRef,
} from '@bambuser/react-native-commerce-sdk';

export function LiveShowScreen() {
  const playerRef = useRef<BambuserVideoViewRef>(null);

  const configuration = useMemo(
    () => ({
      buttons: {
        dismiss: 'none',
        product: 'none',
      },
      ui: {
        hideEmojiOverlay: true,
        hidePlaybackRateButton: false,
        hidePromotedShows: false,
      },
      autoplay: true,
      currency: 'USD', // Required for product hydration
      locale: 'en-US', // Required for product hydration
    }),
    [],
  );

  return (
    <BambuserVideoView
      ref={playerRef}
      style={{ flex: 1 }}
      id="your-show-id"
      configuration={configuration}
    />
  );
}