Getting Started

The BB Channel SDK (@bluebillywig/react-native-channel) embeds Blue Billywig video channels in React Native apps. Channels include swim lanes, grids, carousels, search, and detail pages — all rendered in a WebView with a native bridge for seamless integration.

Compatibility

Requirement	Minimum Version
SDK version	1.1.0
React Native	0.70+
iOS	13+
Android	API 23+
Expo SDK	50+
Node.js	18+

Package Access

Private GitHub Package

@bluebillywig/react-native-channel is a private package hosted on GitHub Packages (not the public npm registry). You must configure a .npmrc with an access token before you can install it.

Contact Blue Billywig to receive your access token.

Once you have a token, create a .npmrc file in your project root:

@bluebillywig:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${BB_SDK_TOKEN}

Then set the BB_SDK_TOKEN environment variable:

export BB_SDK_TOKEN=your_token_here

tip

Add .npmrc to version control so all team members use the same registry config. The token itself should not be committed — use an environment variable or a project-level .npmrc in each developer's home directory (~/.npmrc).

For CI/CD, add BB_SDK_TOKEN as a secret in your pipeline environment (e.g. GitHub Actions secret, Expo secret, Bitrise secret).

Installation

npm install @bluebillywig/react-native-channel react-native-webview

react-native-webview is a required peer dependency.

Optional peer dependencies:

• react-native-safe-area-context — safe area insets for full-screen channels
• @bluebillywig/react-native-bb-player — native video playback (AVPlayer/ExoPlayer) instead of WebView player

iOS

cd ios && pod install

Android

Auto-links via React Native's autolinking. No extra steps needed.

Expo

npx expo install @bluebillywig/react-native-channel react-native-webview

If using @bluebillywig/react-native-bb-player, add the config plugin to app.json:

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

Then rebuild with npx expo prebuild.

Quick Start

import React, { useRef } from 'react';
import { View } from 'react-native';
import { BBChannel, BBFullscreenPlayer } from '@bluebillywig/react-native-channel';
import type { BBChannelRef, MediaPlayEvent } from '@bluebillywig/react-native-channel';

export default function App() {
  const channelRef = useRef<BBChannelRef>(null);

  const handleMediaPlay = (event: MediaPlayEvent) => {
    console.log('Playing clip:', event.clipId, event.title);
  };

  return (
    <View style={{ flex: 1 }}>
      <BBChannel
        ref={channelRef}
        channelUrl="https://demo.bbvms.com/ch/1152.json"
        onMediaPlay={handleMediaPlay}
        onReady={() => console.log('Channel loaded')}
      />
      <BBFullscreenPlayer />
    </View>
  );
}

BBFullscreenPlayer renders the fullscreen/modal player. Place it once at the root of your app alongside BBChannel.

Channel URL

Channel URLs follow this format:

https://{publication}.bbvms.com/ch/{channelId}.json

Where {publication} is your Blue Billywig publication name and {channelId} is the numeric channel ID.

Configuration Options

Pass configuration options as props to BBChannel:

<BBChannel
  channelUrl="https://demo.bbvms.com/ch/1152.json"
  autoPlay={false}
  searchBar={true}
  noStats={false}
  playout="default"
  jwt="eyJ..."
/>

Prop	Type	Description
channelUrl	string	Required. URL to the channel JSON configuration.
autoPlay	boolean	Auto-play the first video. Default: true.
searchBar	boolean	Show the search bar. Default: from channel config.
noStats	boolean	Disable analytics/statistics. Default: false.
playout	string	Override the playout used for players.
jwt	string	JWT for authenticated/restricted content.

Events

<BBChannel
  onMediaPlay={(event) => {
    // Fired when a video starts playing
    console.log(event.clipId, event.title);
  }}
  onNavigate={(event) => {
    // Fired on page navigation (main, detail, overview, search)
    console.log(event.page, event.clipId);
  }}
  onReady={() => {
    // Channel finished loading
  }}
  onError={(error) => {
    // Something went wrong
    console.error(error.message);
  }}
  onCanGoBackChange={(canGoBack) => {
    // Navigation stack changed — useful for Android back button
    console.log('Can go back:', canGoBack);
  }}
/>

Ref Methods

Use a ref to call methods on the channel:

const channelRef = useRef<BBChannelRef>(null);

// Navigate to a specific clip's detail page
channelRef.current?.navigateTo({ page: 'detail', clipId: '4701337' });

// Go back in the navigation stack
channelRef.current?.goBack();

// Trigger a search
channelRef.current?.search('keyword');

Authentication

For restricted content, pass a jwt or rpcToken:

<BBChannel
  channelUrl="https://demo.bbvms.com/ch/1152.json"
  jwt="eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9..."
/>

<BBChannel
  channelUrl="https://demo.bbvms.com/ch/1152.json"
  rpcToken="your-rpc-token"
/>

jwt is preferred for new integrations. rpcToken is supported for backward compatibility.

Deep Linking

Open the channel at a specific page by passing initialNavigationState:

<BBChannel
  channelUrl="https://demo.bbvms.com/ch/1152.json"
  initialNavigationState={{
    page: 'detail',
    clipId: '4701337',
  }}
/>

Supported pages: main, detail (requires clipId), overview (requires clipListId), search (requires query).

What's Next

• Full Screen Guide — full-screen channel with safe area handling
• Embedded Guide — channel inside a scrollable layout
• Deep Linking Guide — state persistence and URL handling
• Player Control Guide — discover and control individual players
• API Reference — complete component and type reference