Skip to content

Quickstart Guide#

This is a developers' guide for setting up Storyteller for native Android apps. This guide will cover the basic technical steps for initializing the Storyteller SDK, authenticating a user, and adding a StorytellerStoriesRowView to your app.

Resources#

Showcase examples#

How to Add the SDK to Your Project#

Before you can add the Android SDK to your app, you will need to obtain an API Key. This is a secret key used to authenticate the SDK in your app. Throughout this document it will be marked as [APIKEY].

SDK Dependencies#

Choosing the SDK release line#

Android SDK 11.7.0 and 12.0.0 are separate release lines. SDK 12.0.0 follows 11.7.0 as a separate release for applications using Kotlin 2.1 or later and the newer Compose dependency line.

Release line Kotlin and Compose baseline Minimum Android version for the core SDK
11.7.0 Retains Kotlin 1.9 and Compose BOM 2024.12.01 Android 5.0 / API 21
12.0.0 Kotlin 2.1+ and Compose BOM 2026.06.01 Android 6.0 / API 23

Use 11.7.0 while your application remains on the existing dependency line. When adopting 12.0.0, update your application's Kotlin/Compose setup and minimum Android version together. Keep the core SDK and every optional Storyteller module on the same exact version; do not mix 11.7.0 and 12.0.0 artifacts.

Ad modules have additional requirements: ads24 requires Kotlin 2.1+ and API 23 even on the 11.x line, and adsnextgen requires API 24. See Choosing an Ad Module before selecting an ads integration.

Maven repository#

The Android SDK is published to Maven Central under the com.getstoryteller Maven group. New integrations must use Maven Central and must not add either legacy Storyteller Maven repository: CloudRepo or MyGet.

Migration notice: CloudRepo and MyGet, along with the legacy Storyteller:* coordinates they serve, are deprecated. Both repositories will be sunset with the SDK 12.0.0 release. Existing integrations can use them temporarily while migrating, but must move to Maven Central before upgrading to 12.0.0.

If you also use Google Ads, select exactly one of the version-aligned ads, ads24, or adsnextgen products. For true Clips IMA pre-roll, the optional version-aligned ads-ima artifact can be added alongside any one of those products and requires no separate host IMA dependency. See Choosing an Ad Module for Android, Kotlin, Google SDK, and migration requirements.

R8 / ProGuard#

If your app uses R8, the rules are added automatically.

SDK Installation#

The Android SDK can be included in your project using Gradle. It is recommended to use Android Studio. If you are having problems with configuring your build, check out the Android Studio guide or Gradle guides.

  1. Make sure Maven Central is available in the Project build.gradle file (MyAwesomeApp/build.gradle), under the allprojects section

Note: make sure it is added to allprojects, and not buildscript

      ...
      allprojects {
         repositories {
            google()
            mavenCentral()
        }
      }
  1. Modify the app Module build.gradle file (MyAwesomeApp/app/build.gradle)
        ...
        dependencies {
            def storyteller_version = "<storyteller-version>"

            implementation(group: "com.getstoryteller", name: "sdk", version: "$storyteller_version")
        }

  1. Sync your project with Gradle files

  2. Android Studio

Gradle Sync

Migrating from the Legacy Storyteller Repository#

Older integrations may resolve Storyteller from either CloudRepo or MyGet. Maven Central coordinates are available from SDK 11.5.1, and both legacy repositories will be sunset with the SDK 12.0.0 release. To migrate an existing integration:

  1. Upgrade every Storyteller dependency to the same 11.5.1 or later version.
  2. Remove the CloudRepo or MyGet repository from your Gradle repositories.
  3. Replace the legacy Storyteller group with com.getstoryteller while keeping each artifact name unchanged. For example, replace Storyteller:sdk with com.getstoryteller:sdk and Storyteller:ads-vast with com.getstoryteller:ads-vast.
  4. Sync Gradle and verify that the dependency graph contains only com.getstoryteller Storyteller artifacts.

Do not mix Storyteller:* and com.getstoryteller:* coordinates in the same application.

SDK Initialization#

Before using the Android SDK in your app, you need to initialize it with an API key.

Adding an API Key#

Use the initialize(apiKey: String, userInput: StorytellerUserInput? = null, eventTrackingOptions: StorytellerEventTrackingOptions = StorytellerEventTrackingOptions(), onSuccess: () -> Unit = {}, onFailure: (StorytellerError) -> Unit = {}) public method to manually initialize the SDK at runtime. This will authenticate the SDK on the Storyteller API and configure it with the corresponding settings.

  • apiKey: (Required) the API key you wish to initialize the SDK with
  • userInput : details of the user to be authenticated (this should be a unique user ID. If this is not set, the default value is used)
  • eventTrackingOptions: privacy and tracking configuration options (defaults to all tracking enabled)
  • onSuccess: callback for successful completion
  • onFailure: callback for failed completion with error

Usage:

    Storyteller.initialize(
      apiKey = "[APIKEY]",
      userInput = StorytellerUserInput("unique-user-id"),
      eventTrackingOptions = StorytellerEventTrackingOptions(
        enablePersonalization = true,
        enableStorytellerTracking = true
        // ... other options
      ),
      onSuccess = {
        // onSuccess action
      },
      onFailure = { error ->
        // onFailure action
      }
    )

Initialization errors:

  • InitializationError: when the context is null
  • InvalidAPIKeyError: when an invalid API key is used
  • NetworkError: when the call to load the settings for the SDK fails (i.e. a non-success HTTP status code is returned)
  • NetworkTimeoutError: when the call to load the settings for the SDK times out
  • JSONParseError: when a malformed settings response is received from the server

Note: Please be aware that this method is asynchronous

Authenticate a User#

For more information about Users and External IDs, please see Working with Users

Adding a StorytellerStoriesRow Composable#

  1. At first we will need a nesting composable. You can use any composable layout you want: Box, Column, LazyColumn, etc.
   @Composable
   fun MainScreen() {
       Box() {
            // ...
       }
   }
  1. Storyteller Composables Now it's time to add the Storyteller Composables to your app. The Storyteller Composables are the building blocks of the Storyteller SDK.
     StorytellerStoriesRow(
       modifier = Modifier,
       dataModel = StorytellerStoriesDataModel(categories = emptyList()), // data model with the configuration for your Composables. We will describe how to use StorytellerDataModel below.
       delegate = listViewDelegate, // delegate for the Composables. We will describe how to use StorytellerListViewDelegate below.
       state = rememberStorytellerRowState() // state for the Composables. We will describe how to use StorytellerRowState below.
     )

XML Views (Legacy)#

Preferred way to add Storyteller Lists is to use Composables. Storyteller still supports XML/Views and the guide can be found in the StorytellerListViews documentation.