Skip to content

Additional Methods#

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

For dedicated topics, see:

Table of Contents#

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#

This value is true when the Search feature is enabled in the tenant configuration.

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.

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#

await Storyteller.shared.openSearch()

This method opens the Search screen when isSearchEnabled is true. If Search is disabled for the tenant, the method returns without presenting anything. See Search for a prerequisite check and complete invocation.

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#

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

This method loads and opens a Sheet with the corresponding ID.

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.