Skip to content

Open Player#

Showcase examples#

Open Stories#

To start silently, call Storyteller.mute after initialization and open the player from its completion callback.

This call opens a Story with a given ID. The call will only open that individual Story.

  fun openStory(activity: Activity, storyId: String? = null, onError: (StorytellerError) -> Unit = {})

Parameters:

  • activity - this is the Activity that will be used to launch the Storyteller Player
  • storyId - this is a Story's ID, if it is null then onError will be called
  • onError - this is called when there is an issue with opening a Story (e.g. the requested content is no longer available)

Open Pages#

This call opens a Page with a given ID. The call will only open that individual Story containing that page.

    fun openPage(activity: Activity, pageId: String? = null, onError: (StorytellerError) -> Unit = {})

Parameters:

  • activity - this is the Activity that will be used to launch the Storyteller Player
  • pageId - this is a Page's ID, if it is null then onError will be called
  • onError - this is called when there is an issue with opening a Story (e.g. the requested content is no longer available)

Open Collection#

        fun openCollection(
            activity: Activity,
            configuration: StorytellerClipCollectionConfiguration,
            titleDrawable: Drawable? = null,
            onError: (StorytellerError) -> Unit = {}
        )

Parameters:

  • activity - this is the Activity that will be used to launch the Storyteller Player
  • configuration - this is a Clip Collection configuration, see below
  • titleDrawable - this is a Drawable that will be used as the title of the Player (optional)
  • onError - this is called when there is an issue with opening the Collection (e.g. the requested Collection is not available)

StorytellerClipCollectionConfiguration parameters:

  • collectionId - this is a Clip Collection's ID (required)
  • categoryId - this is a Category ID (optional), if provided, this category will be opened, if the category is not available or not found it will be ignored
  • clipId - this is a Clip ID to open (optional)
  • adConfiguration - optional StorytellerClipsAdConfiguration for per-presentation Clips ads. Full-screen Clips use default-enabled bottom banners and pre-roll eligibility when this configuration is omitted. Set preRollEnabled = false to suppress IMA and the standard zero-index opening ad-as-Clip while preserving later cadence. Set betweenClipsAdProviderOrder to an ordered provider allowlist, or to an empty list to disable standard between-Clip requests. Set a positive frequency and/or a non-negative initialIndex to override the corresponding remote cadence field for this opening; leave either value null to inherit it. See Per-presentation Clips Ad Controls.

For example, this user receives GAM before VAST and no opening pre-roll:

Storyteller.openCollection(
  activity = this,
  configuration = Storyteller.StorytellerClipCollectionConfiguration(
    collectionId = "yourCollectionId",
    adConfiguration = Storyteller.StorytellerClipsAdConfiguration(
      bottomBannerEnabled = true,
      preRollEnabled = false,
      betweenClipsAdProviderOrder = listOf(
        Storyteller.StorytellerAdProvider.GAM,
        Storyteller.StorytellerAdProvider.VAST,
      ),
      frequency = 4,
      initialIndex = 1,
    ),
  ),
)

A muted full-screen Clips player leaves audio playing in other apps when it opens or resumes. The player requests audio focus when an active video Clip is unmuted, and releases it when playback pauses or the player is hidden.

Open Category#

This call opens a Story category. If Story ID is not supplied, the first Story in the collection will be opened.

    fun openCategory(
      activity: Activity,
      category: String,
      storyId: String? = null,
      onError: (StorytellerError) -> Unit = {}
)

Parameters:

  • activity - this is the Activity that will be used to launch the Storyteller Player
  • category - this is a Story category
  • storyId - this is a Story ID (optional)
  • onError - this is called when there is an issue with opening the Category (e.g. the requested Category is not available)

openStoryByExternalId#

This call opens a Story by external ID.

  fun openStoryByExternalId(
    context: Activity,
    externalId: String? = null,
    onError: (StorytellerError) -> Unit = {}
  )

Parameters:

  • activity - this is the Activity that will be used to launch the Storyteller Player
  • externalId - external Id to open a Story
  • onError - this is called when there is an issue with opening the Category (e.g. the requested Category is not available)

openCollectionByExternalId#

This call opens a Collection of Clips and shows Clip with external id. If Clip ID is not supplied, the first Clip in the collection will be opened.

    fun openCollectionByExternalId(
    activity: Activity,
    collectionId: String,
    externalId: String? = null,
    titleDrawable: Drawable? = null,
    onError: (StorytellerError) -> Unit = {}
)

Parameters:

  • activity - this is the Activity that will be used to launch the Storyteller Player
  • collectionId - this is a Clip Collection's ID
  • externalId - this is a Clip's external ID (optional)
  • titleDrawable - this is a Drawable that will be used as the title of the Player (optional)
  • onError - this is called when there is an issue with opening the Collection (e.g. the requested Collection is not available)

Control Story and Clip Audio#

After initialization succeeds, call Storyteller.mute(onCompletion, onError) or Storyteller.unmute(onCompletion, onError) to control Stories and full-screen or Embedded Clips. Both callbacks are optional and run on the main thread. Calls made before initialization succeeds report StorytellerError.InitializationError.

Completion means the SDK has accepted the command and applied it to current media. To prevent an initial audio burst, wait for mute completion before opening a player or enabling Embedded playback:

Storyteller.mute(
  onCompletion = {
    Storyteller.openStory(activity = this, storyId = "yourStoryId")
  },
  onError = { error -> /* Handle the failed audio command. */ },
)

With no active presentation, the latest command applies to the next Story or Clip, including when controls are hidden or configuration arrives later. During a presentation, the command follows that presentation's existing mute scope: enabled mute controls synchronize Stories and Clips; hidden controls affect the active context.

Muting leaves video playing. Unmuting does not resume paused playback or change device volume, and audible output still depends on the device and audio focus. These are ordinary mute actions: later user and device actions still work, configured persistence still applies, and there is no automatic restoration of an earlier sound choice. Cards use their own audio controls.