Integration Guide

System Requirements

• Xcode 16.0 or higher
• Swift 6 or higher
• iOS 15+

If you use other versions of Swift, contact support and we can add it to our continuous delivery pipeline.

SDK API Key

You need an SDK API Key to integrate StreamLayer into your application. If you do not already have one, follow these steps:

1. Provide your email to StreamLayer — we will create an organization for you on our platform and set up a personal dashboard.
2. You will receive an invitation email with a link to StreamLayer Studio and your authentication credentials.
3. After logging in, generate an API key in the development section of StreamLayer Studio.

This key authenticates your application with StreamLayer servers and is required for all SDK interactions.

Installation

Swift Package Manager

The StreamLayer SDK is distributed as a dynamic framework. Integrate it using Swift Package Manager (SPM):

1. In Xcode, go to File > Add Package.
2. Enter the package URL: [email protected]:StreamLayer/sdk-ios.git
3. Set the Dependency Rule to Up to Next Major Version.

CocoaPods Workaround

StreamLayer SDK is not distributed as a CocoaPods library, but you can add it as an SPM dependency alongside your existing CocoaPods setup:

1. Open your .xcworkspace.
2. Go to Project Settings > Package Dependencies.
3. Press the + button.
4. Enter https://github.com/StreamLayer/sdk-ios.git in the search field.
5. Set the Dependency Rule to Up to Next Minor Version.
6. Press Add.

See the CocoaPods + SPM example project for reference.

Current version: v8.22.169

Core Concepts

Before integrating, familiarize yourself with the key terminology:

• Host App — Your application that integrates the StreamLayer SDK. The host app controls the video player size and position and decides where the StreamLayer Element is placed in the view hierarchy.
• StreamLayer Element — The interactive UI surface managed by the SDK within your app. On iOS, this is implemented via SLROverlayViewController or SLRWidgetsViewController. Formats include:
  • Full-Screen StreamLayer Element — Semi-transparent container positioned over the video in portrait or landscape.
  • Side Bar — Vertical container positioned beside a resized video player.
  • L-Bar — Vertical container plus an optional horizontal banner wrapping around the video in an "L" shape.
  • Picture-in-Picture (PIP) — Video shrinks to a smaller window while the StreamLayer Element occupies the main view.
  • Side-by-Side (SBS) — Screen split between video content and the StreamLayer Element.
  • Frame Ad — Video player reduced slightly and surrounded by a branded frame.
• Launch Button — A button displayed over the interface that opens the StreamLayer menu.
• StreamLayer Menu — An expandable menu displaying all available interactive units, ad formats, and layout options.
• Units — Individual content modules displayed inside the StreamLayer Element: ad units, poll units, prediction units, trivia units, stat units, and more.

Responsibilities:

• Host App — Controls video player size/position and placement of the StreamLayer Element within the app layout.
• SDK — Defines formats and renders/manages units inside the host-provided container.
• StreamLayer Studio — Selects and configures the units that appear inside the StreamLayer Element based on the formats enabled in the SDK and host app.

Note: The format (Overlay, L-Bar, Side Bar, PIP, etc.) is configured in the SDK/host app. The units displayed within those formats are created and managed in StreamLayer Studio.

SDK Configuration

For a complete reference of all available configuration options, see the iOS SDK Configuration documentation.

UI Configuration

Base Example

The core of the SDK is the StreamLayer Element, implemented as a UIViewController. This view controller must be embedded into your app's view hierarchy.

Sidebar Support

The sidebar displays the StreamLayer Element in a compact view during horizontal orientation. Set StreamLayer.config.overlayMode = .sidebar to have the SDK call SLRSideBarDelegate for sidebar activation animations. With .overlay mode (default), the StreamLayer Element appears in its standard modal form.

Reference View Mode

Use Reference View Mode to anchor the StreamLayer Element within a specific view or scrollable content area.

Show StreamLayer Element Without Menu

You can display specific units without showing the full SDK menu (bypassing the Launch Button and StreamLayer Menu):

class ViewController: UIViewController {

    ...

    private lazy var showOverlayButton: UIButton = {
        let button = UIButton()
        button.setTitle("Show overlay", for: .normal)
        button.addTarget(self, action: #selector(showOverlayAction), for: .touchUpInside)
        button.translatesAutoresizingMaskIntoConstraints = false
        return button
    }()

    private func setup() {
        // Disable controlls and add showOverlayButton
        widgetsViewController.hideControls = true
        ...
    }

    @objc
    private func showOverlayAction() {
        do {
            try StreamLayer.showOverlay(
                overlayType: .games,
                mainContainerViewController: self,
                overlayDataSource: self,
                lbarDelegate: self,
                dataOptions: ["eventId": ""]
            )
        } catch {
            // handle error
        }
  }

    ...

}

Plugins

Plugins are optional — install only the ones you need.

Google Ads Manager Plugin

To integrate the Google Ads Manager plugin:

1. Install the latest version of the StreamLayer Plugins package.
2. Add StreamLayerSDKGooglePAL and StreamLayerSDKPluginsGooglePAL to your project's Frameworks, Libraries and Embedded Content section.
3. Register the plugin before configuring the SDK:

import StreamLayerSDKPluginsGooglePAL

class ViewController: UIViewController {

    ...

    override func viewDidLoad() {
        super.viewDidLoad()
        configureSLGooglePALPlugin()
    }

    ...

    private func configureSLGooglePALPlugin() {
        let plugin = SLRGooglePALPlugin()
        StreamLayer.registerPALPlugin(plugin)
    }
}

Configuration Options

General Configuration

The following table summarizes core configuration properties supported by the StreamLayer SDK.

Games Configuration

SLROverlayDelegate

The host application may implement delegate methods based on its specific integration requirements. All methods are optional — only implement those relevant to the features you use.

extension ViewController: SLROverlayDelegate {
  /// Invoked to initiate audio-ducking. Expected behaviour is to reduce output volume of the
  /// video player to enable comfortable voice call environment
  func requestAudioDucking(_ mute: Bool)

  /// Invoked to signal that audio ducking is not required. Expected behaviour is to restore volume levels
  /// to where they were at the time of ducking request
  func disableAudioDucking()

  /// Requests host-app to configure shared audio session for
  /// a specific activity. We support voice calls & audio notifications
  /// Each time before audio session is used this method would be called to
  /// notify host application about the need to setup appropriate audio session
  /// When an existing audio session is already active - it must be a noop
  ///
  /// - Parameter type: requested session type
  func prepareAudioSession(for type: StreamLayerSDK.SLRAudioSessionType)

  /// When StreamLayer is done playing audio or recording voice this method
  /// would be invoked to provide a hint for the app to change current audio session
  /// settings
  /// - Parameter type: requested session type
  func disableAudioSession(for type: StreamLayerSDK.SLRAudioSessionType)

  /// This method must return custom text for a share message that is used
  /// to invite other people to use the app
  func shareInviteMessage() -> String

  /// Used when pinging your friends from who is watching quick access menu
  func waveMessage() -> String

  /// User requested to switch video stream through StreamLayer SDK interface
  /// You are required to react to it by changing video feed
  func switchStream(to streamId: String)

  /// Pause the stream video
  func pauseVideo(_ userInitiated: Bool)

  /// Play the stream video
  func playVideo(_ userInitiated: Bool)

  /// Callback when volume changed not from user interaction
  var onPlayerVolumeChange: (() -> Void)? { get set }

  /// Change video player volume in range from 0.0 to 1.0.
  /// Note that volume of a video player is a value relative to general audio output.
  func setPlayerVolume(_ volume: Float)

  /// Video player volume in range from 0.0 to 1.0.
  func getPlayerVolume() -> Float

  /// It takes an SLRActionClicked parameter and returns a boolean value.
  /// - Parameters:
  ///   - action: An SLRActionClicked object representing the action that was clicked.
  /// - Returns: A boolean value indicating whether the action was handled successfully.
  @MainActor func handleActionClicked(_ action: StreamLayerSDK.SLRActionClicked) async -> Bool

  /// It takes an SLRActionShown parameter and does not return a value.
  /// - Parameter action: An SLRActionShown object representing the action that was shown.
  func handleActionShown(_ action: StreamLayerSDK.SLRActionShown)
}

Troubleshooting

StreamLayer Element Not Displaying

Ensure StreamLayer.setNeedsLayout() is invoked after view layout changes, including during rotation or view hierarchy updates.

Authorization Failures

Confirm that your authorization bypass token and schema are correctly set and match the values issued by your backend or configured in StreamLayer Studio.

Delegate Methods Not Firing

Verify that all necessary delegates are assigned correctly during SDK initialization or when creating the StreamLayer Element.

For further support, visit StreamLayer Support.

Resources

• Example code
• StreamLayer GitHub Repository

Related

• Getting Started — Platform overview and quick-start path
• Test Integration: Advertising — Minimal working example for ads
• Configuration Guide — SDK configuration options and features