Additional Methods

This page is a reference for Storyteller.shared properties and methods that are useful during integration.

For dedicated topics, see:

• Opening content
• Deep linking
• Search
• Ads
• Analytics

Table of Contents

• Properties
• Methods

Properties

delegate

The delegate is responsible for things like fetching ads and handling in-app navigation. More detailed info can be found in Storyteller Delegates.

modules

This is a list of StorytellerModule instances that can extend Storyteller (for example: host-supplied ads), alongside the delegate.

See the Showcase setup that registers modules and the delegate in AppDelegate.setupStoryteller.

currentApiKey

This is the current API key set when using Storyteller.shared.initialize(...).

version

This is the current SDK version (for example "11.4.0").

let version = Storyteller.shared.version

isInitialized

This value becomes true after Storyteller is successfully initialized. Calling initialize again resets it to false until that call succeeds; it remains false if initialization throws.

let isInitialized = Storyteller.shared.isInitialized

isPresentingContent

A Boolean value indicating whether Storyteller content is currently presented.

This property is true when a Story Player, Clip Player, Search or Sheet is visible, and false otherwise. It updates automatically when content is presented or dismissed.

isPlayerMuted

This instance property indicates whether the current Storyteller Player is muted. It is isolated to the main actor, so read it from UI code or another main-actor context.

@MainActor
func updateMuteIndicator() {
    let isMuted = Storyteller.shared.isPlayerMuted
    print("Player muted: \(isMuted)")
}

isSearchEnabled

Available only on iOS.

This synchronously returns the cached Search setting. Before initialization succeeds, it may reflect default settings or settings cached for a previous tenant. The value is authoritative for the current tenant when isInitialized is true.

theme

This is the default fallback theming style used to render Story or Clips items in lists and activities launched from lists.

user

Allows setting or removing custom attributes for personalization and audience targeting. See Working with Users.

Storyteller.shared.user.setCustomAttribute(key: "location", value: "New York")

eventTrackingOptions

The eventTrackingOptions property customizes Storyteller's analytics and tracking behavior. This property is read-only and can only be set during SDK initialization. See Privacy and Tracking.

Methods

Most of the methods below are async and should be called from a Task or another async context.

mute and unmute

Call try await Storyteller.shared.mute() or try await Storyteller.shared.unmute() after initialization succeeds. These main-actor methods return after the native mute state has been accepted and applied to existing media. Calling either method before initialization completes throws StorytellerError.notInitialized.

To start silently, await mute() before opening a Story or Clip or enabling Embedded Clips playback. The explicit choice survives opening configuration and overrides an older saved preference for that opening, including when the mute button is hidden. No Player or audio session is started by the command.

@MainActor
func openMutedClips(collectionId: String) async throws {
    try await Storyteller.shared.mute()
    let configuration = StorytellerClipCollectionConfiguration(collectionId: collectionId)
    try await Storyteller.shared.openCollection(configuration: configuration)
}

During playback, mute and unmute leave video, playback position and pause state intact. A later user or device action can change audio normally. If mute-state persistence is enabled, the command also updates the saved preference used by later openings; the previous preference is not automatically restored. After the Player releases audio, the next activation follows the usual opening defaults and persistence settings. Repeating a command records the explicit choice without producing a duplicate mute transition. unmute() does not raise device volume or promise audible sound. These methods control Stories and full-screen or Embedded Clips; they do not control Cards.

initialize

try await Storyteller.shared.initialize(apiKey: "YOUR_API_KEY")

The initialize method is required to be called for Storyteller to work. It's recommended to fire this method as soon as possible in the app lifecycle.

Parameters:

• apiKey - This is the API key provided by the Storyteller team.
• userInput - This is the ID of the user to be authorized. See Working with Users for more information on user IDs.
• eventTrackingOptions - Configures analytics and tracking behavior. Defaults to .enableAll which enables all tracking options. Once set during initialization, these options can only be changed by reinitializing the SDK. See Privacy and Tracking for more information.

Throws - if there is an issue with initialization.

dismissPlayer

await Storyteller.shared.dismissPlayer(animated: true, dismissReason: "host-navigation")

The dismissPlayer() force closes the currently open Story or Clips Player. If no Story or Clips Player is open when this is called, it has no effect.

Parameters:

• animated - this decides whether to animate the dismissing of the view or not
• dismissReason - an optional host-defined reason for closing the Story, Page, or Clip. When supplied, it populates StorytellerUserActivityData.dismissedReason on the corresponding dismissal event. Passing nil does not suppress the event; it leaves dismissedReason as nil. Delivery through onUserActivityOccurred is controlled by enableUserActivityTracking and, for Ad events, enableAdTracking.

openSearch

Available only on iOS.

await Storyteller.shared.openSearch()

This method waits for successful SDK initialization, then opens the Search screen when Search is enabled for the current tenant. If Search is disabled, or the calling task is cancelled while waiting, it returns without presenting anything or dismissing the current Player. It rechecks current tenant readiness after dismissing an existing Player and does not present Search if reinitialization has started. See Search for the complete invocation and cached isSearchEnabled semantics.

resumePlayer

Storyteller.shared.resumePlayer()

This method resumes the currently open Story or Player Views. If no Player is open when this is called, it has no effect.

If you use Storyteller.shared.useCustomShareHandling = true, call resumePlayer() after dismissing your custom share UI so the paused Storyteller content can continue playback.

openSheet

Available only on iOS.

try await Storyteller.shared.openSheet(id: "sheet-id")

On iOS, this method waits for successful SDK initialization before dismissing an active Player and loading the Sheet with the corresponding ID. If initialization restarts while the Player is being dismissed, it waits again before fetching the Sheet. Task cancellation and post-initialization Sheet errors propagate through the existing async throws call.

getStoriesCount

let storiesCount = await Storyteller.shared.getStoriesCount(for: ["category-id"])

This method retrieves the total count of Stories for the specified category IDs.

getClipsCount

let clipsCount = await Storyteller.shared.getClipsCount(for: "collection-id")

This method retrieves the total count of Clips in the specified Collection.