Flutter Player SDK: Get Started

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

1.0 | What is it?

The Flutter Player SDK (bb_player) provides a BBPlayerView widget that delivers true native playback: AVPlayer on iOS and ExoPlayer on Android. It connects directly to your Blue Billywig publication and supports clips, playlists, outstream ads, and Shorts.

If you are building a native iOS or Android app (not Flutter), 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 Channels SDKs:

• Flutter, via pub.dev: Flutter Channels SDK
• Jetpack Compose (Android), via Maven: Jetpack Compose Channels SDK
• SwiftUI (iOS), via Swift Package Manager: SwiftUI Channels SDK
• React Native, via npm: React Native Channels SDK

2.0 | Features

• True native playback (no WebView)
• AVPlayer engine on iOS, ExoPlayer on Android
• Full ad support (VAST, VPAID, Google IMA): pre-roll, mid-roll, post-roll
• Outstream ad placements with animated collapse/expand
• Shorts (vertical video) player
• Built-in analytics
• Chromecast support
• Fullscreen and Picture-in-Picture support
• Playback event callbacks (40+ events)
• Programmatic playback controls (play, pause, seek, volume, load)

3.0 | Getting started

The SDK is available as a public Git package hosted on GitHub. No access token is required.

3.1 | Add the dependency

Add bb_player to your pubspec.yaml:

dependencies:
  bb_player:
    git:
      url: https://github.com/bluebillywig/flutter-bb-player.git

Then fetch packages:

flutter pub get

3.2 | iOS setup

Set the minimum deployment target to 14.0 in your ios/Podfile:

platform :ios, '14.0'

Then install CocoaPods dependencies:

cd ios && pod install && cd ..

3.3 | Android setup

Add the Blue Billywig Maven repository to your android/build.gradle:

allprojects {
    repositories {
        google()
        mavenCentral()
        maven { url 'https://maven.bluebillywig.com/releases' }
    }
}

Ensure the minimum SDK version in android/app/build.gradle is at least 21:

android {
    defaultConfig {
        minSdkVersion 21
    }
}

3.4 | Minimal example

Here is the simplest way to embed a player:

import 'package:flutter/material.dart';
import 'package:bb_player/bb_player.dart';

class VideoScreen extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Video')),
      body: AspectRatio(
        aspectRatio: 16 / 9,
        child: BBPlayerView(
          jsonUrl: 'https://yourpublication.bbvms.com/p/default/c/1234567.json',
        ),
      ),
    );
  }
}

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 Flutter Player SDK Getting Started guide.

4.0 | Playback controls and events

Use onControllerCreated to receive a BBPlayerController and control playback programmatically:

class VideoPlayerScreen extends StatefulWidget {
  @override
  State<VideoPlayerScreen> createState() => _VideoPlayerScreenState();
}

class _VideoPlayerScreenState extends State<VideoPlayerScreen> {
  BBPlayerController? _controller;

  @override
  void dispose() {
    _controller?.destroy();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return Column(
      children: [
        AspectRatio(
          aspectRatio: 16 / 9,
          child: BBPlayerView(
            jsonUrl: 'https://yourpublication.bbvms.com/p/default/c/1234567.json',
            onControllerCreated: (controller) {
              setState(() => _controller = controller);
            },
          ),
        ),
        Row(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            IconButton(
              icon: const Icon(Icons.play_arrow),
              onPressed: () => _controller?.play(),
            ),
            IconButton(
              icon: const Icon(Icons.pause),
              onPressed: () => _controller?.pause(),
            ),
            IconButton(
              icon: const Icon(Icons.fullscreen),
              onPressed: () => _controller?.enterFullscreen(),
            ),
          ],
        ),
      ],
    );
  }
}

Listen to player events using callback props on BBPlayerView:

BBPlayerView(
  jsonUrl: 'https://yourpublication.bbvms.com/p/default/c/1234567.json',
  onPlay: () => print('Playing'),
  onPause: () => print('Paused'),
  onEnded: () => print('Ended'),
  onAdStarted: () => print('Ad started'),
  onAdFinished: () => print('Ad finished'),
  onViewStarted: () => print('View started'),
  onError: (error) => print('Error: $error'),
)

The player exposes 40+ events covering playback state, ads, time updates, fullscreen, content loading, and analytics.

5.0 | System requirements

• Flutter 3.32+
• Dart SDK 3.8+
• iOS 14.0+
• Android API 21+

6.0 | Also available for native iOS, Android, and React Native

If you are not using Flutter, the player SDK is also available as:

• Native iOS and Android, via CocoaPods, SPM, or Maven: iOS and Android Native Player SDK
• React Native, via npm: React Native Player SDK

All SDKs connect to the same Blue Billywig publication and support the same content and ad configuration.