Getting Started — UIKit

This guide shows how to integrate the Blue Billywig Native Player SDK into a UIKit-based iOS app. This is the primary surface; most apps should start here.

tip

Building a SwiftUI app on iOS 17+? See the SwiftUI Getting Started for a SwiftUI View wrapper around this same SDK.

1. Create a new Xcode project

In Xcode, create a new iOS project using Objective-C or Swift. Use BBNativePlayerExample as the project name.

2. Add BlueBillywigNativePlayerKit-iOS to the Xcode project

The recommended installation method is CocoaPods. In the same directory as your BBNativePlayerExample.xcodeproject, create a text file called Podfile with:

platform :ios, '11.0'

target 'BBNativePlayerExample' do
  pod 'BlueBillywigNativePlayerKit-iOS', '~><version>'
end

From the directory containing the Podfile, run:

pod install --repo-update

This installs BlueBillywigNativePlayerKit-iOS and its dependencies. You should see output similar to:

Installing BlueBillywigNativePlayerKit-iOS (<version>)
Installing BlueBillywigNativeShared-iOS (<version>)
Installing GoogleAds-IMA-iOS-SDK (<version>)

Verify the installation by opening the BBNativePlayerExample.xcworkspace file and confirming it contains two projects: BBNativePlayerExample and Pods.

If pod resolution misbehaves, reset CocoaPods state:

pod cache clean --all
rm -rf Podfile.lock Pods
pod install --repo-update

note

Swift Package Manager is also supported — add https://github.com/bluebillywig/bbnativeplayerkit-cocoapod as a package dependency and select the BlueBillywigNativePlayerKit-iOS product.

3. Import the framework

Add the import statements to your ViewController:

import UIKit
import BBNativePlayerKit
import bbnativeshared

class ViewController: UIViewController {
    // ...
}

4. Create a BBNativePlayerView

In viewDidLoad, create a player view via BBNativePlayer.createPlayerView(frame:jsonUrl:) and add it to your view hierarchy. Use your own embed URL as the jsonUrl parameter:

private var bbPlayerView: BBNativePlayerView? = nil

override func viewDidLoad() {
    super.viewDidLoad()

    // Create the player view from a publication's embed URL.
    bbPlayerView = BBNativePlayer.createPlayerView(
        frame: view.frame,
        jsonUrl: "https://bb.dev.bbvms.com/p/default/c/1092747.json"
    )

    view.addSubview(bbPlayerView!)

    // Use Auto Layout for sizing/placement.
    bbPlayerView?.translatesAutoresizingMaskIntoConstraints = false
    bbPlayerView?.leftAnchor.constraint(equalTo: view.safeAreaLayoutGuide.leftAnchor).isActive = true
    bbPlayerView?.topAnchor.constraint(equalTo: view.safeAreaLayoutGuide.topAnchor, constant: 0).isActive = true
    bbPlayerView?.widthAnchor.constraint(equalTo: view.safeAreaLayoutGuide.widthAnchor).isActive = true
    bbPlayerView?.heightAnchor.constraint(equalToConstant: view.safeAreaLayoutGuide.layoutFrame.width * 9 / 16).isActive = true
}

5. Set the delegate

Assign self as the player's delegate so it can deliver lifecycle and playback events:

override func viewDidLoad() {
    super.viewDidLoad()
    // ... player creation as above ...

    bbPlayerView?.delegate = self
}

6. Implement BBNativePlayerViewDelegate

The delegate is typically implemented in an extension to keep view controller code organized. A minimal example:

extension ViewController: BBNativePlayerViewDelegate {
    func didTriggerPlay() {
        print("Blue Billywig Player: didTriggerPlay")
    }

    func didTriggerPause() {
        print("Blue Billywig Player: didTriggerPause")
    }
}

See the BBNativePlayerViewDelegate API reference for the full list of callbacks (phase changes, state changes, ad events, fullscreen requests, Cast events, etc.).

7. Build and run

Run on a simulator or device. For Picture-in-Picture and AirPlay, see Picture-in-Picture & AirPlay — they require a capability and only work on physical devices.

Demo app

For a complete, working example, see bbnativeplayerkit-demo.