Skip to content

Open Player#

These methods allow you to programmatically open the Storyteller player to specific content like Stories, Pages, Categories, or Clip Collections.

All methods on this page are asynchronous and throwing. Call them from an asynchronous context and handle failures. For example:

import StorytellerSDK

func openFeaturedStory() {
    Task { @MainActor in
        do {
            try await Storyteller.shared.openStory(id: "featured-story")
        } catch {
            print("Unable to open Story: \(error.localizedDescription)")
        }
    }
}

Opening Stories & Categories#

The Story, Page, and Story Category methods in this section wait for successful SDK initialization before dismissing existing Storyteller content or requesting new content. Calls made before initialization starts continue automatically after a later successful initialization, preserving their identifiers and openReason. Cancellation and content-loading errors continue through the existing async throws contract.

openCategory#

Opens a list of Stories filtered by a specific category ID.

try await Storyteller.shared.openCategory(category: "category-id")

See the Showcase usage of openCategory in FeedImageView.

Parameters:

  • category: The ID of the Story category to open.
  • openReason: Why the player was opened. Used only for analytics.

Throws if there is an issue opening the category (e.g., the category is not available).

openStory (by ID)#

Opens a single Story by its specific ID.

try await Storyteller.shared.openStory(id: "story-id")

Parameters:

  • id: The ID of the Story to open.
  • openReason: Why the player was opened. Used only for analytics.

Throws if there is an issue opening the Story (e.g., the requested Story is not available).

openStory (by External ID)#

Opens a single Story by its assigned external ID.

try await Storyteller.shared.openStory(externalId: "story-external-id")

Parameters:

  • externalId: The external ID of the Story to open.
  • openReason: Why the player was opened. Used only for analytics.

Throws if there is an issue opening the Story (e.g., no Story found with the external ID).

openPage#

Opens a specific Page within its Story. The SDK deduces the correct Story based on the Page ID.

try await Storyteller.shared.openPage(id: "page-id")

Parameters:

  • id: The ID of the Page to open.
  • openReason: Why the player was opened. Used only for analytics.

Throws if there is an issue opening the Page (e.g., the requested Page is not available).

Opening Clips & Collections#

openCollection#

Opens a collection of Clips, optionally starting at a specific Clip or Category.

let configuration = StorytellerClipCollectionConfiguration(collectionId: "collection-id")
try await Storyteller.shared.openCollection(configuration: configuration)

Parameters:

  • configuration: A StorytellerClipCollectionConfiguration struct specifying the collection and optional starting points (see Embedded Clips for configuration details).

If a specific clip or category is specified via configuration.destination and found, it will be opened. Otherwise, the first clip in the collection is opened.

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

Throws if there is an issue opening the Collection (e.g., the requested Collection is not available).

import StorytellerSDK

func openTopPlays() {
    let configuration = StorytellerClipCollectionConfiguration(
        collectionId: "top-plays",
        context: ["location": "home"]
    )

    Task { @MainActor in
        do {
            try await Storyteller.shared.openCollection(configuration: configuration)
        } catch {
            print("Unable to open Clips: \(error.localizedDescription)")
        }
    }
}

Open Reason Enum#

The optional openReason parameter accepts values of StorytellerOpenReason:

let openReason: StorytellerOpenReason = .instanceMethod

This value is used only for analytics and has no functional effect on how the player behaves.

openClipByExternalId#

Opens a collection of Clips and attempts to navigate directly to a specific Clip within that collection using its external ID.

try await Storyteller.shared.openClipByExternalId(
    collectionId: "collection-id",
    externalId: "clip-external-id"
)

Parameters:

  • collectionId: The ID of the Clip Collection.
  • externalId: The external ID of the specific Clip to open.
  • openReason: Why the player was opened. Used only for analytics.

The SDK opens the Clip matching externalId, including when viewed ordering moves it outside the Collection's initial response. The requested Collection remains the source for subsequent Clip navigation.

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

Throws if there is an issue opening the Collection or if no Clip can be resolved for the external ID. An unresolved external ID does not open a different Clip from the Collection.