BOSS Platform API

Introduction

Overview of BOSS Player SDKs across web, mobile, and TV platforms.

BOSS Player is GO BOSS's multi-platform video player SDK. Integrate once with a player key from the BOSS CMS, and get playback, DRM, ads, analytics, casting, and feature gating on every screen your app supports.

This documentation is modeled after professional SDK guides (Sendbird, Firebase): install instructions, initialize samples, full configuration tables, and event references for each platform.

Supported platforms

How it works

flowchart LR
  CMS[BOSS CMS] -->|player key| App[Your app]
  App -->|SDK init| API[BOSS Player API]
  API -->|features and entitlement| SDK[BOSS Player SDK]
  SDK --> Playback[Playback UI]

1. Create or copy a player key in BOSS CMS (BOSS Player section).
2. Install the SDK for your platform.
3. Call the platform initialize API with the player key (where required).
4. Pass a stream URL and optional custom parameters (theme, DRM, ads, watermark, headers).
5. The SDK contacts POST /api/player/sdk/init and applies feature gates (ads, DRM, cast, PiP, subtitles, and more).

What you get

• HLS / DASH / progressive playback
• Tenant player key entitlement and feature flags
• Theme color, watermark, and UI controls
• DRM (Widevine / FairPlay / PlayReady where supported)
• SSAI / MediaTailor overlay ads
• Analytics sessions, heartbeats, and event callbacks
• Platform extras: Chromecast, AirPlay, PiP, key moments, chapters, subtitles

Next steps

• Getting started — first playback in minutes
• Player key & init — how authentication and gating work
• Custom parameters — shared config concepts across SDKs
• Pick a platform from the sidebar and open Installation

Getting started

Obtain a player key and play your first video with BOSS Player.

Follow these steps to play your first video with BOSS Player.

1. Get a player key

1. Sign in to BOSS CMS.
2. Open BOSS Player (or Monetization → player settings, depending on your tenant layout).
3. Copy your player key (often prefixed like bsp_… or vd_…).

You will pass this key as playerKey / apiKey when initializing the SDK.

2. Pick a platform

3. Minimal examples

Web (React)

import { BossVideoPlayer } from 'boss-web-player-sdk';
import 'boss-web-player-sdk/css';

export function App() {
  return (
    <BossVideoPlayer
      playerKey="YOUR_PLAYER_KEY"
      src="https://cdn.example.com/video.m3u8"
      title="My Video"
      themeColor="#865fe3"
    />
  );
}

iOS (Swift)

import VuedataPlayerSDK

VuedataPlayer.initialize(apiKey: "YOUR_PLAYER_KEY") { result in
    guard case .success = result else { return }
    // present player after success
}

let config = VuedataPlayerConfiguration(
    videoURL: URL(string: "https://cdn.example.com/video.m3u8")!,
    title: "My Video",
    defaultOrientation: .landscape
)

let player = VuedataPlayerViewController(configuration: config)
present(player, animated: true)

Android (Kotlin)

VideoPlayerActivity.launch(
    context,
    PlayerConfiguration(
        title = "My Video",
        videoUrl = "https://cdn.example.com/video.m3u8",
        apiKey = "YOUR_PLAYER_KEY",
    )
)

Flutter

await VideoPlayerSDK.initialize(apiKey: 'YOUR_PLAYER_KEY');

VdPlayerView(
  configuration: VdPlayerConfiguration(
    title: 'My Video',
    videoUrl: Uri.parse('https://cdn.example.com/video.m3u8'),
  ),
)

React Native

import { RNVideoPlayer } from '@goboss/react-native-video-player-sdk';

<RNVideoPlayer
  src="https://cdn.example.com/video.m3u8"
  playerKey="YOUR_PLAYER_KEY"
  title="My Video"
  themeColor="#865fe3"
/>

4. Add custom parameters

Once playback works, explore shared options such as DRM, ads tracking URL, watermark, headers, start position, and analytics callbacks:

• Custom parameters
• DRM
• Ads & SSAI
• Analytics

Checklist

• To do: Player key from CMS
• To do: SDK installed for your platform
• To do: Valid HTTPS stream URL (HLS/DASH/MP4)
• To do: Theme color / branding (optional)
• To do: Event listeners for errors and analytics (recommended for production)

Player key & init

How BOSS Player authenticates tenants and applies feature gates.

Every BOSS Player SDK can authenticate against the BOSS backend using a player key issued in the CMS. Successful init returns an entitlement package that gates features (ads, DRM, cast, PiP, subtitles, key moments, and more).

API

POST /api/player/sdk/init
Header: x-player-key: YOUR_PLAYER_KEY

Per-platform init

Feature gates

After init, the backend returns licensed features. Typical flags include:

• Stream formats (e.g. HLS / m3u8)
• Subtitles, playback speed, quality, multi-audio
• Key moments / chapters
• DRM
• Screen recording / content protection
• Ads / SSAI
• Chromecast, AirPlay, PiP

Unavailable features are hidden or disabled in the player UI.

Sessions & heartbeats

Most SDKs also start a playback session and send heartbeats / analytics events:

• session/start
• session/heartbeat
• session/end
• event logging (play, pause, seek, quartiles, errors, …)

See Analytics for details.

Security tips

• Treat the player key like a client credential: restrict by domain / app where CMS allows it.
• Prefer short-lived DRM auth tokens over embedding long-lived secrets in the client.
• Use HTTPS for all stream and license URLs.

Custom parameters

Shared configuration options across BOSS Player SDKs.

BOSS Player SDKs share a common configuration model even though property names differ slightly by language. Use this guide as a cross-platform map, then open the platform Configuration page for exact types.

Identity & auth

Media

Branding & UI

DRM

Full details: DRM.

Ads

Full details: Ads & SSAI.

Timeline metadata

Feature flags

Many SDKs expose toggles such as:

• Chromecast / AirPlay / PiP
• Quality / speed / audio tracks
• Fullscreen / gestures
• Content protection / secure mode
• Key moments / thumbnails

When a player key is present, server entitlements usually override local flags.

Analytics callbacks

See Events & delegates and Analytics.

Example: rich web config

<BossVideoPlayer
  playerKey="bsp_your_key"
  src="https://cdn.example.com/master.m3u8"
  title="Episode 1"
  themeColor="#865fe3"
  watermark="SECURE VIEW"
  autoplay
  muted
  initialTime={30}
  adTrackingUrl="https://ads.example.com/v1/tracking/…"
  drmConfig={{
    authToken: "…",
    widevineLicenseUrl: "https://license.example.com/widevine",
    fairplayLicenseUrl: "https://license.example.com/fairplay",
  }}
  onAnalyticsEvent={(e) => console.log(e.eventType, e)}
/>

Example: rich iOS config

let config = VuedataPlayerConfiguration(
    videoURL: streamURL,
    title: "Episode 1",
    defaultOrientation: .landscape,
    videoID: "ep-1",
    mediaTailorTrackingURL: trackingURL,
    contentDuration: 2400,
    chromeCastEnabled: true,
    pictureInPictureEnabled: true
)

DRM

Configure Widevine, FairPlay, and PlayReady for BOSS Player.

BOSS Player supports common DRM schemes on platforms that expose host-facing license configuration. Exact field names vary by platform; entitlement must include DRM in the player key package where licensing applies.

Supported schemes (where configured by the host)

Common web / RN fields

type DRMConfig = {
  widevineLicenseUrl?: string;
  fairplayLicenseUrl?: string;
  playreadyLicenseUrl?: string;
  authToken?: string;
  authHeader?: string;
  allowedDomains?: string[];
  watermarkText?: string;
};

Web

<BossVideoPlayer
  playerKey="bsp_…"
  src="https://cdn.example.com/encrypted.m3u8"
  drmConfig={{
    authToken: "LICENSE_TOKEN",
    widevineLicenseUrl: "https://license.example.com/widevine",
    fairplayLicenseUrl: "https://license.example.com/fairplay",
    playreadyLicenseUrl: "https://license.example.com/playready",
  }}
/>

React Native

<RNVideoPlayer
  src="https://cdn.example.com/encrypted.m3u8"
  playerKey="…"
  drmConfig={{
    authToken: "LICENSE_TOKEN",
    widevineLicenseUrl: "https://license.example.com/widevine",
    fairplayLicenseUrl: "https://license.example.com/fairplay",
  }}
  enableSecureMode
/>

iOS (native SDK)

Use content-protection / screenshot-preventing view factories when your license and product requirements call for them.

Android / Android TV

Enable content protection on PlayerConfiguration (isContentProtectionEnabled) and integrate license acquisition through your approved DRM path for that build.

Flutter

DRM may appear in licensed features after VideoPlayerSDK.initialize. Combine with header providers for auth as needed; verify depth against the package version you pin.

Checklist

• To do: Player key includes DRM entitlement (where required)
• To do: Correct license URL per scheme / platform that supports host config
• To do: Auth token refreshed before expiry
• To do: Test on real devices for each scheme you claim
• To do: Do not document FairPlay host APIs for native iOS

Ads & SSAI

MediaTailor, overlay ads, and ad break callbacks in BOSS Player.

BOSS Player integrates server-side ad insertion (SSAI) and overlay ad tracking. Ads are typically gated by the player key entitlement.

Concepts

Web

<BossVideoPlayer
  playerKey="bsp_…"
  src="https://cdn.example.com/ssai.m3u8"
  adTrackingUrl="https://ads.example.com/v1/tracking/…"
  overlayAdUrl="https://ads.example.com/overlay"
  enableSkipAd
  skipAdAfterSeconds={5}
/>

Lower-level WebVideoPlayer also exposes onAdBreakChange and pauseAdOnTabSwitch.

Core APIs:

• getAdBreaks() / setAdBreaks() / isInAdBreak()
• Events: adbreaksloaded, adbreakchange

React Native

<RNVideoPlayer
  src="…"
  playerKey="…"
  adTrackingUrl="https://ads.example.com/v1/tracking/…"
/>

Analytics may emit ad_break_start, ad_break_end, ad_marker_error.

iOS

let config = VuedataPlayerConfiguration(
    videoURL: url,
    title: "Episode",
    defaultOrientation: .landscape,
    videoID: "ep-1",
    adsEnabled: true,
    contentDuration: 2400,
    mediaTailorTrackingURL: trackingURL
)

Delegate callbacks cover SSAI ad-break start, finish, and watched-ad skip (see iOS events).

Android / Android TV

PlayerConfiguration(
    title = "Episode",
    videoUrl = url,
    isOverlayAdsEnabled = true,
    overlayAdTrackingUrl = "https://ads.example.com/v1/tracking/…",
)

Listener: onAdBreakStarted, onAdBreakCompleted.

Flutter

Ads are feature-gated after init. Pass tracking through your configuration / entitlement package as documented for your SDK version.

CMS

Configure ad ingestion and tracking in BOSS CMS → Monetization → Ad Ingestion. The player key must include ads in its licensed features for client SDKs to show ad UI.

Analytics

Sessions, heartbeats, and playback analytics events.

BOSS Player SDKs report playback telemetry to the BOSS backend and optionally to Firebase / custom handlers.

Session lifecycle

init → session/start → heartbeats + events → session/end

Heartbeat interval is often configurable (default commonly 30 seconds).

Common event names

Platform-specific extras (live edge, ad breaks) appear on React Native and Android.

Wiring handlers

Web

<BossVideoPlayer
  playerKey="…"
  src="…"
  firebaseConfig={/* optional */}
  onAnalyticsEvent={(e) => {
    console.log(e.eventType, e);
  }}
/>

iOS

analyticsHandler: { event in
    print(event.name, event.parameters)
}

Android

Implement VideoPlayerEventListener and/or use the bundled analytics module (com.vd.analytics).

Flutter

analyticsHandler: (event) {
  // event name + parameters
},
callbacks: VdPlayerCallbacks(
  watchHistoryCallback: (pos, duration) {},
),

React Native

Use delegate props and optional @react-native-firebase/analytics.

Privacy

• Do not put PII in custom analytics properties unless your policy allows it.
• Align retention with your tenant's CMS / data settings.

Events & delegates

Cross-platform map of BOSS Player playback callbacks.

Each SDK exposes playback lifecycle callbacks. Names differ, but the concepts align.

Lifecycle

Track & UI changes

Quality, subtitle, audio, speed, fullscreen, PiP, key moments, and ad breaks are exposed on platforms that support those features. See each platform's Events page for the exact method signatures.

Web core emitter

If you use boss-web-player-sdk/core, subscribe with player.on(event, handler):

play, pause, ended, timeupdate, seeking, buffering, volumechange, ratechange, pipchange, error, qualitylevels, qualitychange, subtitlesloaded, audiotracksloaded, audiotrackchange, keymomentsloaded, chaptersloaded, adbreaksloaded, adbreakchange, unsupportedcodec

Best practices

1. Always handle error callbacks in production.
2. Use watch progress / time updates to persist resume position.
3. Prefer analytics handlers for telemetry; keep UI delegates for UX only.
4. On TV, prefer D-pad-friendly flows and test dismiss / back carefully.

Web — Overview

BOSS Player Web SDK overview and license gating.

Package: boss-web-player-sdk (npm) Surfaces: BossVideoPlayer (React), createPlayer (vanilla), boss-web-player-sdk/core (headless)

The Web SDK delivers a production player for browsers with:

• HLS / DASH / progressive playback (hls.js + dashjs bundled)
• Tenant playerKey entitlement and feature gating
• Theme color, watermark, chapters, key moments, subtitles
• DRM config (Widevine / FairPlay / PlayReady where the browser supports it)
• SSAI / overlay ads tracking
• Chromecast, PiP, fullscreen
• Analytics sessions and onAnalyticsEvent / PlayerDelegate

Web — Installation

Install the BOSS Player Web SDK from npm.

Requirements

Install

npm install boss-web-player-sdk

import 'boss-web-player-sdk/css';

Optional: npm install firebase for analytics.

Package exports

Source repo: GO-BOSS-PRODUCTS/boss-player-web-sdk (use branch development if cloning)

Web — Quick start

Create a BOSS Player instance on the web.

playerKey and src are required for gated UI. Prefer mounting only after you have a valid key from CMS.

import { BossVideoPlayer } from 'boss-web-player-sdk';
import 'boss-web-player-sdk/css';

export function Player() {
  return (
    <BossVideoPlayer
      playerKey="bsp_your_player_key"
      src="https://cdn.example.com/video.m3u8"
      title="My Video"
      themeColor="#865fe3"
      autoplay
      muted
      onAnalyticsEvent={(e) => console.log(e.eventType)}
    />
  );
}

import { createPlayer } from 'boss-web-player-sdk';
import 'boss-web-player-sdk/css';

const player = createPlayer(document.getElementById('player')!, {
  playerKey: 'bsp_your_player_key',
  src: 'https://cdn.example.com/video.m3u8',
  title: 'My Video',
  themeColor: '#865fe3',
});

player.update({ src: 'https://cdn.example.com/other.m3u8' });
player.destroy();

import { VideoPlayerSDK } from 'boss-web-player-sdk/core';

const player = new VideoPlayerSDK({
  container: document.getElementById('player')!,
  src: 'https://cdn.example.com/video.m3u8',
  autoplay: false,
  muted: false,
  themeColor: '#865fe3',
});

player.play();
player.pause();
player.seek(30);
player.destroy();

What happens on init

1. SDK sends POST /api/player/sdk/init with x-player-key.
2. Entitlements unlock licensed features.
3. Player mounts UI, loads the stream, and starts analytics when playback begins.

Override API host with apiBaseUrl when needed.

Web — Configuration

Props and options for the BOSS Player Web SDK with types.

Required (BossVideoPlayer / createPlayer)

Optional

Intro / outro and next episode

DRMConfig

Web — Features

Web SDK feature support matrix.

Web — Events

Analytics events and PlayerDelegate callbacks for the Web SDK.

onAnalyticsEvent

eventType values include:

play, pause, seek, ended, complete, buffering_start, buffering_end, stall, quality_change, audio_track_change, volume_change, speed_change, subtitle_change, mute, fast_forward, fast_backward, key_moments, pip_toggle, fullscreen_enter, fullscreen_exit, cast_start, cast_stop, error, network_error, session_start, video_loaded, first_quartile, midpoint, third_quartile, heartbeat, watch_progress, streaming_time

PlayerDelegate

Typed callbacks:

• Start / resume / pause / finish / dismiss
• Seek start / finish
• Current time updates
• Buffering
• Quality / subtitle / audio / speed changes
• Fullscreen, key moment, PiP
• Playback and network errors

<BossVideoPlayer
  playerKey="…"
  src="…"
  delegate={{
    playerDidStartPlaying: () => {},
    playerDidPause: () => {},
    playerDidFinishPlaying: () => {},
    playerDidEncounterPlaybackError: (code, message) => {
      console.error(code, message);
    },
  }}
/>

Core emitter events

play, pause, ended, timeupdate, seeking, buffering, volumechange, ratechange, pipchange, error, qualitylevels, qualitychange, subtitlesloaded, audiotracksloaded, audiotrackchange, keymomentsloaded, chaptersloaded, adbreaksloaded, adbreakchange, adbreakdiscoverysettled, unsupportedcodec

Web — Best practices

Web SDK integration gotchas.

1. Import CSS once — import 'boss-web-player-sdk/css'.
2. Require playerKey + src on gated UI (BossVideoPlayer / createPlayer).
3. Prefer muted autoplay — browsers often block unmuted autoplay.
4. Set apiBaseUrl for production — packages may default to the dev API host.
5. Use drmConfig field names from types — prefer widevineLicenseUrl over outdated README aliases.
6. Destroy players — call destroy() / unmount to end sessions cleanly.
7. Handle error / network_error in analytics or delegate callbacks.
8. Checkout development if cloning the private monorepo (main may be empty).

Web — Playback control

Programmatic play, pause, seek, and related APIs.

Gated mount (createPlayer)

const player = createPlayer(el, { playerKey, src });
player.update({ src: nextUrl, title: 'Next' });
player.destroy();

Headless core (VideoPlayerSDK)

player.play();
player.pause();
player.seek(30);
player.setVolume(0.8);
player.setMute(true);
player.setPlaybackRate(1.25);
player.setQuality(level);
player.setAudioTrack(track);
player.toggleFullscreen();

player.getCurrentTime();
player.getDuration();
player.getVolume();
player.isMuted();
player.getPlaybackRate();
player.getQualityLevels();
player.getActiveQuality();
player.getAudioTracks();
player.getBufferLength();
player.getBufferedRanges();
player.getVideoElement();

player.getAdBreaks();
player.setAdBreaks(breaks);
player.isInAdBreak();
player.destroy();

Modules on the instance

analytics, keyMoments, chapters, subtitles, drm, casting, thumbnails

Events

player.on('timeupdate', handler);
player.off('timeupdate', handler);

See Events for the full list.

Web — Troubleshooting

Common Web SDK issues and fixes.

Still stuck? Capture the analytics error / network_error payload and the init response body for support.

Report with: SDK version, browser/OS, reproduction steps, network traces for /api/player/sdk/init.

iOS — Overview

BOSS Player iOS SDK overview, capabilities, and license gating.

Audience: iOS application developers integrating the SDK, and SDK maintainers Latest distributable version: 1.0.4

VuedataPlayerSDK is a UIKit-based iOS video player built for HLS playback. It bundles the pieces most streaming apps need out of the box:

• Configurable playback controls and quality / audio track selection
• Captions and subtitles (manifest-based and external WebVTT)
• Playback speed control
• Key moments (chapters)
• Server-side ad insertion (SSAI)
• AirPlay and Google Cast
• Picture in Picture
• Analytics and watch-history callbacks
• Orientation handling
• Network recovery
• Optional screen-capture protection

iOS — Installation

Requirements and SPM install for BOSS Player iOS SDK 1.0.4.

Requirements

Prerequisites

• iOS 15 or later
• Xcode with Swift 5.9 or later (tools compatible with the selected release)
• Swift Package Manager

Add the package

In Xcode:

1. File → Add Package Dependencies…
2. Enter the repository URL:

https://github.com/GO-BOSS-PRODUCTS/boss-player-swift-sdk-pkg

1. Choose the approved release version (1.0.4 or later as published).
2. Add the VuedataPlayerSDK product to your application target.

Or in Package.swift:

.package(
  url: "https://github.com/GO-BOSS-PRODUCTS/boss-player-swift-sdk-pkg",
  from: "1.0.4"
)

The public package resolves a binary XCFramework (plus the Google Cast dependency).

Import

import VuedataPlayerSDK

Repos

iOS — Quick start

Initialize VuedataPlayer and present the player fullscreen.

Initialize once at app startup, before presenting any player instance. Initialization is asynchronous — wait for a successful result before creating or presenting a player.

1. Initialize the SDK

import VuedataPlayerSDK

VuedataPlayer.initialize(apiKey: "YOUR_PLAYER_KEY") { result in
    switch result {
    case .success:
        // Package / feature gates resolved — safe to present players
        break
    case .failure(let error):
        // Handle: empty key, invalid URL/response, inactive package,
        // unexpected HTTP status, or networking error
        print("SDK init failed:", error)
    }
}

Inspect state

VuedataPlayer.activePackage
VuedataPlayer.activeFeatures
VuedataPlayer.initializationState

Init calls POST /api/player/sdk/init with x-player-key

2. Configure and present the player

The player is always presented full screen.

let config = VuedataPlayerConfiguration(
    videoURL: URL(string: "https://cdn.example.com/video.m3u8")!,
    title: "Episode 1",
    defaultOrientation: .landscape,
    videoID: "ep-123"
)

let player = VuedataPlayerViewController(configuration: config)
player.delegate = self
present(player, animated: true)

Minimal end-to-end example

import UIKit
import VuedataPlayerSDK

final class PlayerHostViewController: UIViewController {
    override func viewDidLoad() {
        super.viewDidLoad()
        VuedataPlayer.initialize(apiKey: "YOUR_PLAYER_KEY") { [weak self] result in
            guard case .success = result else { return }
            DispatchQueue.main.async { self?.presentPlayer() }
        }
    }

    private func presentPlayer() {
        guard let url = URL(string: "https://cdn.example.com/video.m3u8") else { return }
        let config = VuedataPlayerConfiguration(
            videoURL: url,
            title: "Episode 1",
            defaultOrientation: .landscape,
            videoID: "ep-123"
        )
        let player = VuedataPlayerViewController(configuration: config)
        player.delegate = self
        present(player, animated: true)
    }
}

extension PlayerHostViewController: VuedataPlayerDelegate {
    // Implement callbacks as needed — see Events
}

iOS — Configuration

Full VuedataPlayerConfiguration reference with types and defaults.

Required values

Optional values

Additional integration fields (builders / advanced)

Fluent helpers include: withAPIKey, withPlayback*, withLiveVideo, withThumbnail*, withScreenCaptureProtection, withAirPlay / Cast / PiP helpers, withSDKPackage, withMediaTailorTrackingURL, withAnalyticsProperties, withHeartbeat, withSubtitleURL.

Integration notes

• subtitleURL supplies one external track in addition to any subtitles already present in the media manifest — it does not replace them.
• Set subtitlePreferenceDefaultsKey only if the app should remember the user's subtitle language across sessions.
• startTimeSeconds is an Int, expressed in seconds.
• Set isLivevideo = true for live streams; this hides duration and seek controls.
• Assign delegate before presenting the player if you need playback or watch-history callbacks.
• orientationRequestHandler is only needed if your app maintains a dynamic orientation lock in AppDelegate.

Subtitle auto-select policies

Orientation policies

Example

let config = VuedataPlayerConfiguration(
    videoURL: streamURL,
    title: "Episode 1",
    defaultOrientation: .landscape,
    videoID: "ep-1",
    mediaTailorTrackingURL: trackingURL,
    subtitleURL: vttURL,
    subtitleLanguageCode: "en",
    subtitleAutoSelectPolicy: .preferred(languageCode: "en"),
    startTimeSeconds: 30,
    contentDuration: 2400,
    chromeCastEnabled: true,
    airPlayEnabled: true,
    pictureInPictureEnabled: true
)

iOS — Features

iOS feature support matrix and license conditions.

iOS — Events

VuedataPlayerDelegate callbacks and watch-history guidance.

Implement VuedataPlayerDelegate for visibility into:

• Playback start, resume, pause, finish, and dismissal
• Seek start and completion
• Buffering start and completion
• Quality, audio, subtitle, and speed changes
• Fullscreen enter/exit
• SSAI ad-break start, finish, and watched-ad skip
• Key-moment selection
• Picture in Picture enter/exit
• Playback and network errors
• Periodic watch-history progress

extension MyViewController: VuedataPlayerDelegate {
    func playerDidStartPlaying(/* … */) {}
    func playerDidPause(/* … */) {}
    func playerDidFinishPlaying(/* … */) {}
    func playerDidDismiss(/* … */) {
        // Persist final watch position here
    }
    func playerDidEncounterPlaybackError(/* … */) {}
}

Analytics event names

player_session_start, play, pause, seek, ended, buffering_start/end, stall, quality_change, volume_change, speed_change, subtitle_change, audio_track_change, key_moments, pip_toggle, fullscreen_enter/exit, cast_start/stop, player_error, network_error, quartiles

iOS — Best practices & gotchas

Integration gotchas for the BOSS Player iOS SDK.

1. Initialize before presenting. Always wait for a successful VuedataPlayer.initialize result before creating a player instance.

1. Feature flags are gates, not switches. pictureInPictureEnabled and similar host-side flags cannot unlock a feature the license package doesn't grant.

1. Keep secrets dynamic. Use header-provider closures so expiring tokens are resolved immediately before each request. Never hard-code credentials.

1. Separate header domains. Playback, manifest/subtitle, and thumbnail requests may each require distinct auth, Referer, Origin, cookies, or User-Agent values.

1. Supply content duration for SSAI. When ads are enabled, provide contentDuration where available so the SDK can map stitched stream time back to content time.

1. SSAI is VOD-only. Ad support is disabled whenever isLivevideo == true.

1. Validate your speed index. defaultPlaybackSpeedIndex must be a valid index into playbackSpeeds.

1. Plan orientation carefully. The default orientation policy is forced landscape. If your app has its own AppDelegate orientation lock, implement orientationRequestHandler or switch to .hostManaged.

1. PiP is device-dependent. Enabling the flag doesn't guarantee PiP is available for the current device/state.

1. Google Cast needs app-level setup. Beyond linking the dependency, confirm Cast configuration, network permissions, and receiver setup.

1. Screen-capture protection ≠ DRM. It relies on a host-provided view factory and should be tested on every supported iOS version; it is unrelated to FairPlay.

1. Rely on the dismissal callback for final persistence. Don't assume the last periodic watch-history tick captured the final seconds of a session.

1. Track release metadata on every update. Confirm both the Swift Package release tag and the framework bundle version each time you upgrade.

iOS — Presentation

How the iOS player is presented (UI-driven fullscreen VC).

Present the player as a fullscreen view controller after a successful SDK init:

let player = VuedataPlayerViewController(configuration: config)
player.delegate = self
present(player, animated: true)

See Quick start and Best practices for the full integration flow.

iOS — Troubleshooting & support

Support, versioning, and common iOS SDK issues.

Versioning

Always confirm the Swift Package release tag matches the intended framework bundle version before shipping (latest documented distributable: 1.0.4).

Common issues

What to report

When opening an integration issue, include:

• SDK / SPM version (tag + bundle version)
• iOS version
• Device model
• Reproduction steps
• Init / playback error payloads if available

Android — Overview

BOSS Player Android SDK overview.

Artifact: com.goboss:videoplayer-sdk (GitHub Packages) Surfaces: VideoPlayerActivity.launch, Compose VideoPlayerSDK.VideoPlayer, VideoPlayerController

Kotlin / Media3 player for phones and tablets with:

• HLS playback and adaptive quality
• Chromecast and PiP
• Overlay ads / MediaTailor tracking
• Content protection hooks
• Analytics + session APIs
• Feature flags on PlayerConfiguration (subject to SDK init / license)

Android — Installation

Install BOSS Player for Android from GitHub Packages.

Requirements

Maven repository

https://maven.pkg.github.com/GO-BOSS-PRODUCTS/boss-player-android-sdk-pkg

maven {
    url = uri("https://maven.pkg.github.com/GO-BOSS-PRODUCTS/boss-player-android-sdk-pkg")
    credentials {
        username = providers.gradleProperty("gpr.user").orNull
            ?: System.getenv("GITHUB_ACTOR")
        password = providers.gradleProperty("gpr.key").orNull
            ?: System.getenv("GITHUB_TOKEN")
    }
}

implementation("com.goboss:videoplayer-sdk:1.0.0")

Android — Quick start

Authorize the SDK and launch playback on Android.

Initialize / authorize before launching playback when using tenant gating.

VideoSDK.initializeSdk("YOUR_PLAYER_KEY")

VideoPlayerActivity.launch(
    context,
    PlayerConfiguration(
        title = "My Video",
        videoUrl = "https://cdn.example.com/video.m3u8",
        apiKey = "YOUR_PLAYER_KEY",
        playerPlatform = PlayerPlatform.MOBILE,
    )
)

val controller = VideoPlayerController()

VideoPlayerSDK.VideoPlayer(
    initializationMode = PlayerInitializationMode.Local(
        PlayerConfiguration(
            title = "My Video",
            videoUrl = "https://cdn.example.com/video.m3u8",
            apiKey = "YOUR_PLAYER_KEY",
        )
    ),
    controller = controller,
    listener = myListener,
    onBackPressed = { /* … */ },
)

Android — Configuration

PlayerConfiguration fields for Android with types.

Core fields

Feature flags

Android — Features

Android phone SDK feature matrix.

Android — Events

VideoPlayerEventListener on Android.

Implement VideoPlayerEventListener:

val listener = object : VideoPlayerEventListener {
    override fun onPlayerError(error: /* … */) { /* … */ }
    override fun onProgressUpdate(position: Long, duration: Long) { /* … */ }
    // …
}

Android — Best practices

Android SDK integration gotchas.

1. Authorize before playback — VideoSDK.initializeSdk with a valid key.
2. Use GitHub Packages credentials with read:packages (and SSO if required).
3. Pin artifact versions in production (1.0.0 or your approved channel).
4. Set playerPlatform explicitly (MOBILE / TABLET) when not auto-detecting.
5. Wire VideoPlayerEventListener for errors and exit / ad breaks.
6. Release the controller — call releasePlayer() when leaving the screen.
7. Don’t assume TV Cast/PiP APIs on the phone sample when targeting Leanback — use the TV SDK.

Android — Playback control

VideoPlayerController APIs on Android.

val controller = VideoPlayerController()

controller.play()
controller.pause()
controller.seekTo(positionMs)
controller.forward()
controller.rewind()
controller.goLive()

// Tracks / quality / speed / volume
controller.setQuality(/* … */)
controller.setSubtitle(/* … */)
controller.setAudioTrack(/* … */)
controller.setPlaybackSpeed(/* … */)
controller.setVolume(/* … */)

controller.changePIPMode(/* … */)
controller.toggleFullscreen()

controller.releasePlayer()

Use getters on the controller for current position, duration, and track lists as exposed by your SDK version.

Android — Troubleshooting

Common Android SDK issues and fixes.

For living-room devices, see Android TV / Fire TV.

Apple TV — Overview

BOSS Player Apple TV SDK overview.

Module: VuedataAppleTVPlayerSDK Platform: tvOS 15+

tvOS player built on AVPlayerViewController with:

• HLS playback and track selection
• Programmatic play / pause / seek / select APIs
• Key moments, SSAI (where configured)
• Analytics / heartbeat hooks
• Focus-friendly TV UI (no Chromecast / PiP / mobile orientation)

Apple TV — Installation

Install BOSS Player for Apple TV (tvOS).

Requirements

Add the package (current path)

Private source package:

https://github.com/GO-BOSS-PRODUCTS/boss-apple-tv-player

Branch: confirm with your release process (often feature/initial_sdk until mainlined).

import VuedataAppleTVPlayerSDK

Apple TV — Quick start

Present the Apple TV player view controller.

Initialize once, wait for success, then present fullscreen:

import VuedataAppleTVPlayerSDK

VuedataPlayerSDK.initialize(apiKey: "YOUR_PLAYER_KEY") { result in
    guard case .success = result else { return }
    // present on main after success
}

let configuration = VuedataPlayerConfiguration(
    videoURL: URL(string: "https://cdn.example.com/video.m3u8")!,
    title: "Episode Title",
    videoID: "episode-123",
    analyticsHandler: { event in
        print(event.name, event.parameters)
    }
)

let playerViewController = VuedataPlayerViewController(configuration: configuration)
playerViewController.playerDelegate = self
present(playerViewController, animated: true)

Apple TV — Configuration

Configuration options for Apple TV.

Shared core with iOS, without mobile-only options (orientation lock, Chromecast, PiP, screen-capture factory, external subtitle URL helpers may differ).

Includes:

• Headers providers / user agent
• Start time, durations
• Ads + MediaTailor tracking URL
• Playback speeds + live flag
• Subtitle auto-select
• sdkPackage / licensed features
• Analytics handler / properties
• Watch-history interval + heartbeat

VuedataPlayerConfiguration(
    videoURL: streamURL,
    title: "Episode",
    videoID: "ep-1",
    adsEnabled: true,
    mediaTailorTrackingURL: trackingURL,
    isLivevideo: false,
    analyticsHandler: { event in /* … */ }
)

Apple TV — Features

Apple TV feature support matrix.

Apple TV — Events

Delegate callbacks on Apple TV.

VuedataPlayerDelegate covers:

• Playback / seek / buffering
• Quality / audio / subtitle / speed
• SSAI ads
• Key moments
• Errors
• Watch position
• Will dismiss

Intentionally excluded vs iOS: Cast, PiP, orientation, screen-capture hooks.

extension MyVC: VuedataPlayerDelegate {
    func playerDidStartPlaying(/* … */) {}
    func playerDidEncounterPlaybackError(/* … */) {}
}

Apple TV — Best practices

Apple TV SDK integration gotchas.

1. Initialize before present — wait for VuedataPlayerSDK.initialize success.
2. Use playerDelegate (naming differs from iOS delegate).
3. Design for the Siri Remote — test focus and dismiss flows on device.
4. Prefer VOD for SSAI — align with iOS guidance when ads are enabled.
5. Pin the source branch / XCFramework your release process approves until the public pkg ships.
6. Don’t expect iOS-only APIs (Cast, PiP, orientation lock).

Apple TV — Playback control

Programmatic control APIs on Apple TV.

VuedataPlayerViewController subclasses AVPlayerViewController and exposes:

player.play()
player.pause()
player.seek(to: time) { _ in }
player.selectPlaybackSpeed(at: index)
player.selectQuality(at: index)
player.selectSubtitle(at: index)
player.selectAudioTrack(at: index)
player.openKeyMoment(at: index)

Also available: videoVariants, subtitleTracks, audioTracks, keyMoments.

Apple TV — Troubleshooting & support

Apple TV support and common issues.

Report with: SDK version, tvOS version, device model, reproduction steps.

Apple TV — Public package (coming soon)

Public SPM package for Apple TV.

The public binary package repository is reserved at:

https://github.com/GO-BOSS-PRODUCTS/boss-player-apple-tv-sdk-pkg

Today it is empty (no Package.swift / releases yet). Until it ships:

1. Integrate via the private source repo boss-apple-tv-player, or
2. Consume a prebuilt XCFramework from your internal distribution process

When published, install will mirror iOS:

https://github.com/GO-BOSS-PRODUCTS/boss-player-apple-tv-sdk-pkg

Product name expected: VuedataAppleTVPlayerSDK.

Android TV / Fire TV — Overview

BOSS Player Android TV and Fire TV overview.

One SDK for both: Fire TV uses the same Leanback-oriented Android TV player. There is no separate Fire TV package.

• D-pad / focus-friendly controls
• PlayerPlatform.TV (or Leanback auto-detect)
• Overlay ads and content protection
• No Chromecast / PiP (living-room UI)

Android TV / Fire TV — Installation

Install BOSS Player for Android TV and Fire TV.

Requirements

implementation(project(":videoplayer-sdk"))

Manifest tips

• LEANBACK_LAUNCHER intent filter
• android.software.leanback (optional feature)
• TV banner / logo assets

Android TV / Fire TV — Quick start

Launch BOSS Player on Android TV / Fire TV.

Android TV / Fire TV — Configuration

TV-oriented PlayerConfiguration.

Same shape as the Android phone configuration, with TV-oriented differences:

Still supported: overlay ads, content protection, live, tracks, quality, subtitles, key moments, gestures (as applicable), overlayAdTrackingUrl.

PlayerConfiguration(
    title = "Episode 1",
    videoUrl = url,
    apiKey = key,
    playerPlatform = PlayerPlatform.TV,
    isOverlayAdsEnabled = true,
    overlayAdTrackingUrl = trackingUrl,
    isContentProtectionEnabled = true,
)

Android TV / Fire TV — Features

Android TV / Fire TV feature matrix.

Android TV / Fire TV — Events

Event listener differences on TV.

Same VideoPlayerEventListener as phone, minus:

• onChromecastConnected / onChromecastDisconnected
• onPipModeChanged

Retain handlers for ready, play/pause/complete, errors, progress, quality/subtitle/audio/speed, ads, screen capture, controls visibility, and exit.

Android TV / Fire TV — Best practices

Android TV / Fire TV gotchas.

1. Explicit PlayerPlatform.TV in configuration.
2. Add Leanback launcher metadata for store / sideload discovery.
3. Test on real Fire TV / Android TV hardware for focus and back behavior.
4. Do not look for a separate Fire TV artifact — this is the SDK.
5. Consume as module when Maven TV publish is unavailable.
6. Handle onPlayerExit / errors for session cleanup.

Android TV / Fire TV — Playback control

Controller APIs on Android TV.

VideoPlayerController matches the phone SDK except fullscreen / PiP helpers are removed:

controller.play()
controller.pause()
controller.seekTo(ms)
controller.forward()
controller.rewind()
controller.goLive()
controller.setQuality(/* … */)
controller.setSubtitle(/* … */)
controller.setAudioTrack(/* … */)
controller.setPlaybackSpeed(/* … */)
controller.releasePlayer()

TV UI uses Leanback-friendly controls (TvPlayerControls, focus managers). Design for D-pad navigation.

Android TV / Fire TV — Troubleshooting

Android TV / Fire TV troubleshooting.

Flutter — Overview

BOSS Player Flutter mobile SDK overview.

Package: vd_flutter_player_sdk (pub.dev) Platforms: Android + iOS mobile (Flutter TV is coming soon)

Cross-platform widget player with:

• VideoPlayerSDK.initialize(apiKey:) license gate
• VdPlayerView + VdPlayerConfiguration
• Feature flags, styling, cast/AirPlay/PiP hooks (subject to license)
• Analytics handler and VdPlayerCallbacks

Flutter — Installation

Install the Flutter BOSS Player package.

Requirements

pub.dev

dependencies:
  vd_flutter_player_sdk: ^0.0.8

flutter pub get

From Git

dependencies:
  vd_flutter_player_sdk:
    git:
      url: https://github.com/GO-BOSS-PRODUCTS/boss-player-flutter-sdk.git
      ref: develop
      path: vd-flutter-player-sdk

import 'package:vd_flutter_player_sdk/vd_flutter_player_sdk.dart';

Flutter — Quick start

Initialize VideoPlayerSDK and show VdPlayerView.

Initialize once at startup and wait before showing the player:

import 'package:vd_flutter_player_sdk/vd_flutter_player_sdk.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await VideoPlayerSDK.initialize(apiKey: 'YOUR_PLAYER_KEY');
  runApp(const MyApp());
}

// In your widget tree:
VdPlayerView(
  configuration: VdPlayerConfiguration(
    title: 'Course Video',
    videoUrl: Uri.parse('https://cdn.example.com/master.m3u8'),
    videoId: 'course-001',
  ),
)

Invalid keys show a license overlay unless isDownloaded: true (offline path).

Flutter — Configuration

VdPlayerConfiguration options.

Required

Options

Example

VdPlayerView(
  configuration: VdPlayerConfiguration(
    title: 'Episode 1',
    videoUrl: Uri.parse(hls),
    videoId: 'ep-1',
    startPosition: Duration(seconds: 15),
    autoPlay: true,
    headersProvider: () => {'Authorization': 'Bearer …'},
    analyticsHandler: (event) {},
    callbacks: VdPlayerCallbacks(
      watchHistoryCallback: (pos, duration) {},
      onQualityChanged: (from, to, isAuto) {},
    ),
    featureFlags: VdPlayerFeatureFlags(
      // enable / disable local flags; server entitlement may override
    ),
    style: VdPlayerStyle(
      // accent aligned to brand purple
    ),
  ),
)

Flutter — Features

Flutter mobile feature matrix.

Flutter — Events

Flutter analytics and VdPlayerCallbacks.

analyticsHandler

Host-emitted examples: player_opened, orientation_changed, orientation_change_ignored, key_moment_opened

Backend logEvent names include: play, pause, seek, buffering_start/end, fast_forward, fast_backward, quality_change, subtitle_change, subtitle_disable, speed_change, key_moments, fullscreen_toggle, pip_toggle, player_error, network_error

VdPlayerCallbacks

Wired for: started, pause/resume, complete, dismiss, seek start/end, buffering, quality, subtitle change/disable, speed, orientation, key moments, PiP enter/exit, watch history, playback/network errors.

Some declared callbacks (e.g. position / audio track) may not be fully wired in every package version — verify against the version you pin.

Flutter — Best practices

Flutter SDK integration gotchas.

1. await VideoPlayerSDK.initialize before showing VdPlayerView.
2. Use develop + package path if installing from git (main may be empty).
3. Prefer dynamic header providers for expiring tokens.
4. Persist resume via watchHistoryCallback / dismissal-equivalent callbacks.
5. Confirm API host for production (defaults may point at dev).
6. For TV apps today, use native Android TV / Apple TV SDKs until Flutter TV ships.

Flutter — Playback control

Flutter player surface and platform channels.

Primary integration is the VdPlayerView widget driven by VdPlayerConfiguration.

Platform channel helpers (VdPlayerPlatform) support:

• Screen capture controls
• Orientation
• PiP
• Cast configure / discover / cast media

Use callbacks and analytics handlers for progress and control side-effects. Prefer persisting resume position via watchHistoryCallback.

Flutter — Troubleshooting

Flutter SDK troubleshooting.

Flutter TV — Coming soon

Dedicated Flutter TV SDK status.

The repository boss-player-flutter-tv-sdk exists in the GO-BOSS-PRODUCTS org but is currently empty (no package code).

What to use today

This page will be replaced with install / init / configuration docs when the Flutter TV SDK ships.

React Native — Overview

BOSS Player React Native SDK overview.

Package: @goboss/react-native-video-player-sdk Components: RNVideoPlayer (mobile), TVVideoPlayer (TV)

React Native player built on react-native-video with:

• Optional playerKey gating / session init
• DRM config, watermark, theme color
• Delegate-style props for lifecycle events
• Ads tracking URL
• Secure mode on Android

React Native — Installation

Install the React Native BOSS Player SDK.

Requirements

npm install @goboss/react-native-video-player-sdk
npm install react-native-video react-native-safe-area-context react-native-svg lucide-react-native @react-native-community/slider
npx pod-install

Optional: react-native-google-cast, Firebase analytics packages.

React Native — Quick start

RNVideoPlayer and TVVideoPlayer usage.

import { RNVideoPlayer } from '@goboss/react-native-video-player-sdk';

export function PlayerScreen() {
  return (
    <RNVideoPlayer
      src="https://cdn.example.com/stream.m3u8"
      playerKey="YOUR_PLAYER_KEY"
      title="My Video"
      themeColor="#865fe3"
      watermark="SECURE VIEW"
      playerDidStartPlaying={({ startTime, autoplay }) => {}}
      playerDidEncounterPlaybackError={({ errorCode, message }) => {}}
    />
  );
}

import { Platform } from 'react-native';
import { RNVideoPlayer, TVVideoPlayer } from '@goboss/react-native-video-player-sdk';

export function PlayerScreen() {
  if (Platform.isTV) {
    return (
      <TVVideoPlayer
        src="https://cdn.example.com/stream.m3u8"
        playerKey="YOUR_PLAYER_KEY"
        themeColor="#865fe3"
      />
    );
  }
  return (
    <RNVideoPlayer
      src="https://cdn.example.com/stream.m3u8"
      playerKey="YOUR_PLAYER_KEY"
      themeColor="#865fe3"
    />
  );
}

With playerKey set, the SDK calls init against the BOSS Player API (x-player-key).

React Native — Configuration

Props for RNVideoPlayer and TVVideoPlayer.

Shared props

TVVideoPlayer differences

• No fullscreen / PiP delegates
• No thumbnails prop in the TV interface

Core options (PlayerSDKOptions)

videoRef, src, sessionId, autoplay, muted, chapters, keyMoments, subtitles, thumbnails, drm, analyticsCallback, watchProgressInterval, themeColor, watermark, urlTransformer, isLive, headers

DRM example

<RNVideoPlayer
  src={url}
  playerKey={key}
  drmConfig={{
    authToken: '…',
    widevineLicenseUrl: 'https://license.example.com/widevine',
    fairplayLicenseUrl: 'https://license.example.com/fairplay',
  }}
  enableSecureMode
/>

React Native — Features

React Native feature matrix.

React Native — Events

Delegate props and analytics events for React Native.

Delegate props

Object-arg style callbacks:

• Start / resume / pause / finish / dismiss
• Seek start / finish
• Time update
• Buffering
• Quality / subtitle / audio / speed
• Key moment
• Playback / network errors
• Mobile also: fullscreen + PiP

<RNVideoPlayer
  src="…"
  playerKey="…"
  playerDidStartPlaying={({ startTime, autoplay }) => {}}
  playerDidPause={() => {}}
  playerDidEncounterPlaybackError={({ errorCode, message }) => {
    console.error(errorCode, message);
  }}
/>

Analytics eventTypes

Similar to web, plus live/ad extras: live_edge_seek, live_stream_start, ad_break_start / end, ad_marker_error

React Native — Best practices

React Native SDK integration gotchas.

1. Install peer dependencies (react-native-video, safe-area, svg, slider) and run pod-install.
2. Pass playerKey for entitlement and sessions.
3. Use TVVideoPlayer on TV — don’t reuse mobile chrome on Leanback/tvOS RN builds.
4. Handle error delegate props in production.
5. Confirm autoplay/mute defaults against your package version (some UI defaults are internal).
6. Point API host to production when leaving the default dev environment.

React Native — Playback control

Controlling playback in React Native.

The public React components are primarily declarative. The underlying VideoPlayerSDK coordinator (over react-native-video) supports:

play, pause, seek, skipAd, setVolume, setMute, setPlaybackRate, setQuality, setAudioTrack, togglePictureInPicture, toggleFullscreen, plus getters and module accessors (analytics, keyMoments, chapters, subtitles, drm, casting, thumbnails).

React Native — Troubleshooting

React Native SDK troubleshooting.

Packages & versions

Published package identifiers for BOSS Player SDKs.

Always pin versions in production and confirm SPM release tag vs framework bundle version on iOS upgrades.

Platform matrix

Feature comparison across BOSS Player platforms.

Legend: ✅ supported · ❌ not applicable / not exposed · — limited / N/A · gated = requires entitlement