Integration Guide

Architecture Overview

Please make sure you are familiar with the Architecture Overview before proceeding with this integration.

System Requirements

Android Studio 4.0 or later
Target SDK version 33 or later
Minimum SDK version 23
Kotlin or Java

If your system does not meet these requirements, contact the development team to verify compatibility. If your app cannot host the SDK, the team can evaluate building a version that meets your needs. Code samples in this documentation use Kotlin.

SDK API Key

An SDK API key is required to integrate StreamLayer into your application. You can find and manage this key in the Development section of your StreamLayer Studio organization.

If you do not already have an organization in Studio, provide your email address to the StreamLayer team. This information is used to create a new organization for you on the platform and set up a personal dashboard. You will receive an email invitation with a link to StreamLayer Studio and authentication credentials. After accessing Studio, navigate to the development page in Studio to generate your SDK API key.

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

Installation

The SDK is available through a public Maven repository. Add the following dependency to your module-level build.gradle file:

dependencies {
   implementation "io.streamlayer:androidsdk:<insert latest version>"
}

Find the latest version here.

Add the following repository configuration to your project-level build.gradle file:

allprojects {
    repositories {
        ...
        mavenCentral() // add this line
        maven { url "https://jitpack.io" } // add this line
    }
}

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

Host apps can useStreamLayerFragmentby initializing it as follows:

io.streamlayer.sdk.main.StreamLayerFragment

You must initialize the StreamLayer SDK with the SDK key before using StreamLayerFragment. Using it without initialization causes the app to crash because the SDK component builder depends on the Context object.

Overlay formats (Overlay, Side Bar, L-Bar, PIP, SBS, Frame) are defined and rendered by the SDK inside the StreamLayerFragment. The host app is responsible for placing the fragment in the layout and resizing the video player where needed. The ad units and interactive elements that appear within those formats are configured in StreamLayer Studio.

SDK Initialization

Initialize the SDK before using StreamLayerFragment. Use StreamLayer.initializeApp() in your Application class when the app launches. Provide the application context and SDK key from StreamLayer Studio here.

Responsibility reminder: The host app defines where the overlay container lives in the layout, the SDK renders overlay content inside that container, and StreamLayer Studio controls what ad units or interactive features appear.

import io.streamlayer.sdk.StreamLayer


override fun onCreate() {
    super.onCreate()
        
    // initialize the StreamLayer SDK with SDK key
    StreamLayer.initializeApp(this, {SDK_KEY})
}

Integrating the SDK Overlay

StreamLayerFragment includes all of the features of the StreamLayer SDK. Use the same android:tag=StreamLayerFragment for all SDK fragment versions. UseFragmentContainerViewto insert the fragment. For example, in activity_player.xml:

<androidx.constraintlayout.widget.ConstraintLayout
    android:layout_width="match_parent"
    android:layout_height="match_parent">
  
    <!-- this is your custom video player positioned at the top of the screen -->
    <com.host.app.PlayerView
        android:id="@+id/playerView"
        android:layout_width="match_parent"
        android:layout_height="210dp"
        app:layout_constraintLeft_toLeftOf="parent"
        app:layout_constraintRight_toRightOf="parent"
        app:layout_constraintTop_toTopOf="parent" />
                                                   
    <androidx.fragment.app.FragmentContainerView
        android:id="@+id/streamLayerFragment"
        android:name="io.streamlayer.sdk.main.StreamLayerFragment"
        android:layout_width="match_parent"
        android:layout_height="0dp"
        android:tag="StreamLayerFragment"
        app:layout_constraintBottom_toBottomOf="parent"
        app:layout_constraintTop_toTopOf="@id/playerView" />
  
</androidx.constraintlayout.widget.ConstraintLayout>

For details on layout setup, including portrait and landscape orientation, see the Layout Guide.

Communicating with the SDK

To ensure correct overlay behavior (e.g., statistics, odds), notify the SDK when the selected event stream changes in the host app. UseStreamLayer.createEventSession() whenever the user switches event streams.

For example, in Activity, when a user changes the video stream event, notify the SDK with the Event ID so it initializes specific overlays and data for that specific event.

import io.streamlayer.sdk.StreamLayer


private fun onStreamSelected(event: StreamingEvent) {
        // notify the SDK about the video stream change
        anyCoroutineScope.launch {
            try {
                val eventSession = StreamLayer.createEventSession(event.id, null)
            } catch (t: Throwable) {
                Log.e(TAG, "createEventSession failed:", t)
            }
        }
}

This is a Kotlin suspend function and can be called from any CoroutineScope.

The SDK can also request the host app to change the stream. For example, when joining a Watch Party, participants may be watching different streams. In your Activity, implement SLRAppHost.Delegate to respond to stream change requests:

private val appHostDelegate = object : SLRAppHost.Delegate {
   // other functions
   override fun requestStream(id: String) {
        // play other Event by id
   }
}

Additional Integration

The basic setup is now complete. For additional functionality, review the following guides.

Audio Management

When a user is in a Watch Party call, the host app should lower stream playback volume (audio ducking). See the Audio Management Guide for implementation details.

Push Notifications with Deep Linking

The SDK supports push notifications using Firebase Messaging Service. See the Push Notifications Guide for setup instructions. Then review the Deep Linking Guide to enable deep linking into the StreamLayer overlay.