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.

Opening Stories & Categories#

openCategory#

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

func openCategory(category: String, openReason: StorytellerOpenReason = .instanceMethod) async throws

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.

func openStory(id: String, openReason: StorytellerOpenReason = .instanceMethod) async throws

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.

func openStory(externalId: String, openReason: StorytellerOpenReason = .instanceMethod) async throws

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.

func openPage(id: String, openReason: StorytellerOpenReason = .instanceMethod) async throws

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.

func openCollection(configuration: StorytellerClipCollectionConfiguration, openReason: StorytellerOpenReason = .instanceMethod) async throws

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).

Open Reason Enum#

The optional openReason parameter accepts values of StorytellerOpenReason:

public enum StorytellerOpenReason {
    case instanceMethod
    case deeplink
}

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.

func openClipByExternalId(collectionId: String, externalId: String, openReason: StorytellerOpenReason = .instanceMethod) async throws

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).