Integration Guide
Step-by-step guide to integrating the StreamLayer Android SDK. Covers installation via Maven, SDK API Key setup, StreamLayer Element placement, event sessions, audio management, and push notifications.
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.StreamLayerFragmentYou 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.
Related
- 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
SLRAppHostconfiguration reference
Updated 15 days ago
