React Native Player SDK: Get Started

The React Native Player SDK lets you embed native Blue Billywig video playback inside a React Native app — on both iOS and Android — without a WebView.

1.0 | What is it?

The React Native Player SDK (@bluebillywig/react-native-bb-player) provides a BBPlayerView component that delivers true native playback: AVPlayer on iOS and ExoPlayer on Android. It connects directly to your Blue Billywig publication and supports clips, outstream ads, and Shorts.

The SDK is TypeScript-first and supports both bare React Native projects and Expo (with a config plugin). It also supports both the Old and New React Native Architecture.

If you are building a native iOS or Android app (not React Native), see the iOS and Android Native Player SDK instead.

If you want to embed a full branded video portal with swim lanes, carousels, search, and detail pages, see the React Native Channels SDK instead: it builds on top of this player SDK.

2.0 | Features

• True native playback: no WebView
• AVPlayer engine on iOS, ExoPlayer on Android
• Full ad support (VAST, VPAID, Google IMA)
• Built-in analytics
• Content protection support
• Playback event callbacks
• Programmatic playback controls (play, pause, seek, load)
• Expo config plugin support
• TypeScript-first API

3.0 | Getting started

The SDK is available as a public npm package: no access token required.

3.1 | Bare React Native

Install the package:

npm install @bluebillywig/react-native-bb-player

On iOS, also run:

cd ios && pod install && cd ..

Then rebuild your app:

npx react-native run-ios
# or
npx react-native run-android

3.2 | Expo

The SDK cannot run in Expo Go: a development build is required.

Install the package:

npx expo install @bluebillywig/react-native-bb-player

Add the plugin to app.json:

{
  "expo": {
    "plugins": [
      "@bluebillywig/react-native-bb-player"
    ]
  }
}

Then prebuild and run:

npx expo prebuild
npx expo run:ios
# or
npx expo run:android

3.3 | Minimal example

Here is the simplest way to embed a player:

import { BBPlayerView } from '@bluebillywig/react-native-bb-player';

export function MyPlayer() {
  return (
    <BBPlayerView
      jsonUrl="https://yourpublication.bbvms.com/p/default/c/1234567.json"
      options={{ autoPlay: true }}
      style={{ flex: 1 }}
    />
  );
}

The jsonUrl is the standard Blue Billywig embed URL with a .json extension:

https://{publication}.bbvms.com/p/{playout}/c/{clipId}.json

For full setup instructions and configuration options, visit the React Native Player SDK Getting Started guide.

4.0 | Playback controls and events

Use a ref to control playback programmatically:

import React, { useRef } from 'react';
import { View, Button } from 'react-native';
import { BBPlayerView, type BBPlayerViewMethods } from '@bluebillywig/react-native-bb-player';

export function ControlledPlayer() {
  const playerRef = useRef<BBPlayerViewMethods>(null);
  return (
    <View style={{ flex: 1 }}>
      <BBPlayerView
        ref={playerRef}
        jsonUrl="https://yourpublication.bbvms.com/p/default/c/1234567.json"
        style={{ flex: 1 }}
      />
      <View style={{ flexDirection: 'row', padding: 10, gap: 8 }}>
        <Button title="Play" onPress={() => playerRef.current?.play()} />
        <Button title="Pause" onPress={() => playerRef.current?.pause()} />
        <Button title="Seek 30s" onPress={() => playerRef.current?.seek(30)} />
      </View>
    </View>
  );
}

Listen to player events using callback props:

import { BBPlayerView, type State } from '@bluebillywig/react-native-bb-player';

export function EventPlayer() {
  const [state, setState] = useState<State>('IDLE');
  return (
    <BBPlayerView
      jsonUrl="https://yourpublication.bbvms.com/p/default/c/1234567.json"
      style={{ flex: 1 }}
      onDidTriggerStateChange={setState}
      onDidTriggerPlay={() => console.log('Playing')}
      onDidTriggerEnded={() => console.log('Ended')}
    />
  );
}

5.0 | System requirements

• React Native 0.73+ (Old and New Architecture supported)
• iOS 13.4+
• Android API 24+
• Expo SDK 51+ (if using Expo)
• Node.js 18+