Skip to main content

Getting Started

The BB Channel SDK (@bluebillywig/react-native-channel) embeds Blue Billywig video channels in React Native apps with native video playback, Chromecast support, and full navigation (swim lanes, grids, carousels, search, detail pages).

Compatibility​

RequirementMinimum Version
SDK version8.49.0+
React Native0.70+
iOS13+
AndroidAPI 23+
Expo SDK50+
Node.js18+

Package Access​

@bluebillywig/react-native-channel is a public package hosted on GitHub Packages. The peer dependency @bluebillywig/react-native-bb-player is published publicly on npmjs.com.

GitHub Packages requires authentication even for public packages, so you'll need a GitHub Personal Access Token with the read:packages scope. Any GitHub account works — there's no special token to request from Blue Billywig.

Create a .npmrc in your project root:

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

Then export the token in your environment:

export GITHUB_TOKEN=ghp_yourtokenhere
tip

Commit the .npmrc registry line so all team members and CI use the same config, but read the token from an environment variable — never commit a token. For CI/CD, add GITHUB_TOKEN as a secret (GitHub Actions, Expo, Bitrise, etc.).

License​

The SDK is proprietary software. Installation and use are permitted only under a current written agreement with Blue Billywig covering the use of Blue Billywig channels. See the LICENSE.md bundled with the package (node_modules/@bluebillywig/react-native-channel/LICENSE.md) for full terms. Contact support@bluebillywig.com for licensing inquiries.

Installation​

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

react-native-webview and @bluebillywig/react-native-bb-player are required peer dependencies.

Optional:

  • react-native-safe-area-context — safe area insets for full-screen channels

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 from 'react';
import { SafeAreaView } from 'react-native';
import { BBChannelWithPlayer } from '@bluebillywig/react-native-channel';

export default function App() {
  return (
    <SafeAreaView style={{ flex: 1, backgroundColor: '#000' }}>
      <BBChannelWithPlayer
        channelUrl="https://demo.bbvms.com/ch/1152.json"
        playerAspectRatio={16 / 9}
        onReady={() => console.log('Channel loaded')}
      />
    </SafeAreaView>
  );
}

BBChannelWithPlayer renders the channel with a native video player using the Blue Billywig native player, providing hardware-accelerated playback, Chromecast support, and a modal fullscreen player. See Native Player Integration for Chromecast setup and configuration.

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:

<BBChannelWithPlayer
  channelUrl="https://demo.bbvms.com/ch/1152.json"
  playerMode="inline"
  autoPlay={false}
  searchBar={true}
  noStats={false}
  playout="default"
  jwt="eyJ..."
/>
PropTypeDescription
channelUrlstringRequired. URL to the channel JSON configuration.
autoPlaybooleanAuto-play the first video. Default: true.
searchBarbooleanShow the search bar. Default: from channel config.
noStatsbooleanDisable analytics/statistics. Default: false.
playoutstringOverride the playout used for players.
jwtstringJWT for authenticated/restricted content.

Events​

<BBChannelWithPlayer
  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:

<BBChannelWithPlayer
  channelUrl="https://demo.bbvms.com/ch/1152.json"
  jwt="eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9..."
/>
<BBChannelWithPlayer
  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:

<BBChannelWithPlayer
  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​