BranchVideo Player SDK

branch-video-player-sdk embeds a static BranchVideo Runtime in an iframe.

import { createBranchVideoPlayer } from 'branch-video-player-sdk'

const player = createBranchVideoPlayer({
  container: '#player',
  runtimeUrl: 'https://player.example.com/player.html',
  scriptUrl: 'https://cdn.example.com/release/script.json',
})
player.on('ended', (result) => saveProgress(result))

The ESM entry is branch-video-player-sdk; the UMD build exposes BranchVideoPlayerSDK. For a WeChat web-view or another non-DOM host, import the pure URL entry instead:

import { buildBranchVideoPlayerUrl } from 'branch-video-player-sdk/url'

const src = buildBranchVideoPlayerUrl({
  runtimeUrl: 'https://player.example.com/player.html',
  scriptUrl: 'https://cdn.example.com/release/script.json',
})

runtimeUrl and scriptUrl must be absolute HTTP(S) URLs. The script CDN must allow the Runtime origin with CORS. parentOrigin, when provided, must be an HTTP(S) origin only (no path, query, or fragment).

Default Runtime builds are Service Worker off and may be deployed below a versioned subpath. The explicit SW-on Runtime requires /player.html and /sw.js at the root of a dedicated origin; do not deploy multiple SW-on builds under paths on one origin.

Subscribe with player.on() to loaded, ready, statechange, progress, ended, error, bufferchange, milestone, and exitrequested. play, pause, and seek issued before trusted ready are queued in order.

Runtime size and boot overlay (0.2.15+)

Until 0.2.14 the Runtime bundle assets/player-*.js weighed 10.8 MB because theme artwork (about 9 MB of base64 PNG/SVG) was inlined into the JavaScript. On a 250 KB/s connection the first frame stayed on a fake "0% 0B / 0B" for more than 40 seconds before script.json was even requested.

• Images larger than 4 KB are now emitted as assets/img-<hash>.<ext> and referenced relative to player.html, which keeps working for every host layout (npm package, H5 copy, static image) because player.html and assets/ are always siblings. The bundle is about 1.2 MB (365 KB gzip).
• player.html no longer shows a fake percentage before the module runs. It says the player itself is loading, counts the seconds, warns after 15 s and offers a retry after 60 s. The React overlay with real resource progress takes over as before.
• The runtime build fails if any JS/CSS still contains an inlined image over 4 KB or if total JS exceeds 3 MB (scripts/validate-runtime-artifacts.mjs).

Hosts should serve assets/** with long-lived immutable caching and gzip; the file names are content-hashed.

Web learning observations (0.2.10+)

The Runtime can report privacy-minimized Web learning observations through the existing milestone event. These observations are included in 0.2.10 and later; 0.2.9 does not contain them. No new SDK event name is required.

• schemaVersion: 1
• type: web_step_visible | web_step_message
• nodeId, visitId, contentUrl (origin + pathname only)
• Status messages additionally contain messageName and messageStatus.

Visibility is observed after the Runtime's existing Web visual handoff, not simply on node change. Status messages reuse the current origin/source fence and visit deduplication. Source-less legacy calls may still route for compatibility but are never telemetry. Initial UEStatus=0 and free-text payloads are excluded. Observer exceptions cannot stop playback or alter routing.

A status observation is not a success verdict. The host must apply an explicit content-specific completion contract; it must not assume the same numeric UEStatus means completed, skipped or timed out for every page. No answer bodies, initData or credential query values are forwarded.