Skip to content

Additional Methods#

Table of Contents#

This page covers additional helper methods and properties.

Showcase examples#

Setting the global StorytellerDelegate#

Please see the dedicated Storyteller Delegates page.

    Storyteller.storytellerDelegate = myCustomStorytellerDelegate

Static Attributes#

isInitialized#

isInitialized is a boolean static property which is set to true if Storyteller was initialized successfully.

val initialized = Storyteller.isInitialized

isSearchEnabled#

isSearchEnabled is a boolean static property which is set to true if the Search feature is enabled in the Storyteller configuration.

val searchEnabled = Storyteller.isSearchEnabled

isPlayerVisible#

isPlayerVisible is a boolean property which is set to true when a Story or Clip player is opened, false when the Story or Clip player is dismissed.

val isStoryPlayerVisible = Storyteller.isPlayerVisible

version#

The version is a static String property which holds the SDK version.

val storytellerVersion = Storyteller.version

user#

Allows setting custom attributes for audience targeting. Please see Working with Users.

Storyteller.user.setCustomAttribute("location", "New York")

Static Methods#

openSearch#

    fun openSearch(activity: Activity)

This method opens the Search screen.

Parameters:

  • activity - this is the Activity that will be used to launch the Storyteller Search activity

openSheet#

fun openSheet(activity: AppCompatActivity, sheetId: String, onError: (StorytellerError) -> Unit)

This call opens a Sheet with a given ID.

Parameters:

  • activity - this is the Activity that will be used to launch the Sheet
  • sheetId - this is a Sheet's ID. If it is blank, onError will be called
  • onError - this is called when there is any issue with opening a Sheet (e.g. the sheetId is a blank string)

dismissPlayer#

dismissPlayer(animated: Boolean = true, reason: String? = null, onCompletion: () -> Unit = {}): force closes the currently open Story or Clip player. If no player is open when this is called, it has no effect.

animated: the flag indicating if close animation should be triggered. Defaults to true.

reason: the reason why the Story Page was force closed. This will be used to populate the dismissedReason parameter of the corresponding onUserActivityOccurred callback. If this is set to null the onUserActivityOccurred callback will not be triggered.

onCompletion: a callback that will be called when the player is dismissed. This is useful when you want to perform an action after the player is dismissed.

Storyteller.dismissPlayer(true, "reason")

resumePlayer#

resumePlayer(): resumes the currently open Story or Player Views. If no Player is open when this is called, it has no effect.

Storyteller.resumePlayer()

getStoriesCount#

suspend fun getStoriesCount(categoryIds: List<String>): Int

This method returns the count of stories available in the specified categories. It can be used to determine if a particular category or set of categories contains any Stories before rendering a UI component.

Parameters:

  • categoryIds - a list of category IDs to check for stories

Return value:

  • Returns the total number of stories available in the specified categories, or 0 if Storyteller is not initialized or the categoryIds list is empty

getClipsCount#

suspend fun getClipsCount(categoryIds: List<String>): Int

This method returns the count of clips available in the specified categories. It can be used to determine if a particular category or set of categories contains any Clips before rendering a UI component.

Parameters:

  • categoryIds - a list of category IDs to check for clips

Return value:

  • Returns the total number of clips available in the specified categories, or 0 if Storyteller is not initialized or the categoryIds list is empty

preloadClips#

@MainThread
fun preloadClips(
    collection: String,
    clipsIds: List<String> = emptyList(),
    preloadVideos: Boolean = false
): StorytellerClipPreloadHandle?

Preloads a Clips collection and optional single Clip IDs into the in-memory cache. This fetches the first page of the collection and stores it in the Clips cache, then fetches each requested clip by ID so single‑clip requests can read from cache. The loaded clips are also used to warm the playcard image cache to avoid a blank flash on first open.

Important: You must retain a strong reference to the returned StorytellerClipPreloadHandle while preloading is in progress. If the handle is garbage collected, preloading will stop.

Parameters:

  • collection - The Clips collection ID to preload.
  • clipsIds - Optional list of Clip IDs to preload (useful for clips beyond page 0).
  • preloadVideos - Whether to preload clip video content in addition to playcards. Defaults to false.

Return value:

  • Returns a StorytellerClipPreloadHandle that must be retained to keep preloading active. Call cancel() on the handle to stop preloading. Returns null if the SDK is not initialized or the collection is blank.

Best practices:

  • Only preload IDs for clips that are likely to be viewed soon (e.g., visible list items)
  • Call StorytellerClipPreloadHandle.cancel() when the preloaded clips are no longer needed
  • Large lists may contend with playback bandwidth; limit to near-term items
  • Include any single clip IDs that are outside the first page of the collection

Example usage:

class MyClipListViewModel : ViewModel() {
    private var preloadHandle: StorytellerClipPreloadHandle? = null

    fun onClipsVisible(collectionId: String, clipIds: List<String>) {
        // Cancel previous preloads
        preloadHandle?.cancel()
        // Start new preloads for the collection + visible clips
        preloadHandle = Storyteller.preloadClips(collectionId, clipIds, preloadVideos = false)
    }

    override fun onCleared() {
        super.onCleared()
        preloadHandle?.cancel()
    }
}