Integration Guide

Before you begin, review the Architecture Overview to understand how the SDK, host app, and StreamLayer Studio work together.

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

Core Concepts

StreamLayer's SDK architecture has three layers. Understanding these layers helps you integrate and configure the SDK correctly.

Host App: The app that integrates the SDK. The host app controls the video player's size and position and decides where StreamLayerFragment (the StreamLayer Element container) is placed in the layout. For example, the host app may resize the video player to make room for a sidebar or L-bar, or position the StreamLayer Element below the video player in portrait mode.
StreamLayer Element: The interactive UI surface rendered by the SDK within the host app. The StreamLayer Element is the core system used for all interactive and advertising units. Once the host app places the container, the SDK manages and renders content inside it. The StreamLayer Element supports multiple formats:
- StreamLayer Element: A semi-transparent layer positioned over the main video in portrait or landscape orientation.
- Sidebar: A vertical panel positioned to one side of the video when the video player is reduced in size.
- L-Bar: A vertical panel 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 StreamLayer Element occupies the primary view.
- Side-by-Side (SBS): A format where the screen is split between content and the StreamLayer Element, with ad audio typically taking priority.
- Frame Ad: A format where the main video player is reduced slightly and surrounded by a branded frame.
Launch Button: A button displayed on the interface that opens the StreamLayer menu.
StreamLayer Menu: An expandable menu displaying all available units, ad formats, and sidebar / L-bar containers.
Element Container: The host app-provided view that contains the SDK view hierarchy for any format.

Selecting the Launch Button opens the StreamLayer Menu. Selecting a menu item activates the corresponding format. All formats are rendered inside the Element Container provided by the host app.

Responsibilities:

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

Note: The format (e.g., overlay, L-bar, sidebar, PIP, side-by-side, frame) is configured in the SDK/host app. The ad units and interactive units displayed within those formats are created and managed in StreamLayer Studio.

Getting Started

Host apps use StreamLayerFragment to render the StreamLayer Element. Initialize it as follows:

io.streamlayer.sdk.main.StreamLayerFragment

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

The StreamLayer Element formats (overlay, sidebar, 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 units 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 API Key from StreamLayer Studio here.

Responsibility reminder: The host app defines where the StreamLayer Element container lives in the layout, the SDK renders content inside that container, and StreamLayer Studio controls what ad units or interactive units 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 StreamLayer Element

StreamLayerFragment includes all of the features of the StreamLayer SDK. Use the same android:tag=StreamLayerFragment for all SDK fragment versions. Use FragmentContainerView to 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 StreamLayer Element behavior (e.g., stats, odds), notify the SDK when the selected event stream changes in the host app. Use StreamLayer.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 units 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. 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

The host app should implement audio ducking to lower stream playback volume during calls. 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 route users directly to the StreamLayer Element.

Layout Guide — Portrait and landscape layout configuration
Sample Integrations — Demo app with full integration example
Features Integration — Google PAL and authentication modules
UI Options Guide — Comprehensive SLRAppHost configuration reference