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#

Currently the Android SDK contains the following dependencies.

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. Add the maven repository for the SDK 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()
            maven {
                url 'https://storyteller.mycloudrepo.io/public/repositories/storyteller-sdk'
            }
        }
      }
  1. Modify the app Module build.gradle file (MyAwesomeApp/app/build.gradle)
        ...
        dependencies {
            def storyteller_version = "11.2.0"

            implementation(group: "Storyteller", name: "sdk", version: "$storyteller_version")
        }

  1. Sync your project with Gradle files

  2. Android Studio

Gradle Sync

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: (Error) -> 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)#

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