StreamLayer Web/TV SDK Integration

How to wire StreamLayer into an existing React app cleanly. Follow the rules —
they prevent the common over-integration mistakes.

This page is the human-readable form of the streamlayer-web-integration agent
skill. Reference it from your AI agent alongside the streamlayer-docs MCP — see
Integrate with an AI Agent.

Pick the package

• @streamlayer/web-os — TV platforms (LG webOS, Samsung Tizen, Hisense
  VIDAA, Xbox). Main UI element: StreamLayerSDKTv (wraps the video, handles
  remote / spatial navigation).
• @streamlayer/react — browser web apps. Main UI element:
  StreamLayerSDKReact (sidebar-style interactive unit).

Same provider model for both: StreamLayerProvider (needs sdkKey, optional
event) + a stylesheet import.

Rules (do this)

1. Provider high, UI low. Put StreamLayerProvider in the parent that
   renders the player (e.g. App), wrapping only the player subtree — not
   the whole app, and not inside the player component itself. That gives the
   provider a stable mount point and keeps the player component free of SDK
   boilerplate. Keep the SDK UI elements (StreamLayerSDKReact,
   StreamLayerPauseAd, StreamLayerSDKTv) inside the player component,
   right next to the <video> — they almost always need the player instance and
   its play/pause/mute state and controls, which live there. Your own player
   hooks (useVideoJs, etc.) stay in that component too.

   • ❌ Provider around <App>; ❌ provider inside the player component.
   • ✅ Provider in the parent around <VideoPlayer>; UI elements inside
     <VideoPlayer>, next to the video.

2. Memoise every prop you hand to an SDK component. Wrap all callbacks
   (videoPlayerController, onRenderPauseAd, onClosePauseAd, …) in
   useCallback, and give every object/array prop (pauseAdExternalUrls,
   options) a stable reference — useMemo, or a module-level constant when
   it's fully static. The SDK registers handlers by identity (e.g.
   addVideoPlayerController) and re-fetches / re-subscribes whenever a
   reference changes; fresh inline () => {} or [{…}] on every render causes
   dropped subscriptions, refetch loops, and flicker.

3. Minimal diff. Drop the provider and SDK UI element straight into the
   existing markup — the UI element wraps the existing video element as its
   child, and that's the only structural change. Don't add helper wrapper
   <div>s or components, don't re-indent or reorganize unrelated JSX, don't
   create config/abstraction layers the task didn't ask for, and don't leave
   console.log / debug code behind.

4. Wire the callbacks the feature needs; comment the rest. Attach every
   relevant callback (memoised — rule 2). Wire the ones the feature actually
   needs (showPauseAd from your pause state, videoPlayerController → your
   player, onRenderPauseAd → hide your controls); for the rest leave a
   // TODO: comment saying what to implement. Prefix unused params with _
   to satisfy noUnusedParameters.

5. Keep credentials simple. The SDK key is a public, client-side value —
   it ships in the bundle. A few hardcoded constants (or a tiny config module)
   are fine for a demo. Don't add .env scaffolding, typed ImportMetaEnv, or
   dev-only warnings unless the project actually asks for env-based config.

Gotchas

• HttpStatusError: invalid SDK key in the console with a placeholder key is
  expected and non-fatal — the app still renders, and the SDK UI just renders
  your children (no overlay) until a real key initializes it.
• The SDK bundle is large; Vite will warn about chunk size. That's fine.
• Unstable props = churn. Flicker, refetch loops, or a pause ad that
  re-mounts on every render almost always mean a non-memoised callback/array
  prop (rule 2).
• Authoritative API details: the streamlayer-docs MCP (search / fetch) and,
  for exact type shapes, the package type definitions.

Related

• Integrate with an AI Agent — Connect the MCP and prompt your agent to run this integration
• Exposed Pause Ad — Full Pause Ad feature guide and options
• Integration Guide — Complete Web SDK setup and configuration