Migration Guide

This guide covers upgrading the StreamLayer Android SDK to the latest 2.x release. Apply the changes for every version you cross between your current version and the target version.

For the full list of changes per release, see the Changelog. For a clean setup reference, see the Integration Guide.

Before you upgrade

Bump the dependency to the latest version from Maven Central, then run ./gradlew clean build to surface deprecation warnings and unresolved symbols.
dependencies {
    implementation "io.streamlayer:androidsdk:<latest version>"
}

Behavioral changes that won't show in a code diff

These do not produce compiler errors, so verify them manually after upgrading.

Change	Impact	What to do
Forced re-authentication on upgrade	The SDK performs an internal logout once when you move to a newer major SDK runtime. Users are signed out of the StreamLayer session and local SDK data is cleared on first launch after the update.	Expect users to be unauthenticated on first launch. Re-run your authentication flow (`useAnonymousAuth()` or `authorizationBypass()`). No host data is affected.
Anonymous auth by default	Newer releases authenticate anonymously by default so interactive units work without an explicit sign-in.	If you relied on the SDK staying unauthenticated, gate features on `isUserAuthorized()` / `userIsAuthorizedState()`.

Deprecated APIs

`setGamificationOptions(Boolean, Boolean)` → `GameOptions`

The two-argument setGamificationOptions is deprecated in favor of the GameOptions data class, which also exposes onboarding controls.

Before:

StreamLayer.setGamificationOptions(
    isGlobalLeaderboardEnabled = false,
    isInvitesEnabled = false
)

After:

StreamLayer.setGamificationOptions(
    StreamLayer.GameOptions(
        isGlobalLeaderboardEnabled = false,
        isInvitesEnabled = false,
        isOnboardingEnabled = true,
        showGamificationNotificationOnboarding = true
    )
)

GameOptions defaults: isGlobalLeaderboardEnabled = false, isInvitesEnabled = true, isOnboardingEnabled = true, showGamificationNotificationOnboarding = true.

New APIs

You don't need these to compile, but adopt them to stay current.

API	Since	Purpose
`StreamLayer.GameOptions`	2.16.0	Replaces the deprecated `setGamificationOptions(Boolean, Boolean)`.
`StreamLayer.initializeApp(context, sdkKey, config)`	2.x	Pass a `Configuration` (for example `subscribeToRemoteAd`) at init time.
Pause ad unit prefetch	2.19.0	Preloads pause ad creatives for faster display. Enabled via Studio configuration; no host code change required.

Media playback module

If you use the StreamLayer Media3 player integration (recommended for Android TV), add the media3 module alongside the core SDK and initialize it after initializeApp():

dependencies {
    implementation "io.streamlayer:androidsdk:<latest version>"
    implementation "io.streamlayer:android-media3:<latest version>"
}

override fun onCreate() {
    super.onCreate()
    StreamLayer.initializeApp(this, BuildConfig.SL_SDK_KEY)
    StreamLayerMedia3Player.initSdk(this)
}

Keep the media3 module version aligned with the core androidsdk version.

Existing-client database migration

If you are upgrading an app that already shipped with an older StreamLayer SDK and need the full local database migration to run, set the flag before calling initializeApp():

StreamLayer.executeFullDbMigration = true
StreamLayer.initializeApp(this, BuildConfig.SL_SDK_KEY)

New integrations do not need this flag.

Post-upgrade checklist

Dependency updated to the target version; ./gradlew clean build passes.
setGamificationOptions migrated to GameOptions.
ProGuard/R8 keep rules still apply on a release build (see Troubleshooting).
Authentication flow re-runs cleanly after the forced logout.
StreamLayer Element renders and createEventSession() succeeds for a test event.

Changelog — Full per-version change history
Integration Guide — Full Android SDK setup and configuration
Error Reference — SDK error codes, causes, and fixes