iOS and Android Native Player SDK: Get Started

The Blue Billywig Native Player SDK lets you embed native video playback directly inside your iOS or Android app.

1.0 | What is it?

The Native Player SDK provides a lightweight, hardware-accelerated video player for iOS and Android. It connects directly to your Blue Billywig publication and supports clips, playlists, and project embeds; the same content you publish on the web, now available in your native app.

The SDK has three main structures: the BBNativePlayer class (factory for creating player views), the BBNativePlayerView class (the UI view with playback controls), and the BBNativePlayerViewDelegate interface (for responding to player events).

New features developed for the web player are also developed for the native SDKs. Both iOS and Android are continuously updated.

2.0 | Features

• Native hardware-accelerated playback
• Support for clips, playlists, and project embeds
• Chromecast support (iOS and Android)
• AirPlay and Picture-in-Picture support (iOS)
• Outstream and Shorts playback
• Playback event callbacks (play, pause, and more)
• Full ad support (VAST, VPAID, Google IMA)

3.0 | Getting started

The player is created via BBNativePlayer.createPlayerView() using a JSON embed URL. The JSON URL is the standard Blue Billywig embed URL with a .json extension, for example:

https://yourpublication.bbvms.com/p/default/c/1234567.json

3.1 | Android

The SDK is distributed via Maven Central. Add the dependency to your app-level build.gradle.kts:

dependencies {
    implementation("com.bluebillywig.bbnativeplayersdk:bbnativeplayersdk:8.40.0")
}

A minimal implementation in Kotlin:

import com.bluebillywig.bbnativeplayersdk.BBNativePlayer
import com.bluebillywig.bbnativeplayersdk.BBNativePlayerView

class MainActivity : AppCompatActivity() {
    private lateinit var playerContainer: LinearLayout
    private var playerView: BBNativePlayerView? = null

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)

        playerContainer = findViewById<LinearLayout>(R.id.player_container)
        playerView = BBNativePlayer.createPlayerView(
            this,
            "https://yourpublication.bbvms.com/p/default/c/1234567.json"
        )
        playerContainer.addView(playerView)
    }
}

Add the required permissions to AndroidManifest.xml:

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="com.google.android.gms.permission.AD_ID"/>
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PLAYBACK" />

For the full Android setup guide, visit the Android Getting Started guide.

3.2 | iOS

The SDK (BBNativePlayerKit) is available via Swift Package Manager (SPM). It needs iOS 14.0 or later and brings the shared module, Google IMA, Google User Messaging Platform and Google Cast, so you do not add those yourself.

1. In Xcode, go to File > Add Package Dependencies.
2. Enter the repository URL https://github.com/bluebillywig/bbnativeplayerkit-cocoapod.
3. Set Dependency Rule to Exact Version and enter 8.63.0 or a later version. A new SDK version can contain breaking changes even when only the middle number goes up.
4. Click Add Package and pick one product. Set Add to Target to your app target for that product, and to None for the other one.

Add exactly one product, never both. Each one contains its own copy of Google Cast.

CocoaPods: version 8.64 is the last version on CocoaPods and gets no further updates. Move to Swift Package Manager; the migration guide has the steps.

A minimal Swift implementation:

import UIKit
import BBNativePlayerKit
import bbnativeshared

class ViewController: UIViewController {
    private var bbPlayerView: BBNativePlayerView? = nil

    override func viewDidLoad() {
        super.viewDidLoad()

        bbPlayerView = BBNativePlayer.createPlayerView(
            uiViewController: self,
            frame: view.frame,
            jsonUrl: "https://yourpublication.bbvms.com/p/default/c/1234567.json"
        )
        view.addSubview(bbPlayerView!)

        bbPlayerView?.translatesAutoresizingMaskIntoConstraints = false
        bbPlayerView?.leftAnchor.constraint(equalTo: view.safeAreaLayoutGuide.leftAnchor).isActive = true
        bbPlayerView?.topAnchor.constraint(equalTo: view.safeAreaLayoutGuide.topAnchor).isActive = true
        bbPlayerView?.widthAnchor.constraint(equalTo: view.safeAreaLayoutGuide.widthAnchor).isActive = true
        bbPlayerView?.heightAnchor.constraint(equalToConstant: view.safeAreaLayoutGuide.layoutFrame.width * 9/16).isActive = true
    }
}

For the full iOS setup guide, visit the iOS Getting Started guide.

4.0 | System requirements

4.1 | Android

• Android API 21+
• Kotlin or Java

4.2 | iOS

• iOS 14.0+
• Xcode 14.3.1+
• Swift or Objective-C

5.0 | Also available for React Native and Flutter

If you are building a cross-platform app, the same native playback is available for:

• React Native: React Native Player SDK — one TypeScript codebase for iOS and Android, with Expo support.
• Flutter: Flutter Player SDK — a Dart/Flutter plugin for iOS and Android, distributed as a public Git package.

6.0 | Looking for a complete video experience?

If you want to embed a full branded video portal with swim lanes, carousels, search, and detail pages, the Channels SDK builds on top of the Native Player SDK and gives you a turnkey streaming experience inside your app. It is available for all three mobile platforms:

• Jetpack Compose (Android): Jetpack Compose Channels SDK
• SwiftUI (iOS): SwiftUI Channels SDK
• React Native: React Native Channels SDK, or React Native Player SDK for standalone playback