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#

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.

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.

If the clip with the externalId is found within the collection, it will be opened. Otherwise, the player will open to the first clip in the collection.

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