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 was successfully initialized.

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 is a boolean static property which indicates whether the Storyteller Player is currently muted.

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#

func initialize(apiKey: String, userInput: StorytellerUserInput? = nil, eventTrackingOptions: StorytellerEventTrackingOptions = .enableAll) async throws

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#

func dismissPlayer(animated: Bool, dismissReason: String? = nil) async

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 - the reason why the Story/Page/Clip 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.

openSearch#

func openSearch() async

This method opens the Search screen (when enabled via isSearchEnabled).

resumePlayer#

func 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#

func openSheet(id: String) async throws

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

getStoriesCount#

func getStoriesCount(for categories: [String]) async -> Int

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

getClipsCount#

func getClipsCount(for collectionId: String) async -> Int

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