Integration Guide

System Requirements

• Xcode 16.0 or higher
• Swift 6 or highter
• 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 will need an SDK API Key in order to successfully integrate StreamLayer into your application. If you do not already have one, please follow the instructions below to obtain one.

Provide us with your email, we will use this to create a new organization for you on our platform, including setting up a personal dashboard for your account. You will then receive an invitation email with a link to the admin panel and the credentials for authentication. After receiving access to the admin panel, you will be able to generate an API key in the development section of the admin panel. This API authenticates your application with our servers and is required for all interactions.

Installation

Swift Package Manager

The StreamLayer SDK is distributed as a dynamic framework. You can integrate the SDK with the SPM (Swift Package Manager).

1. In Xcode go to File -> Add Package
2. Search by entering package url "[email protected]:StreamLayer/sdk-ios.git"
3. Dependency Rule: Up to Next Major Version.

If you use CocoaPods as a dependency manager

We don't distribute StreamLayer SDK as CocoaPods library but you're able to integrate SDK as SPM dependency in your .xcworkspace.

1. Open your .xcworkspace
2. Go your Project Settings -> Package Dependencies
3. Press + button
4. Put https://github.com/StreamLayer/sdk-ios.git into Search Field
5. Dependency Rule: Up to Next Minor Version]
6. Press Add

You can find our example of CocoaPods + SPM integration here

Current version: v8.22.169

Integration

Basic Terminology

• Host App: The app that integrates the SDK. The host app controls the video player’s size and position, and decides where theStreamLayerFragment(the SDK overlay container) is placed in the layout. For example, the host app may resize the video player to make room for a Side Bar or L-Bar, or position the overlay container below the video player in portrait mode.
• Overlay: An interactive container rendered by the SDK within the host app. Overlays are the core system used for all interactive and advertising formats. Once the host app places the container, the SDK manages and renders overlay content. Formats include:
  • Full-Screen Overlay: Semi-transparent container positioned over the main video in portrait or landscape orientation.
  • Side Bar: A vertical container positioned to one side of the video when the video player is reduced in size.
  • L-Bar: A vertical container plus an optional horizontal banner that wraps around the video, forming an “L” shape.
  • Picture-in-Picture (PIP): A format where the main video is reduced to a smaller window while the overlay occupies the primary view.
  • Side-by-Side (SBS): A format where the screen is split between content and the overlay, with ad audio typically taking priority.
  • Frame Ad: A format where the main video player is reduced slightly and surrounded by a branded overlay frame.
• Overlay Button: A button displayed on top of the interface that opens the StreamLayer menu.
• Overlay Menu: An expandable menu displaying all available overlays, ad formats, and Side Bar / L-Bar containers.
• Overlay Wrapper View: The host app–provided view that contains the SDK view hierarchy for any overlay format.

Selecting the Overlay Button opens the Overlay Menu. Selecting a menu item activates the corresponding overlay format. All overlay formats are rendered inside the Overlay Wrapper View provided by the host app.

Responsibilities: • Host App: Controls the video player size/position and placement of the overlay container (StreamLayerFragment) within the app layout. • SDK: Defines overlay formats and renders/manages their content inside the host-defined container. • StreamLayer Studio: Selects and configures the ad units or interactive elements that appear inside SDK-rendered overlays, based on the formats enabled in the SDK and host app.

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

Introduction

The framework provides an overlay which is rendered on top of the host application interface. In order to activate the overlay, we have to initialise it with our SDK key during the creation of the overlay (you will see a sample call of the method below). Because the interactive experience StreamLayer provides is tightly coupled with the video playback and interacts with the audio session, some delegate methods have to be implemented to set up communication between the SDK and the host app.

SDK configuration

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

UI Configuration

Base example

The main feature of the SDK is the overlay, implemented as a UIViewController. This view controller must be embedded into your app's view hierarchy.

Sidebar Support

The Sidebar displays selected overlays in a compact view during horizontal orientation. If StreamLayer.config.overlayMode = .sidebar, overlay will call SLRSideBarDelegate, for a signal actiovation animation for appearing the sidebar. StreamLayer.config.overlayMode = .overlay, overlays will appear in their default modal form.

Reference view mode

Use Reference View Mode to anchor overlays within a specific view or scrollable content.

Show overlay without menu

You can display specific overlays without showing the full SDK menu (without Overlay Menu and Overlay Button).

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 if you need the feature they implement.

Watch Party Plugin

To integrate the Watch Party plugin:

– Install latest version of the StreamLayer Plugins package.

– Add StreamLayerSDKWatchParty and StreamLayerSDKPluginsWatchParty to your project's Frameworks, Libraries and Embedded Content section.

– Register the plugin before configuring the SDK:

import StreamLayerSDKPluginsWatchParty

class ViewController: UIViewController {

    ...

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

    ...

    private func configureSLWatchPartyPlugin() {
        let plugin = SLRWatchPartyPlugin()
        StreamLayer.registerWatchPartyPlugin(plugin)
    }
}

Google Ads Manager Plugin

To integrate the Google Ads Manager plugin:

– Install latest version of the StreamLayer Plugins package.

– Add StreamLayerSDKGooglePAL and StreamLayerSDKPluginsGooglePAL to your project's Frameworks, Libraries and Embedded Content section.

– 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)
    }
}

SDK Configuration Options

StreamLayer.config general

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

StreamLayer.config Games

StreamLayer.config Watch Party

SDK Overlay Delegate

The host application may implement delegate methods based on its specific integration requirements. All methods are optional, and only those relevant to the selected features need to be used.

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

  /// Inform the host app to display a custom view of the Return WP badge.
  func onReturnToWP(isActive: Bool)

  /// 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

Below are common issues that may arise during SDK integration, along with recommended solutions:

Overlay 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 the StreamLayer Studio.

Delegate Methods Not Firing

Verify that all necessary delegates are assigned correctly during SDK initialization or when creating overlays.

For further support, please refer to StreamLayer Support.

Resources and Examples

For implementation references, code samples, and additional examples, visit:

• Example code
• StreamLayer GitHub Repository