This guide explains how to use Storyteller SDK documentation with AI-powered coding assistants to enhance your development experience.
AI coding assistants like GitHub Copilot, Claude, ChatGPT, and others can significantly improve your development workflow when integrating the Storyteller SDK. By providing these AI tools with our documentation, you can:
AI-enabled editors can index and use Storyteller SDK documentation to provide more accurate suggestions. Here's how you can add our docs to various AI assistants:
Click to expand information about the complete SDK documentation
# Storyteller SDK Kotlin
## General Info and Rules to follow
> This file contains the complete documentation for the Storyteller SDK for Android (Kotlin).
> It should serve our integrators which are using AI to help adding Storyteller SDK to heir code.
Rules:
1. Client may use different structure and the codebase should be scanned to check if the right things are added e.g. Client may use build.gradle.kts files instead of build.gradle files when integrating Storyteller
2. When Adding Storyteller methods to the code comment should be created with a link to official www documentation (docs.getstoryteller.com/android)
3. If methods or fields are optional they should not be added to generated code
# 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
- [Storyteller Showcase App](https://github.com/getstoryteller/storyteller-showcase-android)
## 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](https://storyteller.mycloudrepo.io/public/repositories/storyteller-sdk/Storyteller/sdk/10.12.0/sdk-10.12.0.pom).
### 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](https://gradle.org/). It is recommended to use [Android Studio](https://developer.android.com/studio). If you are having problems with configuring your build, check out the [Android Studio guide](https://developer.android.com/studio/build) or [Gradle guides](https://gradle.org/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'
}
}
}
...
dependencies {
def storyteller_version = "10.12.0"
implementation(group: "Storyteller", name: "sdk", version: "$storyteller_version")
}
Storyteller.initialize(
apiKey = "[APIKEY]",
userInput = StorytellerUserInput("unique-user-id"),
onSuccess = {
// onSuccess action
},
onFailure = { error ->
// onFailure action
}
)
@Composable
fun MainScreen() {
Box() {
// ...
}
}
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.
)
...
override fun onCreateViewHolder(parent: ViewGroup, viewType: Int): ViewHolder {
val itemView = LayoutInflater.from(parent.context).inflate(R.layout.my_item, parent, false)
return MyViewHolder(itemView, parent)
}
...
class MyViewHolder(
private val view: View,
private val parent: ViewGroup,
): RecyclerView.ViewHolder(view) {
private val binding = ListStoryRowBinding.bind(view)
fun onBind(item: Item) {
binding.storytellerView.setViewHolderParent(parent)
...
}
}
<com.storyteller.ui.list.StorytellerStoriesRowView
android:id="@+id/storyRowView"
android:layout_width="match_parent"
android:layout_height="wrap_content"
...
/>
val storyRowView = StorytellerStoriesRowView(context)
view.addView(storyRowView)
// 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
// ~~~~~~~
}
val storytellerStoriesRowView = StorytellerStoriesRowView(context)
storytellerStoriesRowView.configuration = StorytellerStoriesView.ListConfiguration(
theme = customTheme,
uiStyle = StorytellerListViewStyle.AUTO,
displayLimit = 10,
cellType = StorytellerListViewCellType.SQUARE,
categories = listOf("category1", "category2", "categoryX")
)
<com.storyteller.ui.list.StorytellerStoriesRowView
app:cellType="square"
android:layout_width="match_parent"
android:layout_height="200dp"
...
/>
<LinearLayout
android:layout_width="match_parent"
android:layout_height="200dp"
android:orientation="vertical">
<com.storyteller.ui.list.StorytellerStoriesRowView
app:cellType="square"
android:layout_width="match_parent"
android:layout_height="match_parent"
...
/>
</LinearLayout>
<?xml version="1.0" encoding="utf-8"?>
<com.storyteller.ui.list.StorytellerStoriesRowView
app:cellType="square"
xmlns:android="http://schemas.android.com/apk/res/android"
xmlns:app="http://schemas.android.com/apk/res-auto"
android:layout_width="wrap_content"
android:layout_height="match_parent"
...
/>
...
<LinearLayout
android:layout_width="match_parent"
android:layout_height="match_parent"
android:orientation="vertical">
<com.storyteller.ui.list.StorytellerStoriesRowView
app:cellType="square"
android:layout_width="match_parent"
android:layout_height="wrap_content"
...
/>
...
</LinearLayout>
<com.storyteller.ui.list.StorytellerStoriesRowView
android:layout_width="match_parent"
android:layout_height="wrap_content"
app:cellType="round"/>
val storytellerStoriesRowView = StorytellerStoriesRowView(context)
storytellerStoriesRowView.reloadData()
val storytellerClipsRowView = StorytellerClipRowView(context)
storytellerClipsRowView.configuration = StorytellerClipsView.ListConfiguration(
theme = customTheme,
uiStyle = StorytellerListViewStyle.AUTO,
displayLimit = 10,
cellType = StorytellerListViewCellType.SQUARE,
collection = "collectionId"
)
<com.storyteller.ui.list.StorytellerClipsRowView
app:cellType="square"
android:layout_width="match_parent"
android:layout_height="200dp"
...
/>
<LinearLayout
android:layout_width="match_parent"
android:layout_height="200dp"
android:orientation="vertical">
<com.storyteller.ui.list.StorytellerClipsRowView
app:cellType="square"
android:layout_width="match_parent"
android:layout_height="match_parent"
...
/>
</LinearLayout>
<?xml version="1.0" encoding="utf-8"?>
<com.storyteller.ui.list.StorytellerClipsRowView
app:cellType="square"
xmlns:android="http://schemas.android.com/apk/res/android"
xmlns:app="http://schemas.android.com/apk/res-auto"
xmlns:tools="http://schemas.android.com/tools"
android:layout_width="wrap_content"
android:layout_height="match_parent"
...
/>
...
<LinearLayout
android:layout_width="match_parent"
android:layout_height="match_parent"
android:orientation="vertical">
<com.storyteller.ui.list.StorytellerClipsRowView
app:cellType="square"
android:layout_width="match_parent"
android:layout_height="wrap_content"
...
/>
...
</LinearLayout>
<com.storyteller.ui.list.StorytellerClipsRowView
android:layout_width="match_parent"
android:layout_height="wrap_content"/>
val storytellerClipsRowView = StorytellerClipsRowView(context)
storytellerClipsRowView.reloadData()
@Composable
fun MainScreen() {
Box() {
// ...
}
}
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.
)
val state = rememberStorytellerRowState() // or rememberStorytellerGridState() for StorytellerStoriesGrid or StorytellerClipsGrid
StorytellerStoriesRow(
// ...
state = state
)
// At any point in your code you can call `reloadData` method, maybe after doing PTR or after some event.
LaunchedEffect(Unit) {
state.reloadData()
}
StorytellerStoriesDataModel(
categories = listOf("category1", "category2"), // list of stories categories for the Composable. If you want to use all categories, you can pass an empty list.
theme = UiTheme(), // theme for the Composable. A global theme will be set if no value will be passed here.
uiStyle = StorytellerListViewStyle.LIGHT, // a style of the Composable. It can be AUTO, LIGHT or DARK. AUTO will represent the theme of the app.
displayLimit = 6, // a limit of the stories to be displayed in the Composable. Default is Int.MAX_VALUE.
cellType = StorytellerListViewCellType.SQUARE, // a cell type of the Composable. It can be SQUARE or ROUND.
visibleTiles = null // a number of visible tiles for rows. Default is null and turned off. If the value is set for greater than 0, the visible tiles will be turned on. The height of the row will be calculated based on the number of visible tiles and if set to eg. 3.5 it will always show three and a half tile independently of the screen size.
)
StorytellerClipsDataModel(
collection = "collection1", // a string representing your collection of Clips.
theme = UiTheme(), // theme for the Composable. A global theme will be set if no value will be passed here.
uiStyle = StorytellerListViewStyle.LIGHT, // a style of the Composable. It can be AUTO, LIGHT or DARK. AUTO will represent the theme of the app.
displayLimit = 6, // a limit of the clips to be displayed in the Composable. Default is Int.MAX_VALUE.
cellType = StorytellerListViewCellType.SQUARE, // a cell type of the Composable. It can be SQUARE or ROUND.
visibleTiles = null // a number of visible tiles for rows. Default is null and turned off. If the value is set for greater than 0, the visible tiles will be turned on. The height of the row will be calculated based on the number of visible tiles and if set to eg. 3.5 it will always show three and a half tile independently of the screen size.
)
val listViewDelegate by remember("your_item_id") {
val value = object : StorytellerListViewDelegate {
override fun onPlayerDismissed() {
// handle player dismissed event
}
override fun onDataLoadStarted() {
// handle loading started event
}
override fun onDataLoadComplete(success: Boolean, error: Error?, dataCount: Int) {
// handle data load complete event
}
}
mutableStateOf(
value
)
}
StorytellerStoriesRow(
delegate = listViewDelegate,
// ...
)
//Stories Grid
StorytellerStoriesGrid(
modifier = modifier,
dataModel = StorytellerStoriesDataModel(categories = emptyList()),
delegate = listViewDelegate,
state = rememberStorytellerGridState(),
isEnabled = true
)
//Stories Scrollable Grid
StorytellerStoriesGrid(
modifier = modifier,
dataModel = StorytellerStoriesDataModel(categories = emptyList()),
delegate = listViewDelegate,
state = rememberStorytellerGridState(),
isScrollable = true,
isEnabled = true
)
StorytellerStoriesRow(
modifier = modifier,
dataModel = StorytellerStoriesDataModel(categories = emptyList()),
delegate = listViewDelegate,
state = rememberStorytellerRowState()
)
//Clips Grid
StorytellerClipsGrid(
modifier = modifier,
dataModel = StorytellerClipsDataModel(collection = "collection"),
delegate = listViewDelegate,
state = rememberStorytellerGridState(),
isScrollable = false,
isEnabled = true
)
//Clips Scrollable Grid
StorytellerClipsGrid(
modifier = modifier,
dataModel = StorytellerClipsDataModel(collection = "collection"),
delegate = listViewDelegate,
state = rememberStorytellerGridState(),
isScrollable = true,
isEnabled = true
)
StorytellerClipsRow(
modifier = modifier,
dataModel = StorytellerClipsDataModel(collection = "collection"),
delegate = listViewDelegate,
state = rememberStorytellerRowState()
)
Storyteller.storytellerDelegate = myCustomStorytellerDelegate
val initialized = Storyteller.isInitialized
val searchEnabled = Storyteller.isSearchEnabled
val isStoryPlayerVisible = Storyteller.isPlayerVisible
val storytellerVersion = Storyteller.version
Storyteller.user.setCustomAttribute('location', 'New York');
fun openSearch(activity: Activity)
fun openSheet(activity: AppCompatActivity, sheetId: String, onError: (Error) -> Unit = {})
Storyteller.dismissPlayer(true, "reason")
Storyteller.resumePlayer()
suspend fun getStoriesCount(categoryIds: List<String>): Int
suspend fun getClipsCount(categoryIds: List<String>): Int
<!-- Content from docs/Ads.md -->
# Ads
## Table of Contents
<!-- no toc -->
+ [Introduction](#introduction)
+ [Storyteller First Party Ads](#storyteller-first-party-ads)
+ [Storyteller GAM SDK](#storyteller-gam-sdk)
## Introduction
The Storyteller SDK supports displaying ads that can be created in the Storyteller CMS (First Party Ads), as well as Ads from Google Ad Manager via an SDK extension developed by Storyteller and Ads
from other sources via custom implementation provided by the integrator.
Which source of ads is used can be configured on your behalf by a member of the Storyteller Delivery Team.
### Storyteller First Party Ads
If your tenant is configured to use Storyteller First Party Ads, which can be managed in the Storyteller CMS, then no changes to the Storyteller integration code are necessary. The Ads code is managed
entirely within the Storyteller SDK.
### Storyteller GAM SDK
To use Ads from Google Ad Manager in Storyteller, first reach out to your Storyteller contact and they will assist you with setting up Google Ad Manager to traffic ads to Storyteller.
You will then need to use the Storyteller Google Ad Manager SDK extension to fetch the ads from Google Ad Manager.
To use this extension, first install it using Gradle. Ensure you have the following Maven repository added to your `settings.gradle`:
```groovy
maven {
url = uri("https://storyteller.mycloudrepo.io/public/repositories/storyteller-sdk")
}
storyteller-ads = { module = "Storyteller:ads", version.ref = "storyteller" }
implementation(libs.storyteller.ads)
import com.storyteller.modules.ads.StorytellerGamModule
import com.storyteller.domain.ads.entities.CustomNativeTemplateIds
val storytellerGamModule = StorytellerGamModule.getInstance(applicationContext).apply {
init(
adUnit = { storytellerAdRequestInfo: StorytellerAdRequestInfo -> "/33813572/storyteller" },
templateIds = CustomNativeTemplateIds("12102683", "12269089"),
keyValuePairs = { emptyMap() },
)
}
fun initializeStoryteller() {
Storyteller.modules = listOf(storytellerGamModule)
//initialize code
}
Storyteller.modules = listOf(storytellerGamModule)
import com.storyteller.modules.ads.StorytellerGamModule
import com.storyteller.domain.ads.entities.CustomNativeTemplateIds
val storytellerGamModule = StorytellerGamModule.getInstance(applicationContext).apply {
init(
adUnit = { storytellerAdRequestInfo: StorytellerAdRequestInfo ->
when (storytellerAdRequestInfo) {
is StorytellerAdRequestInfo.StoriesAdRequestInfo -> "/33813572/storyteller/stories"
else -> "/33813572/storyteller/clips"
}
},
templateIds = StorytellerGoogleAdInfo.TEMPLATE_IDCustomNativeTemplateIds("12102683", "12269089"),
keyValuePairs = { emptyMap() },
)
}
fun initializeStoryteller() {
Storyteller.modules = listOf(storytellerGamModule)
//initialize code
}
<intent-filter android:autoVerify="true">
<action android:name="android.intent.action.VIEW" />
<category android:name="android.intent.category.DEFAULT" />
<category android:name="android.intent.category.BROWSABLE" />
<data
android:scheme="https"
android:host="[tenant_name].ope.nstori.es"
android:pathPattern="/open/.*/.*" />
</intent-filter>
<intent-filter android:autoVerify="true">
<action android:name="android.intent.action.VIEW" />
<category android:name="android.intent.category.DEFAULT" />
<category android:name="android.intent.category.BROWSABLE" />
<data
android:scheme="https"
android:host="[tenant_name].shar.estori.es"
android:pathPattern="/go/.*/.*" />
</intent-filter>
<intent-filter>
<action android:name="android.intent.action.VIEW" />
<category android:name="android.intent.category.DEFAULT" />
<category android:name="android.intent.category.BROWSABLE" />
<data
android:pathPattern="/.*/.*"
android:scheme="[tenant_name]stories"
android:host="open"/>
</intent-filter>
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.main)
val data: Uri? = intent?.data
if (data != null && Storyteller.isStorytellerDeepLink(data.toString()) {
//open link automatically
Storyteller.openDeepLink(this, data.toString())
}
}
fun openDeepLink(activity: Activity, url: String, onError: ((Error) -> Unit))
Storyteller.isStorytellerDeepLink("stories://open/9329bed2-2311-69b8-cbcf-39fcf8d8af21/f6445df7-bd79-71de-cdfb-39fd071568a1")
override fun userNavigatedToApp(url: String) {
// parse the url and navigate to the destination
}
fun openStory(activity: Activity, storyId: String? = null, onError: (Error) -> Unit = {})
fun openPage(activity: Activity, pageId: String? = null, onError: (Error) -> Unit = {})
fun openCollection(
activity: Activity,
configuration: StorytellerClipCollectionConfiguration,
titleDrawable: Drawable? = null,
onError: (Error) -> Unit = {}
)
fun openCategory(
activity: Activity,
category: String,
storyId: String? = null,
onError: (Error) -> Unit = {}
)
fun openStoryByExternalId(
context: Activity,
externalId: String? = null,
onError: (Error) -> Unit = {}
)
fun openCollectionByExternalId(
activity: Activity,
collectionId: String,
externalId: String? = null,
titleDrawable: Drawable? = null,
onError: (Error) -> Unit = {}
)
Storyteller.storytellerDelegate = myCustomStorytellerDelegate
...
override fun onUserActivityOccurred(type: StorytellerUserActivity.EventType, data: UserActivityData) {
if (type == StorytellerUserActivity.EventType.OPENED_STORY) {
// Retrieve the story id value
val openStoryId = data.storyId
// Retrieve the story title value
val openStoryTitle = data.storyTitle
// Report retrieved values from your app
}
}
...
override fun getAd(adRequestInfo: StorytellerAdRequestInfo, onComplete: (StorytellerAd) -> Unit = {}, onError: () -> Unit) {
// Action to get some ads
val ad = getMyAd()
// Convert the ad to a StorytellerAd
val storytellerAd = convertToStorytellrAd(ad)
// Provide the ad to the SDK
onComplete(ad)
}
override fun configureWebView(
view: WebView,
url: String?,
favicon: Bitmap?
) {
// Your custom configuration code goes here
// The following line shows a simple alert in the WebView with the message "test webview javascript".
view.evaluateJavascript("javascript: alert('test webview javascript');", null)
}
override fun customScreenForCategory(): @Composable()
((StorytellerFollowableCategoryCustomScreen) -> Unit) {
return { (pendingModifier, category, onBackClicked) ->
Scaffold(
modifier = pendingModifier,
topBar = {
CenterAlignedTopAppBar(
title = {
Text("${category.displayTitle}")
},
navigationIcon = {
IconButton(onClick = onBackClicked) {
Icon(
imageVector = Icons.AutoMirrored.Default.ArrowBack,
contentDescription = "Back"
)
}
}
)
}
) { paddingValues ->
Surface(
modifier = Modifier.padding(paddingValues)
) {
Box(
modifier = Modifier.fillMaxSize(), contentAlignment = androidx.compose.ui.Alignment.Center
) {
Text("Custom layout for ${category.displayTitle}")
}
}
}
}
}
Storyteller.useCustomScreenForCategory = {
if (it.type == "custom") {
// return true if you want to show the custom followable category screen
true
} else {
// return false if you want to show the default followable category screen
false
}
}
override fun bottomSheetScreen(
urlProvider: () -> String,
onDismiss: () -> Unit
): @Composable (() -> Unit) {
return {
DemoBottomSheet(urlProvider, onDismiss)
}
}
val StorytellerStoriesRowView = StorytellerStoriesRowView()
StorytellerStoriesRowView.delegate = myDelegate
...
override fun onDataLoadComplete(success: Boolean, error: Error?, dataCount: Int) {
if (success) {
// stories data has been loaded successfully
// dataCount is the current total number of stories, including newly added/removed data
} else if (error != null) {
// an error has occurred, unwrap the error value for more information
// dataCount is the total number of stories before loading began
}
}
...
override fun onDataLoadComplete(success: Boolean, error: Error?, dataCount: Int) {
if (error != null && dataCount == 0) {
// stories have failed to load with error and there is no data to show
// you may wish to hide the `StorytellerStoriesRowView` instance here
StorytellerStoriesRowView.visibility = View.GONE
}
}
<?xml version="1.0" encoding="utf-8"?>
<androidx.constraintlayout.widget.ConstraintLayout
xmlns:android="http://schemas.android.com/apk/res/android"
xmlns:app="http://schemas.android.com/apk/res-auto" xmlns:tools="http://schemas.android.com/tools"
android:layout_width="match_parent" android:layout_height="match_parent">
<androidx.fragment.app.FragmentContainerView
android:id="@+id/fragment_host"
android:name="com.storyteller.ui.pager.StorytellerClipsFragment"
android:layout_width="0dp"
android:layout_height="0dp"
app:layout_constraintBottom_toBottomOf="parent"
app:layout_constraintDimensionRatio="9:16"
app:layout_constraintEnd_toEndOf="parent"
app:layout_constraintStart_toStartOf="parent"
app:layout_constraintTop_toTopOf="parent"
app:storyteller_collection_id="your-collection-id"
app:storyteller_initial_category="initial-category-of-collection"/>
</androidx.constraintlayout.widget.ConstraintLayout>
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
// An example using viewBinding feature; see view binding for reference.
val binding = ActivityClipFragmentHostBinding.inflate(layoutInflater)
setContentView(binding.root)
val storytellerClipsFragment = StorytellerClipsFragment.create("yourCollectionId")
val transaction = supportFragmentManager.beginTransaction()
transaction.add(
binding.fragmentHost.id,
storytellerClipsFragment
)
transaction.commit()
}
// finding the fragment by id using the fragment manager
val storytellerClipsFragment = supportFragmentManager.findFragmentById(binding.fragmentHost.id)
as StorytellerClipsFragment
storytellerClipsFragment.shouldPlay = false // stops playback
storytellerClipsFragment.shouldPlay = true // starts playback
val storytellerClipsFragment = StorytellerClipsFragment.create(collection = "yourCollectionId", topLevelBackEnabled = true)
val canGoBack = storytellerClipsFragment.canGoBack
val storytellerClipsFragment = StorytellerClipsFragment.create(collection = "yourCollectionId", topLevelBackEnabled = true)
storytellerClipsFragment.listener = object : StorytellerClipsFragment.Listener {
override fun onTopLevelBackPressed(): Boolean {
// will be invoked when top level back button is pressed
return true // true if fragment needs to be stopped / host should handle back
}
override fun onDataLoadStarted() {
// will be invoked when data load starts
}
override fun onDataLoadComplete(success: Boolean, error: Error?, dataCount: Int){
// will be invoked when data load completes or fails
}
}
storytellerClipsFragment.reloadData()
val storytellerClipsFragment = StorytellerClipsFragment.create(collection = "yourCollectionId", topLevelBackEnabled = true)
storytellerClipsFragment.listener = object : StorytellerClipsFragment.Listener {
override fun onTopLevelBackPressed(): Boolean {
// will be invoked when top level back button is pressed
return true // true if fragment needs to be stopped
}
}
val storytellerClipsFragment = StorytellerClipsFragment.create(collection = "yourCollectionId", topLevelBackEnabled = true)
val canGoBack = storytellerClipsFragment.canGoBack
val storytellerClipsFragment = StorytellerClipsFragment.create(collection = "yourCollectionId", initialCategory = "yourCategory")
<androidx.fragment.app.FragmentContainerView android:id="@+id/fragment_host"
android:name="com.storyteller.ui.pager.StorytellerClipsFragment"
android:layout_width="0dp"
android:layout_height="0dp"
app:layout_constraintBottom_toBottomOf="parent"
app:layout_constraintDimensionRatio="9:16"
app:layout_constraintEnd_toEndOf="parent"
app:layout_constraintStart_toStartOf="parent"
app:layout_constraintTop_toTopOf="parent"
app:storyteller_collection_id="your-collection-id"
app:storyteller_initial_category="initial-category-of-collection"/>
val storytellerClipsFragment = StorytellerClipsFragment.create(collection = "yourCollectionId", topLevelBackEnabled = true)
storytellerClipsFragment.listener = object : StorytellerClipsFragment.Listener {
override fun onTopLevelBackPressed(): Boolean {
// will be invoked when top level back button is pressed
return true // true if fragment needs to be stopped / host should handle back
}
override fun onDataLoadStarted() {
// will be invoked when data load starts
}
override fun onDataLoadComplete(success: Boolean, error: Error?, dataCount: Int){
// will be invoked when data load completes or fails
}
}
storytellerClipsFragment.reloadData()
ViewCompat.setOnApplyWindowInsetsListener(binding.root) { _, winInsets ->
val inset =
winInsets.getInsets(WindowInsetsCompat.Type.statusBars() or WindowInsetsCompat.Type.navigationBars())
storytellerClipsFragment.topInset = inset.top
storytellerClipsFragment.bottomInset = inset.bottom
WindowInsetsCompat.CONSUMED
}
class DemoComposeEmbeddedClipsActivity : FragmentActivity() {
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
val collection = intent.getStringExtra("collection") ?: ""
val widthPercentage = intent.getIntExtra("width", 100) / 100F
val heightPercentage = intent.getIntExtra("height", 80) / 100F
val topLevelBack = intent.getBooleanExtra("topLevelBack", false)
val initialCategory = intent.getStringExtra("category") ?: ""
enableEdgeToEdge()
setContent {
val state = rememberStorytellerEmbeddedClipsState(collectionId = collection, topLevelBack = topLevelBack, initialCategory = initialCategory)
StorytellerEmbeddedClips(
modifier = Modifier
.fillMaxWidth(widthPercentage)
.fillMaxHeight(heightPercentage),
state = state,
)
}
}
companion object {
fun start(context: Context, collection: String, category: String?, width: Int, height: Int, topLevelBack: Boolean) {
// add params to intent
Intent(context, DemoComposeEmbeddedClipsActivity::class.java).apply {
putExtra("collection", collection)
putExtra("category", intialCategory)
putExtra("width", width)
putExtra("height", height)
putExtra("topLevelBack", topLevelBack)
context.startActivity(this)
}
}
}
}
val state = rememberStorytellerEmbeddedClipsState(collectionId = "collection", topLevelBack = topLevelBack)
StorytellerEmbeddedClips(
modifier = Modifier,
state = state
)
val state = rememberStorytellerEmbeddedClipsState(collectionId = "collection", topLevelBack = topLevelBack)
val canGoBack = state.canGoBack // true if user can navigate back
val state = rememberStorytellerEmbeddedClipsState(collectionId = collection, topLevelBack = topLevelBack)
state.goBack() // navigate to previous category programmatically
import com.storyteller.domain.theme.builders.buildTheme
import com.storyteller.domain.theme.builders.ofHexCode
import com.storyteller.domain.theme.builders.fontRes // For font resources
import com.storyteller.domain.theme.builders.drawableRes // For drawable resources
Storyteller.theme = buildTheme {
light { // Configure the light theme
colors.primary = ofHexCode("#1A2B3C") // Example: Set primary color
font = fontRes(R.font.your_custom_font_family) // Example: Set a custom font
// ... other light theme customizations
}
dark from light // Apply light theme settings to dark, then override if needed
// dark.colors.primary = ofHexCode("#D3E4F5") // Example: Override primary for dark
}
light.colors.primary = ofHexCode("#FF00FF")
light.player.icons.close = drawableRes(R.drawable.custom_close_icon)
<!-- res/font/custom_font.xml -->
<?xml version="1.0" encoding="utf-8"?>
<font-family xmlns:android="http://schemas.android.com/apk/res/android">
<font android:fontWeight="400" android:font="@font/my_font_regular" />
<font android:fontWeight="700" android:font="@font/my_font_bold" />
</font-family>
light.font = fontRes(R.font.custom_font)
// Example of setting up the delegate (typically in your Application class or where Storyteller is initialized)
Storyteller.storytellerDelegate = object : StorytellerDelegate {
// ... other delegate methods
override fun onUserActivityOccurred(type: StorytellerUserActivity.EventType, data: UserActivityData) {
// Handle the analytics event here
// 'type' is an enum member of StorytellerUserActivity.EventType
// 'data' is a UserActivityData object containing details about the event
when (type) {
StorytellerUserActivity.EventType.OPENED_STORY -> {
val storyId = data.storyId
// Process Opened Story event
}
StorytellerUserActivity.EventType.OPENED_CLIP -> {
val clipId = data.clipId
// Process Opened Clip event
}
// ... handle other event types as needed
else -> {
// Optional: handle other events or log them
}
}
}
// ... other delegate methods
}
Here are some effective prompts to use with AI assistants when implementing Storyteller SDK: