---
updatedAt: 2026-09-21T07:32:25.000Z
agentTools:
  projectIndex: https://docs.streamlayer.io/llms.txt
---

# tvOS Integration Skill

Integration conventions for the StreamLayer tvOS SDK that keep an AI agent's diff small and correct — where to initialize, the tvOS-specific createOverlay, delegate wiring, focus/remote, and ad breaks.

# StreamLayer tvOS SDK Integration

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

This page is the human-readable form of the `streamlayer-tvos-integration` agent
skill. Reference it from your AI agent alongside the `streamlayer-docs` MCP — see
[Integrate with an AI Agent](https://docs.streamlayer.io/docs/integrate-with-an-ai-agent).

> 📘 The tvOS SDK shares the iOS SDK
>
> tvOS ships in the same `StreamLayer` package as iOS. For anything not called out
> as tvOS-specific below, follow the [iOS Integration Guide](https://docs.streamlayer.io/docs/integration-guide-ios).

## Pick the package

* **`StreamLayer`** — the SDK, distributed as a dynamic framework via Swift
  Package Manager (`git@github.com:StreamLayer/sdk-ios.git`, product
  `StreamLayer`). Add the package, then `import StreamLayerSDKTVOS` (the tvOS
  module — **not** `StreamLayerSDK`).
* **Main UI element:** the StreamLayer Element, created with
  `StreamLayer.createOverlay(containerViewController:contentView:delegate:)` and
  rendered on top of your player.
* **Requirements:** Xcode 16+, Swift 6, tvOS 18+.

## Rules (do this)

1. **Initialize once at launch; create the overlay in the player screen.** Call
   `StreamLayer.initSDK(with: key)` exactly once at app launch (`AppDelegate`),
   then start your event with `StreamLayer.createSession(for: eventId)` after
   authentication completes. Build the
   Element in the view controller that owns the video — via
   `createOverlay(containerViewController:contentView:delegate:)`. Note the tvOS
   signature **differs from iOS**: you pass your **content view** (the video
   container) and a `StreamLayerTVOSDelegate`, not the iOS overlay-delegate set.
   * ❌ Copying the iOS `createOverlay(mainContainerViewController:overlayDelegate:…)` call shape.
   * ✅ `createOverlay(containerViewController: self, contentView: playerView, delegate: self)`.

2. **Implement `StreamLayerTVOSDelegate` for the player bridge.** It has three
   methods: `streamLayerDelegateUpdateDuckingState(_ enabled: Bool, fullyMuteHost: Bool)`
   — lower your player volume when `enabled` is `true` (to zero when
   `fullyMuteHost` is `true`) and **restore it when `false`**. It has a default
   implementation, so a one-argument version compiles but is never called; the
   required `streamLayerDelegateAdDidFinish(_ info: SLRAdInfo)` — resume playback
   when `info.isPausedAd` is `true`; and the optional
   `streamLayerDelegateAdDidStart(_ info: SLRAdInfo)`. Keep a strong owner of the
   delegate so callbacks keep firing.

3. **Let the SDK own focus and the remote.** On tvOS the SDK handles Apple TV
   remote navigation and the focus engine for its Element automatically. Don't
   fight it — don't trap focus, don't intercept remote presses meant for the
   overlay while it's active, and keep your own focus guides outside the Element's
   region. Restore your normal focus environment after the Element dismisses.

4. **Drive ad breaks and the stream timeline.** Call `StreamLayer.startADBreak()`
   / `StreamLayer.stopADBreak()` around your ad breaks, and
   `StreamLayer.setStreamTimelineEnabled(_:player:)` to feed stream time for
   spoiler-safe and timed units. For server-side ad insertion, set
   `StreamLayer.shared.ssaiHostDelegate` to react to `willBeginAdBreak` /
   `didFinishAdBreak`. Wire only what your app actually uses.

5. **Auth + credentials.** Authenticate once after init —
   `try await StreamLayer.setAnonymousAuth()`, then `createSession`. The tvOS
   module has no bypass-token call — don't copy the iOS
   `setAuthorizationBypass(token:schema:)` or `useAnonymousAuth()`. The SDK API
   Key is a **public, client-side** value from [StreamLayer Studio](https://studio.streamlayer.io/develop/)
   — a constant is fine; don't add `.env` scaffolding. User tokens are different:
   never hardcode them. Keep the diff minimal: fit
   the Element around your existing player screen instead of restructuring it.

## Gotchas

* **`createOverlay` signature is different from iOS.** tvOS takes `contentView` +
  `StreamLayerTVOSDelegate`; don't copy the iOS overlay-delegate call.
* **Wrong import.** Use `import StreamLayerSDKTVOS`, not `StreamLayerSDK`.
* **`initSDK` called twice traps** — it's a one-time call.
* **`createOverlay` before `initSDK` crashes.** It dereferences the SDK
  singleton, so a lazy overlay property touched before init brings the app down.
* **Left-ducked audio.** Always restore player volume when
  `streamLayerDelegateUpdateDuckingState` is called with `enabled == false`; forgetting to leaves the stream
  quiet after an ad or voice segment.
* **Focus traps.** The most common tvOS pitfall — don't override
  `preferredFocusEnvironments` in a way that steals focus from the active Element.
* **Shared SDK.** For dependencies, SDK API Key, and initialization mechanics not
  covered here, follow the [iOS Integration Guide](https://docs.streamlayer.io/docs/integration-guide-ios).
* Authoritative API details: the `streamlayer-docs` MCP (`search` / `fetch`) and
  the tvOS docs.

***

## Related

* [Integrate with an AI Agent](https://docs.streamlayer.io/docs/integrate-with-an-ai-agent) — Connect the MCP and prompt your agent to run this integration
* [tvOS Getting Started](https://docs.streamlayer.io/docs/streamlayer-tv-os-documentation) — tvOS setup, requirements, and installation
* [iOS Integration Guide](https://docs.streamlayer.io/docs/integration-guide-ios) — The shared SDK setup the tvOS SDK builds on
* [Pause Advertising](https://docs.streamlayer.io/docs/ad-break) — Display ads when the viewer pauses playback
* [Custom Paused Ads](https://docs.streamlayer.io/docs/custom-paused-ads) — Fullscreen and transparent pause ads with VAST