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.
Before you can add the iOS 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]
.
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"
If your app uses R8, the rules are added automatically. If your app uses ProGuard, you should add the following rules here.
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.
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 notbuildscript
...
allprojects {
repositories {
google()
mavenCentral()
maven {
url 'https://www.myget.org/F/storyteller-android-sdk/maven'
}
}
}
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 = "8.1.10"
implementation(group: "Storyteller", name: "sdk", version: "$storyteller_version")
}
Sync your project with Gradle files
Android Studio
Before using the Android SDK in your app, you need to initialize it with an API key.
Use the initialize(apiKey: String, userInput: UserInput? = null, 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 withuserInput
: details of the user to be authenticated (this should be a unique user ID. If this is not set, the default value is used)onSuccess
: callback for successful completiononFailure
: callback for failed completion with errorUsage:
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 usedNetworkError
: 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 outJSONParseError
: when a malformed settings response is received from the serverNote: Please be aware that this method is asynchronous
For more information about Users and External IDs, please see Working with Users
The StorytellerRowView
can be added to your app using XML layout or in code.
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"
...
/>
Create a StorytellerRowView
instance
val storyRowView = StorytellerRowView(context)
Add the created view instance to the view hierarchy
view.addView(storyRowView)
StorytellerListView
Hosting ActivityPlease keep in mind that Stories will open in the activity that displays a status bar only if there is a cutout notch present on the device. In other cases, Stories will open in the activity without a status bar.
Status bar visibility changes can have an 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 the 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
// ~~~~~~~
}
To properly handle reenter transitions hosting activity should also invoke Storyteller.Companion.activityReentered()
override fun onActivityReenter(resultCode: Int, data: Intent?) {
super.onActivityReenter(resultCode, data)
activityReentered()
}
Storyteller
has some helper methods which may be useful, see AdditionalMethods for more details.
StorytellerDelegate
has callbacks for events which can be implemented, see StorytellerDelegate for more details.
StorytellerRowView
has callbacks for events which can be implemented, see StorytellerListViewDelegate for more details.