Getting Started

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 StorytellerRowView to your app.

Resources

• Storyteller Android Sample App

How to add the SDK to your project

Before you can add the Android SDK to your app, you will need to obtain the following:

• API Key - This is a secret key used to authenticate the SDK in your app, marked as [APIKEY]

SDK Dependencies

Currently the Android SDK contains the following dependencies:

//Kotlin
implementation "org.jetbrains.kotlin:kotlin-stdlib-jdk7:1.5.10"
implementation "org.jetbrains.kotlinx:kotlinx-coroutines-core:1.4.0"
implementation "org.jetbrains.kotlinx:kotlinx-coroutines-android:1.4.0"
//DI
implementation  "org.koin:koin-android:2.2.2"
implementation  "org.koin:koin-android-viewmodel:2.2.2"
//Android Support
implementation "androidx.appcompat:appcompat:1.2.0"
implementation "androidx.browser:browser:1.2.0"
implementation "androidx.constraintlayout:constraintlayout:2.0.1"
implementation "androidx.core:core-ktx:1.3.1"
implementation "androidx.lifecycle:lifecycle-extensions:2.1.0"
implementation "androidx.lifecycle:lifecycle-viewmodel-ktx:2.2.0"
implementation "androidx.work:work-runtime-ktx:2.4.0"
implementation "androidx.transition:transition:1.3.1"
implementation "androidx.cardview:cardview:1.0.0"
implementation "androidx.viewpager2:viewpager2:1.1.0-alpha01"
//API & serialization
implementation "com.squareup.retrofit2:retrofit:2.3.0"
implementation "org.jetbrains.kotlinx:kotlinx-serialization-json:1.0.0"
implementation "com.jakewharton.retrofit:retrofit2-kotlinx-serialization-converter:0.8.0"
//Media
implementation "com.google.guava:guava:27.1-android"
implementation "com.squareup.picasso:picasso:2.71828"
implementation "jp.wasabeef:picasso-transformations:2.2.1"

R8 / ProGuard

If your app uses R8, the rules are added automatically. If your app uses ProGuard, you should add the following rules here.

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://www.myget.org/F/storyteller-android-sdk/maven'
            }
        }
      }
   

2. Modify the app Module build.gradle file (MyAwesomeApp/app/build.gradle)

        ...
        android {
            ...
            compileOptions {
                sourceCompatibility JavaVersion.VERSION_1_8
                targetCompatibility JavaVersion.VERSION_1_8
            }
        }
   
        dependencies {
            ...
            def storyteller_version = "7.1.0"
            implementation(group: "Storyteller", name: "sdk", version: "$storyteller_version")
        }
   
   

3. Sync your project with gradle files

• Android Studio

  

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: UserInput? = null, categoriesToPreload: List<String> = emptyList(), 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, should be unique user id, if not set the default value is used
• categoriesToPreload: list of categories for preloading, it can remain empty if no categories preload is required
• onSuccess: callback for successful completion
• onFailure: callback for failed completion with error

Usage:

    Storyteller.initialize(
      apiKey = "[APIKEY]",
      userInput = UserInput("unique-user-id"),
      onSuccess = {
        // onSuccess action
      },
      onFailure = { error ->
        // onFailure action
      }
    )

Initialization errors:

• InitiailizationError: 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 Users

Adding a StorytellerRowView

The StorytellerRowView can be added to your app using xml layout or in code.

XML

Add a com.storyteller.ui.list.StorytellerRowView element to your layout

        <com.storyteller.ui.list.StorytellerRowView
            android:id="@+id/storyRowView"
            android:layout_width="match_parent"
            android:layout_height="wrap_content"
            ...
            />

Code

1. Create a StorytellerRowView instance

      val storyRowView = StorytellerRowView(context)
   

2. Add the created view instance to the view hierarchy

      view.addView(storyRowView)
   

Recommendations for StorytellerListView hosting activity

Please keep in mind that stories are being opened in the activity that will display status bar only if there is a cutout notch present on the device, in other cases stories will be open in the activity without status bar.

Status bar visibility changes can have impact on shared element transitions between storyteller list view and story viewing activity. For that reason we recommend hosting activities to use LAYOUT_STABLE flags as in code snippet below

 // Storyteller hosting activity onCreate method
  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    // ~~~~~~~
    window.decorView.systemUiVisibility =
      window.decorView.systemUiVisibility or View.SYSTEM_UI_FLAG_LAYOUT_STABLE
    // ~~~~~~~
}

Further Reading

Additional Storyteller Methods

Storyteller has some helper methods which may be useful, see AdditionalMethods for more details.

Implementing Storyteller Callbacks

StorytellerDelegate has callbacks for events which can be implemented, see StorytellerDelegate for more details.

Implementing StorytellerRowView Callbacks

StorytellerRowView has callbacks for events which can be implemented, see StorytellerListViewDelegate for more details.