{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"],"fields":{"title":{"boost":1000.0},"text":{"boost":1.0},"tags":{"boost":1000000.0}}},"docs":[{"location":"","title":"Storyteller Swift SDK Documentation","text":"

Use Storyteller to add Stories, Clips, and Cards to your iOS or tvOS application. Choose the route that matches what you are trying to do.

"},{"location":"#quick-start","title":"Start Here","text":"

For a new iOS integration:

The UIKit and SwiftUI routes are both complete; choose the framework your app uses. For Apple TV, use the tvOS Guide.

Using an AI coding assistant? The AI-assisted integration guide explains how to give it the published Storyteller documentation and, if you have access to the Storyteller iOS Showcase repository, use its $integrate-storyteller skill.

"},{"location":"#sdk-and-showcase-requirements","title":"SDK and Showcase Requirements","text":"

The SDK compatibility contract is separate from the build settings used by the Showcase applications. A deployment target determines which operating-system versions can run your app; a Showcase app's Xcode version and Swift language mode describe how that example project is built.

The current Storyteller SDK supports these application deployment targets:

Platform Minimum deployment target iOS iOS 13.0 tvOS tvOS 15.0

We test the current SDK line with Xcode 26.2. Earlier Xcode versions may also work, but they are not part of our tested configuration. The deployment targets above define the supported operating-system versions. The SDK binary is built in Swift 6, but it can be consumed by app targets using either Swift 5 or Swift 6 language mode.

The private iOS Showcase repository contains two deliberately modern example applications:

Application Installation App deployment target Swift language mode Xcode used for testing SwiftUI Feature Showcase Swift Package Manager iOS 16.0 Swift 6 26.2 UIKit/CocoaPods Sample CocoaPods iOS 16.0 Swift 5 26.2

Those are the checked-in example configurations, not higher minimums for the SDK. Your own app can keep an iOS 13 deployment target and its existing supported Swift language mode while adopting the current SDK.

"},{"location":"#showcase-source-access","title":"Access the iOS Showcase Source","text":"

The iOS documentation and the private Showcase source are both available to Storyteller customers, but access is granted separately. The documentation access code supplied by Storyteller does not grant GitHub access.

To use the Showcase source links in these guides, tell your Storyteller contact which GitHub account you want authorised. Accept the resulting GitHub invitation, then make sure you are signed in with that exact account before opening a link.

The Showcase repository intentionally returns a 404 to anyone without access. If a link returns a 404, check that you are signed in to GitHub with the authorised account, that you accepted the invitation, and that Storyteller has granted that account access. Contact support@getstoryteller.com if you still cannot open the source.

"},{"location":"#documentation","title":"Choose a Documentation Path","text":""},{"location":"#getting-started","title":"Set Up or Upgrade an Integration","text":"

Start with the iOS Quickstart Guide, follow the tvOS Guide, or migrate an existing integration from version 10.

"},{"location":"#components","title":"Add a Storyteller Experience","text":"

Choose Story and Clip Lists, Storyteller Home, Embedded Clips, or Storyteller Cards. You can also open a Player programmatically or add content Search.

"},{"location":"#configuration","title":"Configure Your Integration","text":"

Set up user identity and personalization, choose privacy and tracking behavior, and customize Storyteller themes.

"},{"location":"#features","title":"Add Features and Integrations","text":"

Continue with Analytics integration, the Analytics Event Reference, Ads, Deep Linking, navigation back into your app, or Brightcove.

"},{"location":"#reference","title":"Look Up SDK Behavior","text":"

Use Delegates and Callbacks, Storyteller Modules, or Additional SDK Methods for API details. You can also use the documentation with AI assistants or review the release notes.

"},{"location":"#support","title":"Troubleshoot or Get Help","text":"

Start with Troubleshooting Storyteller on iOS to identify the failing boundary and the next useful check. If you still need help, contact us at support@getstoryteller.com.

"},{"location":"AI/","title":"Using Storyteller SDK Docs with AI Assistants","text":"

This guide explains how to use Storyteller SDK documentation with AI-powered coding assistants to enhance your development experience.

"},{"location":"AI/#why-use-ai-assistants-with-documentation","title":"Why Use AI Assistants with Documentation","text":"

AI coding assistants can significantly improve your development workflow when integrating the Storyteller SDK. By providing your tool with our documentation, you can:

"},{"location":"AI/#use-the-showcase-integration-skill","title":"Use the Showcase Integration Skill","text":"

If you have access to the private Storyteller iOS Showcase repository, it includes an $integrate-storyteller skill at .agents/skills/integrate-storyteller/SKILL.md for AI coding assistants that support repository-local skills. It can guide a new integration, audit an existing integration, or help troubleshoot a problem using your app and the published Storyteller documentation.

Open the Showcase repository in your assistant's workspace alongside your iOS app, then ask:

Use $integrate-storyteller to help me integrate Storyteller into <path-to-my-ios-app>.

For an existing integration, ask the skill to audit the app instead. It will inspect your app as the primary source, ground its guidance in the published documentation, and identify assumptions explicitly.

If you do not have access to the Showcase repository or your assistant does not support repository-local skills, use the documentation bundle below.

"},{"location":"AI/#adding-documentation-to-your-project","title":"Adding Documentation to Your Project","text":""},{"location":"AI/#download-llmstxt","title":"Download llms.txt","text":"

Download the Storyteller iOS documentation bundle and place it somewhere your editor can reference.

The bundle can be saved into your local repository and then referenced by your AI tool:

  1. Create a .ai/ directory in your project
  2. Save the downloaded content as .ai/storyteller-sdk-docs.md
  3. Point your tool to .ai/storyteller-sdk-docs.md and reference it in your prompts, or paste the relevant sections into the editor

For narrower context, read the aggregate bundle's <PAGE: slug> markers and request the corresponding concrete topic filename from the /ios/ai/ directory. For example, <PAGE: quickstart> maps to the Quickstart topic bundle.

Agents can also use the documentation search index to discover concrete documentation pages. Confirm important answers against those pages.

"},{"location":"AI/#example-prompts","title":"Example Prompts","text":"

Here are some effective prompts to use with AI assistants when implementing Storyteller SDK:

  1. \"Using the Storyteller SDK documentation, help me initialize the SDK in my Swift iOS app.\"

  2. \"Based on the Storyteller documentation, what's the best way to implement a StorytellerStoriesRow SwiftUI view in my app?\"

  3. \"Help me troubleshoot this initialization error with Storyteller SDK: [paste your error]\"

  4. \"Using the Storyteller docs context, show me how to customize the theme of my StorytellerStoriesRow\"

  5. \"With the Storyteller documentation, help me implement analytics tracking for story views.\"

"},{"location":"AI/#additional-resources","title":"Additional Resources","text":""},{"location":"AdditionalMethods/","title":"Additional Methods","text":"

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

For dedicated topics, see:

"},{"location":"AdditionalMethods/#table-of-contents","title":"Table of Contents","text":""},{"location":"AdditionalMethods/#properties","title":"Properties","text":""},{"location":"AdditionalMethods/#delegate","title":"delegate","text":"

The delegate is responsible for things like fetching ads and handling in-app navigation. More detailed info can be found in Storyteller Delegates.

"},{"location":"AdditionalMethods/#modules","title":"modules","text":"

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.

"},{"location":"AdditionalMethods/#currentapikey","title":"currentApiKey","text":"

This is the current API key set when using Storyteller.shared.initialize(...).

"},{"location":"AdditionalMethods/#version","title":"version","text":"

This is the current SDK version (for example \"11.4.0\").

let version = Storyteller.shared.version\n
"},{"location":"AdditionalMethods/#isinitialized","title":"isInitialized","text":"

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\n
"},{"location":"AdditionalMethods/#ispresentingcontent","title":"isPresentingContent","text":"

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.

"},{"location":"AdditionalMethods/#isplayermuted","title":"isPlayerMuted","text":"

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\nfunc updateMuteIndicator() {\n    let isMuted = Storyteller.shared.isPlayerMuted\n    print(\"Player muted: \\(isMuted)\")\n}\n
"},{"location":"AdditionalMethods/#issearchenabled","title":"isSearchEnabled","text":"

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

"},{"location":"AdditionalMethods/#theme","title":"theme","text":"

This is the default fallback theming style used to render Story or Clips items in lists and activities launched from lists.

"},{"location":"AdditionalMethods/#user","title":"user","text":"

Allows setting or removing custom attributes for personalization and audience targeting. See Working with Users.

Storyteller.shared.user.setCustomAttribute(key: \"location\", value: \"New York\")\n
"},{"location":"AdditionalMethods/#eventtrackingoptions","title":"eventTrackingOptions","text":"

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.

"},{"location":"AdditionalMethods/#methods","title":"Methods","text":"

Most of the methods below are async and should be called from a Task or another async context.

"},{"location":"AdditionalMethods/#initialize","title":"initialize","text":"
try await Storyteller.shared.initialize(apiKey: \"YOUR_API_KEY\")\n

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:

Throws - if there is an issue with initialization.

"},{"location":"AdditionalMethods/#dismissplayer","title":"dismissPlayer","text":"
await Storyteller.shared.dismissPlayer(animated: true, dismissReason: \"host-navigation\")\n

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:

"},{"location":"AdditionalMethods/#opensearch","title":"openSearch","text":"
await Storyteller.shared.openSearch()\n

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.

"},{"location":"AdditionalMethods/#resumeplayer","title":"resumePlayer","text":"
Storyteller.shared.resumePlayer()\n

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.

"},{"location":"AdditionalMethods/#opensheet","title":"openSheet","text":"
try await Storyteller.shared.openSheet(id: \"sheet-id\")\n

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

"},{"location":"AdditionalMethods/#getstoriescount","title":"getStoriesCount","text":"
let storiesCount = await Storyteller.shared.getStoriesCount(for: [\"category-id\"])\n

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

"},{"location":"AdditionalMethods/#getclipscount","title":"getClipsCount","text":"
let clipsCount = await Storyteller.shared.getClipsCount(for: \"collection-id\")\n

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

"},{"location":"Ads/","title":"Ads","text":""},{"location":"Ads/#introduction","title":"Introduction","text":"

The Storyteller SDK supports displaying ads that can be created in the Storyteller CMS (First Party Ads), as well as Ads from Google Ad Manager, Google AdMob, VAST tags via SDK extensions developed by Storyteller, and Ads from other sources via custom implementation provided by the integrator.

Which source of ads is used can be configured on your behalf by a member of the Storyteller Delivery Team.

If Ads do not appear, follow the shared Ads troubleshooting route first to identify whether the last successful boundary belongs to the tenant strategy, app extension, external provider, or SDK rendering.

"},{"location":"Ads/#storyteller-first-party-ads","title":"Storyteller First Party Ads","text":"

If your tenant is configured to use Storyteller First Party Ads, which can be managed in the Storyteller CMS, then no changes to the Storyteller integration code are necessary. The Ads code is managed entirely within the Storyteller SDK.

"},{"location":"Ads/#storyteller-gam-sdk","title":"Storyteller GAM SDK","text":"

To use Ads from Google Ad Manager in Storyteller, first reach out to your Storyteller contact and they will assist you with setting up Google Ad Manager to traffic ads to Storyteller.

You will then need to use the Storyteller Google Ad Manager SDK extension to fetch the ads from Google Ad Manager.

To use this extension, first install it using Swift Package Manager or Cocoapods.

For Swift Package Manager, it is available on Github here:

https://github.com/getstoryteller/storyteller-gam-module-swift\n

For Cocoapods, first make sure to specify the sources for Cocoapods:

source 'https://github.com/getstoryteller/storyteller-sdk-ios-podspec.git'\nsource 'https://github.com/getstoryteller/storyteller-lottie-ios-podspec.git'\nsource 'https://cdn.cocoapods.org/'\n

The StorytellerGAMIntegration is available by importing this pod:

pod 'StorytellerGAMIntegration'\n
"},{"location":"Ads/#basic-setup","title":"Basic Setup","text":"

Make sure to import the same version of StorytellerSDK and StorytellerGAMIntegration.

Now initialize the extension as follows:

import StorytellerSDK\nimport StorytellerGAMIntegration\n\nlet configuration = StorytellerGAMModuleConfiguration(\n    adUnit: { requestInfo in\n        return \"YOUR_AD_UNIT_ID\"\n    }\n)\n

You will need to supply the following parameter:

Parameter Name Description adUnit A closure that returns the ID of the Ad unit in Google Ad Manager that will be used to serve the Storyteller Ads for the specific Ad request. This can be used for custom Ad units depending on the request context. bottomBannerAdUnit Optional closure that returns the Ad unit ID used specifically for the Clips bottom banner placement. Leave this nil if you don't plan to serve Clips bottom banner Ads.

Then pass the newly created instance of the extension to the modules property on the Storyteller instance:

let configuration = StorytellerGAMModuleConfiguration(\n    adUnit: { _ in \"YOUR_AD_UNIT_ID\" }\n)\nStoryteller.shared.modules = [StorytellerGAMModule(configuration: configuration)]\n

Our Showcase app uses this module to integrate ads - see the GAM module configuration in AppDelegate.setupStoryteller.

"},{"location":"Ads/#setup-with-dynamic-ad-unit-changes","title":"Setup with Dynamic Ad Unit Changes","text":"

Example for dynamic Ad unit changes when you want to use different Ad units for Stories and Clips:

import StorytellerSDK\nimport StorytellerGAMIntegration\n\nlet configuration = StorytellerGAMModuleConfiguration(\n    adUnit: { requestInfo in\n        switch requestInfo {\n        case .stories:\n            return \"/33813572/storyteller/stories\"\n        case .clips:\n            return \"/33813572/storyteller/clips\"\n        @unknown default:\n            return \"/33813572/storyteller/default\"\n        }\n    }\n)\n
"},{"location":"Ads/#setup-with-additional-parameters","title":"Setup with Additional Parameters","text":"

You can also supply optional parameters customNativeTemplateIds, publisherProvidedId, customKvps, and configureAdRequest if needed:

import GoogleMobileAds\nimport StorytellerSDK\nimport StorytellerGAMIntegration\n\nlet configuration = StorytellerGAMModuleConfiguration(\n    adUnit: { requestInfo in\n        switch requestInfo {\n        case .stories:\n            return \"/33813572/storyteller/stories\"\n        case .clips:\n            return \"/33813572/storyteller/clips\"\n        @unknown default:\n            return \"/33813572/storyteller/default\"\n        }\n    },\n    customNativeTemplateIds: StorytellerGAMModuleConfiguration.CustomNativeTemplateIds(\n        stories: \"YOUR_STORIES_TEMPLATE_ID\",\n        clips: \"YOUR_CLIPS_TEMPLATE_ID\"\n    ),\n    publisherProvidedId: {\n        \"YOUR_PUBLISHER_PROVIDED_ID\"\n    },\n    customKvps: {\n        [\n            \"YOUR_CUSTOM_KEY\": \"YOUR_CUSTOM_VALUE\",\n            \"YOUR_PRIVACY_KEY\": \"YOUR_PRIVACY_VALUE\"\n        ]\n    },\n    configureAdRequest: { _, request in\n        var targeting = request.customTargeting ?? [:]\n        targeting[\"host_app_context\"] = \"sports\"\n        request.customTargeting = targeting\n    }\n)\n

This example adds a host-owned GAM targeting value. You can also use configureAdRequest to await your app's Sliide, APS, Nimbus, or other bidder adapter and apply its response to the request before Storyteller starts loading the Ad.

Parameter Name Description customNativeTemplateIds If you have worked with the Storyteller Delivery team to setup Custom Native Ads, you will need to supply their IDs here. If you are only using Stories (but not Clips) it is only necessary to supply one property of this struct. publisherProvidedId Optional closure that returns the Publisher Provided ID (PPID) for Google Ad Manager audience targeting. Return the identifier your GAM setup expects, or nil to omit PPID. customKvps A closure that is called each time we request a new ad. The Storyteller GAM SDK passes a default set of KVPs to GAM to allow targeting based on the content of the Stories/Clips the user is viewing. If you have any additional parameters that you need to be able to target by, these should be passed here. Note that the SDK will not inherit any KVPs being set in the rest of your app. Do not pass PPID here; use publisherProvidedId for PPID. configureAdRequest Optional async main-actor closure called after Storyteller applies its request setup, default KVPs, customKvps, and publisherProvidedId, but before it loads the Google request. Storyteller awaits this closure before calling the Google load API. Use it for host-owned bidder setup or Google request fields that cannot be expressed as KVPs or PPID.

Storyteller default KVPs and customKvps are only sent when ad tracking is enabled. publisherProvidedId and configureAdRequest are host-controlled request customizations; return nil for PPID and avoid mutating the request when your app should not send those values. configureAdRequest runs on the main actor for full-screen native, custom-template, and banner-fallback GAM requests, and for Clips bottom-banner GAM requests. It is not automatically privacy-gated by Storyteller. Apply any consent, limited-ad-tracking, or regional privacy checks required by your app before mutating the request. Because Storyteller awaits this callback before loading the Google request, keep bidder work bounded and handle any timeout or cancellation fallback inside your app. Storyteller-owned GAM KVP names beginning with st are reserved; do not overwrite or remove them in the callback. If configureAdRequest is omitted, Storyteller builds and loads the request using the existing request behavior.

"},{"location":"Ads/#default-kvps","title":"Default KVPs","text":"

The Storyteller GAM SDK automatically sends a set of key-value pairs (KVPs) to Google Ad Manager to enable content-based targeting. These KVPs are only sent when ad tracking is enabled (enableAdTracking == true in the StorytellerEventTrackingOptions you pass to Storyteller.shared.initialize(...)).

For Stories:

KVP Key Description stCategories Categories associated with the current story stCurrentCategory Categories of the list containing the story stPlacement The placement identifier of the story stApiKey The current Storyteller API key stAdIndex The order of the ad within the story

For Clips:

KVP Key Description stCollection The identifier of the clip collection stClipCategories Categories associated with the current clip stNextClipCategories Categories of the next clip (if available) stApiKey The current Storyteller API key stAdIndex The order of the ad within the clip collection"},{"location":"Ads/#storyteller-vast-sdk","title":"Storyteller VAST SDK","text":"

The Storyteller VAST SDK extension requests vendor-neutral HTTPS VAST tags, resolves compatible inline and wrapper responses, selects playable linear media, and returns Storyteller-rendered fullscreen Ads through the standard module system.

The module is generic VAST support, not an ITV-specific integration. ITV is the first validated production-shaped scenario for the iOS VAST module, but the same module can be configured for any compatible VAST server.

To use this extension, first install it using Swift Package Manager or Cocoapods.

For Swift Package Manager, it is available on Github here:

https://github.com/getstoryteller/storyteller-vast-module-swift\n

For Cocoapods, first make sure to specify the sources for Cocoapods:

source 'https://github.com/getstoryteller/storyteller-sdk-ios-podspec.git'\nsource 'https://github.com/getstoryteller/storyteller-lottie-ios-podspec.git'\nsource 'https://cdn.cocoapods.org/'\n

The StorytellerVASTIntegration is available by importing this pod:

pod 'StorytellerVASTIntegration'\n
"},{"location":"Ads/#basic-setup_1","title":"Basic Setup","text":"

Make sure to import the same version of StorytellerSDK and StorytellerVASTIntegration.

import StorytellerSDK\nimport StorytellerVASTIntegration\n\nlet configuration = StorytellerVASTModuleConfiguration(\n    baseUrl: \"https://ads.example.com/vast\",\n    requestParameters: { _ in\n        [\n            \"placement\": \"storyteller\"\n        ]\n    },\n    urlFormat: .queryString\n)\n\nStoryteller.shared.modules = [StorytellerVASTModule(configuration: configuration)]\n

You will need to supply the following parameters:

Parameter Name Description baseUrl HTTPS base URL of the VAST tag endpoint. requestParameters Closure called for each Ad request. Return the key-value parameters your VAST provider needs for the specific Stories or Clips request context. urlFormat Optional serialization strategy. Use .pathSegment to append parameters as /key=value path segments, or .queryString to append them as query parameters. Defaults to .pathSegment. diagnosticsHandler Optional closure that receives request, parse, wrapper, media-selection, mapping, completion, and failure diagnostics.

The generated VAST tag URL must use HTTPS and be no longer than 2,048 bytes. The module supports compatible VAST 2.x, 3.x, and 4.x linear video responses, including wrappers up to the module depth limit. Unsupported creative types such as VPAID JavaScript are ignored during media selection.

The VAST module supports fullscreen Story and Clip Ads. It does not serve Clips bottom banner Ads.

"},{"location":"Ads/#gam-vast-setup","title":"GAM VAST Setup","text":"

If you use Google Ad Manager to serve VAST video tags, use StorytellerGAMVASTModule. This module is part of StorytellerVASTIntegration; it does not use the Google Mobile Ads SDK or IMA SDK. It builds a GAM VAST tag request and then uses the same Storyteller VAST request, parsing, tracking, and fullscreen Player flow as StorytellerVASTModule.

import StorytellerSDK\nimport StorytellerVASTIntegration\n\nlet configuration = StorytellerGAMVASTModuleConfiguration(\n    adUnit: { requestInfo in\n        switch requestInfo {\n        case .stories:\n            return \"/33813572/storyteller/stories_vast\"\n        case .clips:\n            return \"/33813572/storyteller/clips_vast\"\n        @unknown default:\n            return \"/33813572/storyteller/default_vast\"\n        }\n    },\n    descriptionUrl: { _ in\n        \"https://example.com/storyteller-video\"\n    },\n    contentUrl: { _ in\n        \"https://example.com/storyteller-video\"\n    },\n    customParams: { _ in\n        [\n            \"sliide_content_category\": \"sports\"\n        ]\n    }\n)\n\nStoryteller.shared.modules = [StorytellerGAMVASTModule(configuration: configuration)]\n

You will need to supply the following parameters:

Parameter Name Description adUnit Required closure that returns the GAM Ad Unit path for the current Ad request. This becomes the GAM iu parameter. descriptionUrl Required closure that returns the canonical HTTPS URL describing the video content or Player context. This becomes the GAM description_url parameter. contentUrl Optional closure that returns the page or content URL to send as the GAM url parameter. Return nil to omit it. customParams Optional closure that returns GAM custom targeting parameters. The SDK serializes these into GAM's cust_params value, so pass unencoded keys and values. tagParameters Optional closure that returns extra top-level GAM VAST tag parameters. These are applied after the SDK-generated GAM parameters, so a matching key overrides the generated value. diagnosticsHandler Optional closure that receives the same VAST diagnostics events as StorytellerVASTModule.

StorytellerGAMVASTModule generates a request to https://pubads.g.doubleclick.net/gampad/ads with query-string parameters. It supplies iu, output=vast, env=vp, gdfp_req=1, sz, correlator, description_url, optional url, vpa=auto, vpmute, optional cust_params, and the SDK-owned VAST bid parameters listed below. Use tagParameters for any additional GAM VAST tag parameters required by your ad server setup.

The SDK serializes sz as <width>x<height> in physical pixels, with a lowercase x and no spaces or px suffix. It derives this from the active fullscreen Player window or screen and omits sz only when it cannot resolve a reliable non-zero size. customParams are serialized inside cust_params; for example, [\"sliide_content_category\": \"sports\"] becomes sliide_content_category=sports inside the cust_params value before the final request URL is encoded.

GAM VAST is VAST-backed, not Google Mobile Ads or IMA-backed. The module sets adSource to .custom(\"vast\"), so Google paid ad analytics events are not emitted for GAM VAST requests.

See VAST and GAM VAST Parameter Tables for the parameters the SDK sets internally, where client-provided values are applied, and which values can be overridden.

The GAM VAST module supports fullscreen Story and Clip Ads. It does not serve Clips bottom banner Ads.

"},{"location":"Ads/#vast-and-gam-vast-parameter-tables","title":"VAST and GAM VAST Parameter Tables","text":"

Use these tables to decide whether a value belongs in generic VAST requestParameters, GAM VAST customParams, or GAM VAST tagParameters.

Surface Client Parameter Path SDK Behavior Override Behavior Generic VAST tag parameters StorytellerVASTModuleConfiguration.requestParameters The SDK builds the Sliide VAST bid parameters first, then merges the returned key-value pairs and serializes the final result using the configured urlFormat. It does not add GAM-specific parameters. Matching keys in requestParameters override SDK-set Sliide VAST bid parameters. GAM VAST custom targeting StorytellerGAMVASTModuleConfiguration.customParams The SDK encodes the returned key-value pairs into GAM's cust_params value. Change individual custom targeting values in customParams, or replace the generated cust_params by returning cust_params from tagParameters. GAM VAST top-level parameters StorytellerGAMVASTModuleConfiguration.tagParameters The SDK builds GAM VAST parameters and Sliide VAST bid parameters first, then applies these top-level parameters. Matching keys in tagParameters are the final override layer. Sliide VAST Bid Parameter Applies To Value / Source Static or Dynamic Client Override adtype Generic VAST and GAM VAST 13 Static Generic: requestParameters[\"adtype\"]; GAM VAST: tagParameters[\"adtype\"] plcmt Generic VAST and GAM VAST 3 Static Generic: requestParameters[\"plcmt\"]; GAM VAST: tagParameters[\"plcmt\"] vw Generic VAST and GAM VAST Player width in physical pixels, for example 1080 Dynamic; omitted when no reliable size is available Generic: requestParameters[\"vw\"]; GAM VAST: tagParameters[\"vw\"] vh Generic VAST and GAM VAST Player height in physical pixels, for example 1920 Dynamic; omitted when no reliable size is available Generic: requestParameters[\"vh\"]; GAM VAST: tagParameters[\"vh\"] vminl Generic VAST and GAM VAST 5 Static Generic: requestParameters[\"vminl\"]; GAM VAST: tagParameters[\"vminl\"] vmaxl Generic VAST and GAM VAST 30 Static Generic: requestParameters[\"vmaxl\"]; GAM VAST: tagParameters[\"vmaxl\"] vfmt Generic VAST and GAM VAST 1 for MP4 playable media format on iOS Static Generic: requestParameters[\"vfmt\"]; GAM VAST: tagParameters[\"vfmt\"] vadFmt Generic VAST and GAM VAST 2+3+8 Static Generic: requestParameters[\"vadFmt\"]; GAM VAST: tagParameters[\"vadFmt\"] vplay Generic VAST and GAM VAST 6 for muted autoplay, 5 for sound-on autoplay Dynamic; falls back to 6 when mute state is unavailable Generic: requestParameters[\"vplay\"]; GAM VAST: tagParameters[\"vplay\"] vskip Generic VAST and GAM VAST 1 Static Generic: requestParameters[\"vskip\"]; GAM VAST: tagParameters[\"vskip\"] vpos Generic VAST and GAM VAST 0 Static Generic: requestParameters[\"vpos\"]; GAM VAST: tagParameters[\"vpos\"] vcom Generic VAST and GAM VAST 0 Static Generic: requestParameters[\"vcom\"]; GAM VAST: tagParameters[\"vcom\"] vcont Generic VAST and GAM VAST 1 Static Generic: requestParameters[\"vcont\"]; GAM VAST: tagParameters[\"vcont\"] vtype Generic VAST and GAM VAST 1 Static Generic: requestParameters[\"vtype\"]; GAM VAST: tagParameters[\"vtype\"] vminbtr Generic VAST and GAM VAST 600 Static Generic: requestParameters[\"vminbtr\"]; GAM VAST: tagParameters[\"vminbtr\"] vmaxbtr Generic VAST and GAM VAST 8000 Static Generic: requestParameters[\"vmaxbtr\"]; GAM VAST: tagParameters[\"vmaxbtr\"]

vw and vh are separate integer values in physical pixels. Do not include px, point units, spaces, or an x separator in those values. For a fullscreen player measured as 1080 by 1920 physical pixels, the SDK sends vw=1080 and vh=1920.

Pure generic VAST does not use GAM cust_params. If you need GAM custom targeting such as a content category, pass it through GAM VAST customParams so the SDK encodes it into cust_params.

GAM VAST Top-Level Parameter Set By Default Default Source Value Type Client Override output Yes SDK sets vast. Static tagParameters[\"output\"] env Yes SDK sets vp. Static tagParameters[\"env\"] gdfp_req Yes SDK sets 1. Static tagParameters[\"gdfp_req\"] iu Yes adUnit closure. Dynamic per Ad request tagParameters[\"iu\"] sz When a reliable non-zero size is available. SDK derives active fullscreen Player window or screen physical pixels as <width>x<height>. Dynamic per request context tagParameters[\"sz\"] correlator Yes SDK generates a fresh value for each request. Dynamic per Ad request tagParameters[\"correlator\"] description_url Yes descriptionUrl closure. Dynamic per Ad request tagParameters[\"description_url\"] url When non-nil contentUrl closure. Dynamic per Ad request tagParameters[\"url\"] vpa Yes SDK sets auto. Static tagParameters[\"vpa\"] vpmute Yes SDK sets 1 when the Player is muted and 0 when unmuted. Dynamic per request context tagParameters[\"vpmute\"] cust_params When customParams returns at least one key-value pair. Encoded customParams output. Dynamic per Ad request tagParameters[\"cust_params\"] GAM VAST Custom Parameter Recommended Client Path Encoded Location Notes sliide_content_category customParams[\"sliide_content_category\"] Inside cust_params. Use this for Sliide content category targeting. Additional custom KVPs customParams Inside cust_params. Pass unencoded keys and values; the SDK handles GAM cust_params encoding."},{"location":"Ads/#vast-url-formats","title":"VAST URL Formats","text":"

Use .pathSegment when your VAST server expects parameters appended as path segments:

let configuration = StorytellerVASTModuleConfiguration(\n    baseUrl: \"https://ads.example.com/vast\",\n    requestParameters: { _ in\n        [\n            \"placement\": \"stories\",\n            \"adIndex\": \"1\"\n        ]\n    },\n    urlFormat: .pathSegment\n)\n

This produces a request shaped like:

https://ads.example.com/vast/placement=stories/adIndex=1\n

Use .queryString when your VAST server expects standard query parameters:

let configuration = StorytellerVASTModuleConfiguration(\n    baseUrl: \"https://ads.example.com/vast\",\n    requestParameters: { _ in\n        [\n            \"placement\": \"stories\",\n            \"adIndex\": \"1\"\n        ]\n    },\n    urlFormat: .queryString\n)\n

This produces a request shaped like:

https://ads.example.com/vast?placement=stories&adIndex=1\n

The SDK encodes parameter keys and values for the selected format. Pass unencoded values from your callback.

"},{"location":"Ads/#vast-support-in-the-first-release","title":"VAST Support in the First Release","text":"

The first iOS release supports:

The first iOS release does not support:

"},{"location":"Ads/#vast-tracking-and-skip-behavior","title":"VAST Tracking and Skip Behavior","text":"

When a VAST response contains multiple URLs for the same supported tracking event, the SDK preserves and fires all of them for the matching Storyteller playback event.

VAST skip tracking maps to the Storyteller skipped-Ad flow. VAST skipoffset is converted to an ad-specific non-skippable duration in the Storyteller Player. When skipoffset is present, it controls the countdown for that VAST Ad; when it is absent, the SDK uses the tenant's CMS-configured non-skippable Ads behavior.

VAST <Error> URLs are reported by the VAST module when the SDK cannot request, parse, resolve, select media for, or map a VAST Ad. These failures cause the module to fail safely so Storyteller can continue through the normal module fallback flow.

"},{"location":"Ads/#vast-branded-presentation-metadata","title":"VAST Branded Presentation Metadata","text":"

VAST ads can provide Storyteller presentation metadata through Extension type=\"storyteller:ad-ui\". The SDK reads CtaText and AdvertiserName from the StorytellerAdUi child element:

<Extension type=\"storyteller:ad-ui\">\n  <StorytellerAdUi>\n    <CtaText>Shop now</CtaText>\n    <AdvertiserName>Example Brand</AdvertiserName>\n  </StorytellerAdUi>\n</Extension>\n

The SDK resolves the final presentation values with this priority:

Field Resolution priority CTA text VAST extension CtaText -> backend default ads.presentationDefaults.vast.ctaText -> Learn more Advertiser display name VAST extension AdvertiserName -> backend default ads.presentationDefaults.vast.advertiserName -> VAST <Advertiser> -> VAST <AdTitle>

CTA text is only shown when the VAST ad has a non-empty <ClickThrough> destination. VAST <Icon> elements are reserved for industry, privacy, or program overlays and are not used as brand logos.

"},{"location":"Ads/#vast-icon-overlays","title":"VAST Icon Overlays","text":"

For fullscreen Story and Clip VAST ads, the SDK renders one compatible static-resource <Icon> overlay per ad only when the icon has program=\"AdChoices\". Non-AdChoices icons, <IFrameResource> icons, and <HTMLResource> icons are parsed for diagnostics but are not rendered.

The icon is rendered inside the video frame, including landscape videos that are aspect-fitted inside the Player. The SDK honors VAST xPosition values of left, right, or a numeric x-coordinate, and yPosition values of top, bottom, or a numeric y-coordinate. The overlay has a fixed 24pt height and preserves the static resource aspect ratio for its width. VAST offset and duration values control when the icon appears, IconViewTracking is fired once when it first becomes visible, and IconClickTracking is fired when the icon is tapped. If IconClickThrough is present, tapping the icon opens that destination externally.

"},{"location":"Ads/#setup-with-dynamic-parameters","title":"Setup with Dynamic Parameters","text":"

Use StorytellerAdRequestInfo to provide different parameters for Stories and Clips:

let configuration = StorytellerVASTModuleConfiguration(\n    baseUrl: \"https://ads.example.com/vast\",\n    requestParameters: { requestInfo in\n        switch requestInfo {\n        case let .stories(placement, categories, story, adIndex):\n            return [\n                \"placement\": placement,\n                \"categories\": categories.joined(separator: \",\"),\n                \"storyCategories\": story.categories.map(\\.externalId).joined(separator: \",\"),\n                \"adIndex\": \"\\(adIndex)\"\n            ]\n        case let .clips(collection, clip, nextClip, adIndex):\n            return [\n                \"collection\": collection,\n                \"clipCategories\": clip.categories.map(\\.externalId).joined(separator: \",\"),\n                \"nextClipCategories\": nextClip?.categories.map(\\.externalId).joined(separator: \",\") ?? \"\",\n                \"adIndex\": \"\\(adIndex)\"\n            ]\n        @unknown default:\n            return [:]\n        }\n    },\n    urlFormat: .queryString\n)\n
"},{"location":"Ads/#storyteller-admob-sdk","title":"Storyteller AdMob SDK","text":"

AdMob support uses the same StorytellerGAMIntegration artifact but a different module entry point. Only one ads integration module can be used at a time.

Due to AdMob limitations, banner Ads cannot be served from the same Ad unit as native Ads. adUnit is always used for native Ads, while bannerAdUnit is used for fullscreen banner Ads.

enableBannerAdPriority only affects this fullscreen fallback order. It has no effect when bannerAdUnit is nil, and it does not change Clips bottom banner behavior configured through bottomBannerAdUnit.

"},{"location":"Ads/#basic-setup_2","title":"Basic Setup","text":"
import StorytellerSDK\nimport StorytellerGAMIntegration\n\nlet configuration = StorytellerAdMobModuleConfiguration(\n    adUnit: { requestInfo in\n        return \"YOUR_NATIVE_AD_UNIT_ID\"\n    },\n    bannerAdUnit: { requestInfo in\n        return \"YOUR_BANNER_AD_UNIT_ID\"\n    },\n    bottomBannerAdUnit: { requestInfo in\n        return \"YOUR_BOTTOM_BANNER_AD_UNIT_ID\"\n    }\n)\n\nStoryteller.shared.modules = [StorytellerAdMobModule(configuration: configuration)]\n
Parameter Name Description adUnit Required closure that returns the native Ad unit ID. bannerAdUnit Optional closure that returns a fullscreen banner Ad unit ID. If supplied, the module can use it as the banner fallback path or the banner-first path when enableBannerAdPriority is enabled. bottomBannerAdUnit Optional closure that returns the Ad unit ID used specifically for the Clips bottom banner placement. Leave this nil if you don't plan to serve Clips bottom banner Ads. customKvps Optional closure that returns custom key-value pairs to attach to AdMob requests for targeting. enableBannerAdPriority Optional flag that changes the fullscreen Ad loading order to banner first, then native fallback. This flag only has an effect when bannerAdUnit is configured.

For a complete integration example, see our Showcase app code here.

"},{"location":"Ads/#setup-with-banner-priority-enabled","title":"Setup with Banner Priority Enabled","text":"
import StorytellerSDK\nimport StorytellerGAMIntegration\n\nlet configuration = StorytellerAdMobModuleConfiguration(\n    adUnit: { _ in\n        \"YOUR_NATIVE_AD_UNIT_ID\"\n    },\n    bannerAdUnit: { _ in\n        \"YOUR_BANNER_AD_UNIT_ID\"\n    },\n    enableBannerAdPriority: true\n)\n\nStoryteller.shared.modules = [StorytellerAdMobModule(configuration: configuration)]\n
"},{"location":"Ads/#setup-with-dynamic-ad-unit-changes_1","title":"Setup with Dynamic Ad Unit Changes","text":"
import StorytellerSDK\nimport StorytellerGAMIntegration\n\nlet configuration = StorytellerAdMobModuleConfiguration(\n    adUnit: { requestInfo in\n        switch requestInfo {\n        case .stories:\n            return \"YOUR_STORIES_NATIVE_AD_UNIT_ID\"\n        case .clips:\n            return \"YOUR_CLIPS_NATIVE_AD_UNIT_ID\"\n        @unknown default:\n            return \"YOUR_DEFAULT_NATIVE_AD_UNIT_ID\"\n        }\n    },\n    bannerAdUnit: { requestInfo in\n        switch requestInfo {\n        case .stories:\n            return \"YOUR_STORIES_BANNER_AD_UNIT_ID\"\n        case .clips:\n            return \"YOUR_CLIPS_BANNER_AD_UNIT_ID\"\n        @unknown default:\n            return \"YOUR_DEFAULT_BANNER_AD_UNIT_ID\"\n        }\n    },\n    bottomBannerAdUnit: { requestInfo in\n        switch requestInfo {\n        case .stories:\n            return \"YOUR_STORIES_BOTTOM_BANNER_AD_UNIT_ID\"\n        case .clips:\n            return \"YOUR_CLIPS_BOTTOM_BANNER_AD_UNIT_ID\"\n        @unknown default:\n            return \"YOUR_DEFAULT_BOTTOM_BANNER_AD_UNIT_ID\"\n        }\n    },\n    customKvps: {\n        [\"appmode\": \"prod\"]\n    },\n    enableBannerAdPriority: true\n)\n
"},{"location":"Ads/#admob-test-ids-for-local-validation","title":"AdMob Test IDs for Local Validation","text":"

The Showcase app uses the following sample AdMob unit IDs for local validation. Use your own production IDs outside test and debug flows.

Placement Sample AdMob unit ID Native ca-app-pub-3940256099942544/3986624511 Native video ca-app-pub-3940256099942544/2521693316 Fullscreen banner fallback ca-app-pub-3940256099942544/2435281174 Clips bottom banner ca-app-pub-3940256099942544/2934735716"},{"location":"Ads/#admob-vs-gam-at-a-glance","title":"AdMob vs GAM at a Glance","text":"Concern GAM AdMob Module entry point StorytellerGAMModule StorytellerAdMobModule Native-specific options Supports customNativeTemplateIds for custom native Ads Uses standard native Ads and does not expose customNativeTemplateIds Fullscreen banner setup No separate bannerAdUnit parameter Uses optional bannerAdUnit; this can be banner fallback or banner-first when enableBannerAdPriority is true Shared options Supports bottomBannerAdUnit, publisherProvidedId, customKvps, and configureAdRequest Supports bottomBannerAdUnit, customKvps, and enableBannerAdPriority"},{"location":"Ads/#mutual-exclusivity","title":"Mutual Exclusivity","text":"

StorytellerGAMModule and StorytellerAdMobModule are mutually exclusive. Configure only one of them at a time.

StorytellerVASTModule and StorytellerGAMVASTModule are separate fullscreen Ads modules. If you use either with any other Ads module, order the Storyteller.shared.modules array deliberately because the SDK asks modules for Ads in order and falls back to the next module when one throws.

"},{"location":"Ads/#bottom-banner-ads","title":"Bottom Banner Ads","text":"

The Clips Player supports bottom banner Ads rendered as standard banner views added to the hierarchy below the video view. Bottom banner Ads are disabled when StorytellerClipCollectionConfiguration.adConfiguration is omitted or set to nil, and for new StorytellerClipsAdConfiguration instances. To opt a Clips presentation into bottom banner Ads, pass StorytellerClipsAdConfiguration(bottomBannerEnabled: true) through StorytellerClipCollectionConfiguration.adConfiguration.

When using the GAM or AdMob module, supply bottomBannerAdUnit in the corresponding configuration to fetch bottom banner Ads. Opting in locally does not force Ads on: the tenant feed response must still enable the placement with showBottomBannerAd == true, and the active Ads module must support it.

Storyteller First Party Ads, StorytellerVASTModule, and StorytellerGAMVASTModule do not support bottom banner Ads.

"},{"location":"Ads/#clips-opening-pre-roll-ads","title":"Clips Opening Pre-Roll Ads","text":"

If your tenant is configured for Clips Ads with initialIndex = 0, individual Clips presentations can opt into an opening fullscreen Ad before the first Clip is played by passing StorytellerClipsAdConfiguration(preRollEnabled: true) through StorytellerClipCollectionConfiguration.adConfiguration.

let configuration = StorytellerClipCollectionConfiguration(\n    collectionId: \"top-plays\",\n    adConfiguration: StorytellerClipsAdConfiguration(preRollEnabled: true)\n)\n

Opening pre-roll is disabled when StorytellerClipCollectionConfiguration.adConfiguration is omitted or set to nil, and for new StorytellerClipsAdConfiguration instances. Opting in locally does not force Ads on: Clips Ads must still be available for the tenant, and the remote Clips Ad strategy must use initialIndex = 0. The request uses the first opened content Clip as the current Clip context and sends adIndex = 1, which maps to the default stAdIndex = 1 value for Google Ad Manager and AdMob integrations.

When a CMS-configured opening pre-roll timeout is reached before the Ad loads, the Player starts the content Clip and ignores any late opening pre-roll result. Later between-Clip Ads continue to use the normal Clips ad cadence and increment from the next Ad index.

"},{"location":"Ads/#ad-request-information","title":"Ad Request Information","text":"

Note: This section is only relevant if you're implementing a custom Ads solution or building VAST request parameters. If you're using Storyteller First Party Ads, StorytellerGAMModule, or StorytellerAdMobModule, you don't need to work with this directly.

If your StorytellerModule (or StorytellerDelegate) provides integrating-app ads, set adSource to declare the source used by your implementation.

Setting adSource to .gam or .admob enables Google paid ad analytics events. See Ad Events.

StorytellerGAMModule, StorytellerAdMobModule, StorytellerVASTModule, and StorytellerGAMVASTModule set adSource automatically.

When implementing custom Ads, you'll receive context about the Ad request through the StorytellerAdRequestInfo enum. This provides information about what content the Ad will be displayed for.

"},{"location":"Ads/#storytelleradrequestinfo","title":"StorytellerAdRequestInfo","text":"

The StorytellerAdRequestInfo enum has two cases:

"},{"location":"Ads/#iteminfo","title":"ItemInfo","text":"

Each case includes an ItemInfo struct that contains:

"},{"location":"Ads/#non-skippable-ads","title":"Non Skippable Ads","text":"

Our Player can enforce a period of time during which ads can't be skipped. When enabled, user interactions that would skip a Story or Clip Ad won't be allowed for that duration. This feature can be configured in the CMS.

"},{"location":"Analytics/","title":"Analytics","text":""},{"location":"Analytics/#table-of-contents","title":"Table of Contents","text":"
  1. Event Types
  2. Story Events
  3. Clip Events
  4. List Tile Events
  5. Card Events
  6. Ad Events
  7. Playback Events
  8. Sheet Events
  9. Search Events
  10. Event Data
"},{"location":"Analytics/#event-types","title":"Event Types","text":"

These are the various events which are triggered from within the SDK. Each event is a member of the StorytellerUserActivity.EventType enumeration. Follow Integrate Analytics to retain the delegate, choose tracking options, forward events, and verify the integration.

For a concrete analytics integration, see the Showcase forwarding implementation in StorytellerTrackingDelegate.

In the below discussion, \"completing\" a Page refers to allowing the timer to expire - so this would correspond to watching all of an Image Page for the duration set for it (default 15s) or watching all of a video.

"},{"location":"Analytics/#story-events","title":"Story Events","text":"

The following properties are included in Story-related events:

"},{"location":"Analytics/#opened-story","title":"Opened Story","text":"

This event is recorded in the following scenarios:

Whenever an Opened Story event occurs, additional event data specific to this event includes storyReadStatus, categories, categoryDetails, storyIndex, and openedReason.

"},{"location":"Analytics/#opened-page","title":"Opened Page","text":"

This event is recorded whenever a user views content from a page.

Opened Page is one of the most important events to track as it is equal to a video start, one of the most important measures of engagement. By tracking this event, you can monitor valuable information about user engagement with your app.

Whenever an Opened Page event occurs, additional event data specific to this event includes openedReason.

"},{"location":"Analytics/#dismissed-story","title":"Dismissed Story","text":"

This event is recorded in the following scenarios:

Whenever a Dismissed Story event occurs, additional event data specific to this event includes dismissedReason, durationViewed, and pagesViewedCount.

"},{"location":"Analytics/#skipped-story","title":"Skipped Story","text":"

This event is recorded when a user swipes left to go to the next story (not on the last page).

Note: This event is not fired when the user swipes on the last page of a story. In that case, the user has consumed all pages and is naturally moving to the next story or dismissing the player, which is not considered a \"skip\".

"},{"location":"Analytics/#skipped-page","title":"Skipped Page","text":"

This event is recorded when a user taps to go to the next page before completing the current page.

"},{"location":"Analytics/#completed-story","title":"Completed Story","text":"

This event is recorded at the same time as OpenedPage for the final page in a story.

"},{"location":"Analytics/#completed-page","title":"Completed Page","text":"

This event is recorded when a user watches a page to completion (i.e. the timer for that page finishes.)

"},{"location":"Analytics/#action-button-tapped","title":"Action Button Tapped","text":"

This event is recorded when a user taps an action button on a page to open a link.

Whenever an Action Button Tapped event occurs, additional event data specific to this event includes actionText.

"},{"location":"Analytics/#share-button-tapped","title":"Share Button Tapped","text":"

This event is recorded when a user taps the share button on a page.

Whenever a Share Button Tapped event occurs, additional event data specific to this event includes shareMethod.

"},{"location":"Analytics/#previous-story","title":"Previous Story","text":"

This event is recorded when:

"},{"location":"Analytics/#previous-page","title":"Previous Page","text":"

This event is recorded when a user taps back to go to a previous page in the story.

"},{"location":"Analytics/#share-success","title":"Share Success","text":"

This event is recorded when a user selects a sharing method from the system dialog.

Whenever a Share Success event occurs, additional event data specific to this event includes shareMethod.

"},{"location":"Analytics/#voted-poll","title":"Voted Poll","text":"

This event is recorded when user votes in a poll.

Whenever a Voted Poll event occurs, additional event data specific to this event includes pollAnswerId.

"},{"location":"Analytics/#trivia-quiz-question-answered","title":"Trivia Quiz Question Answered","text":"

This event is recorded when a user answers a question in a trivia quiz.

Whenever a Trivia Quiz Question Answered event occurs, additional event data specific to this event includes triviaQuizId, triviaQuizTitle, triviaQuizQuestionId, and triviaQuizAnswerId.

"},{"location":"Analytics/#trivia-quiz-completed","title":"Trivia Quiz Completed","text":"

This event is recorded when a user completes a trivia quiz.

Whenever a Trivia Quiz Completed event occurs, additional event data specific to this event includes triviaQuizId, triviaQuizTitle, and triviaQuizScore.

"},{"location":"Analytics/#story-instructions-screen-viewed","title":"Story Instructions Screen Viewed","text":"

This event is recorded when:

Whenever a Story Instructions Screen Viewed event occurs, additional event data specific to this event includes storyReadStatus and openedReason.

"},{"location":"Analytics/#muted-story","title":"Muted Story","text":"

This event is recorded when:

"},{"location":"Analytics/#unmuted-story","title":"Unmuted Story","text":"

This event is recorded when:

"},{"location":"Analytics/#clip-events","title":"Clip Events","text":"

The following properties are included in all Clip-related events:

The following additional properties may be included when available:

"},{"location":"Analytics/#opened-clip","title":"Opened Clip","text":"

This event is recorded when:

Whenever an Opened Clip event occurs, additional event data specific to this event includes openedReason.

"},{"location":"Analytics/#dismissed-clip","title":"Dismissed Clip","text":"

This event is recorded when:

This event does not fire when the user is not at the top of the Clip Category stack. Whenever a Dismissed Clip event occurs, additional event data specific to this event includes dismissedReason, durationViewed, clipsViewed, and loopsViewed.

"},{"location":"Analytics/#next-clip","title":"Next Clip","text":"

This event is recorded when:

"},{"location":"Analytics/#previous-clip","title":"Previous Clip","text":"

This event is recorded when:

"},{"location":"Analytics/#completed-loop","title":"Completed Loop","text":"

This event is recorded when:

Whenever a Completed Loop event occurs, additional event data specific to this event includes completionType.

Note: For live clips this event will never be fired.

"},{"location":"Analytics/#action-button-tapped_1","title":"Action Button Tapped","text":"

This event is recorded when:

Whenever an Action Button Tapped event occurs, additional event data specific to this event includes actionText, actionClass, actionIndex, tappedClipActionText, tappedClipActionUrl, and tappedClipActionType.

"},{"location":"Analytics/#share-button-tapped_1","title":"Share Button Tapped","text":"

This event is recorded when:

"},{"location":"Analytics/#share-success_1","title":"Share Success","text":"

This event is recorded when:

Whenever a Share Success event occurs, additional event data specific to this event includes shareMethod.

"},{"location":"Analytics/#paused-clip","title":"Paused Clip","text":"

This event is recorded when:

Note: For live clips this event will never be fired, as pausing/resuming live clips is not supported.

"},{"location":"Analytics/#resumed-clip","title":"Resumed Clip","text":"

This event is recorded when:

Note: For live clips this event will never be fired, as pausing/resuming live clips is not supported.

"},{"location":"Analytics/#scrubbed-clip","title":"Scrubbed Clip","text":"

This event is recorded when:

Whenever a Scrubbed Clip event occurs, additional event data specific to this event includes openedReason, startPosition, endPosition, and scrubDirection.

"},{"location":"Analytics/#liked-clip","title":"Liked Clip","text":"

This event is recorded when:

"},{"location":"Analytics/#unliked-clip","title":"Unliked Clip","text":"

This event is recorded when:

"},{"location":"Analytics/#finished-clip","title":"Finished Clip","text":"

This event is recorded when:

Whenever a Finished Clip event occurs, additional event data specific to this event includes loopsViewed, durationViewed, and completionType.

"},{"location":"Analytics/#opened-category","title":"Opened Category","text":"

This event is recorded when:

Note: This event is not fired when opening the top level of a collection - only when navigating to a specific category.

"},{"location":"Analytics/#dismissed-category","title":"Dismissed Category","text":"

This event is recorded when:

This event does not fire when dismissing the top level collection

"},{"location":"Analytics/#follow-category","title":"Follow Category","text":"

This event is recorded when:

"},{"location":"Analytics/#unfollow-category","title":"Unfollow Category","text":"

This event is recorded when:

"},{"location":"Analytics/#followable-category-tapped","title":"Followable Category Tapped","text":"

This event is recorded when:

"},{"location":"Analytics/#enable-captions","title":"Enable Captions","text":"

This event is recorded when:

"},{"location":"Analytics/#disable-captions","title":"Disable Captions","text":"

This event is recorded when:

"},{"location":"Analytics/#muted-clip","title":"Muted Clip","text":"

This event is recorded when:

"},{"location":"Analytics/#unmuted-clip","title":"Unmuted Clip","text":"

This event is recorded when:

"},{"location":"Analytics/#followable-category-limit-shown","title":"Followable Category Limit Shown","text":"

This event is recorded when:

Whenever a Followable Category Limit Shown event occurs, additional event data specific to this event includes followableCategoryLimitDialogue, followableCategoryLimitActionText, and followableCategoryLimitActionUrl.

"},{"location":"Analytics/#followable-category-limit-action-button-tapped","title":"Followable Category Limit Action Button Tapped","text":"

This event is recorded when:

Whenever a Followable Category Limit Action Button Tapped event occurs, additional event data specific to this event includes followableCategoryLimitDialogue, followableCategoryLimitActionText, and followableCategoryLimitActionUrl.

"},{"location":"Analytics/#followable-category-limit-dismissed","title":"Followable Category Limit Dismissed","text":"

This event is recorded when:

Whenever a Followable Category Limit Dismissed event occurs, additional event data specific to this event includes followableCategoryLimitDialogue, followableCategoryLimitActionText, and followableCategoryLimitActionUrl.

"},{"location":"Analytics/#list-tile-events","title":"List Tile Events","text":""},{"location":"Analytics/#tile-visible","title":"Tile Visible","text":"

This event is recorded when a Story or Clip tile becomes visible in a Storyteller list row or grid.

It is recorded in the following scenarios:

This event is not recorded again while the same tile remains continuously visible, and it is not recorded just because the app returns from the background or the Story/Clip Player is dismissed if the same visible tiles remain and the list did not reload or scroll.

Whenever a Tile Visible event occurs, additional event data specific to this event includes tileIndex. Story tile events include storyId, storyTitle, categories, and context when available. Clip tile events include clipId, clipTitle, collection, categories, and context when available.

"},{"location":"Analytics/#card-events","title":"Card Events","text":"

The following properties are included in all Card-related events:

The following additional properties are included on specific card video events:

"},{"location":"Analytics/#card-viewed","title":"Card Viewed","text":"

This event is recorded when:

"},{"location":"Analytics/#card-tapped","title":"Card Tapped","text":"

This event is recorded when:

"},{"location":"Analytics/#card-video-started","title":"Card Video Started","text":"

This event is recorded when:

This event is only emitted for video cards.

Whenever a Card Video Started event occurs, additional event data specific to this event includes videoStartReason.

For Card Video Started, videoStartReason is natural for the first visible playback start of the current Card session and loop when the same visible Card naturally restarts after a completed loop.

"},{"location":"Analytics/#card-video-heartbeat","title":"Card Video Heartbeat","text":"

This event is recorded when:

This event is only emitted for video cards.

Whenever a Card Video Heartbeat event occurs, additional event data specific to this event includes durationViewed.

For Card Video Heartbeat, durationViewed is reported in milliseconds, counts active playback only, accumulates through pauses, buffering, backgrounding, and other interruptions within the same loop, and resets when the video starts a new loop.

"},{"location":"Analytics/#card-video-completed","title":"Card Video Completed","text":"

This event is recorded when:

This event is only emitted for video cards.

Whenever a Card Video Completed event occurs, additional event data specific to this event includes durationViewed.

For Card Video Completed, durationViewed is the active playback duration of the completed loop in milliseconds.

"},{"location":"Analytics/#card-audio-toggled","title":"Card Audio Toggled","text":"

This event is recorded when:

This event is only emitted for video Cards where audio can be controlled. It is not emitted for no-audio Cards, behavior-locked muted Cards, inactive Cards, or interruption-forced mutes.

Whenever a Card Audio Toggled event occurs, additional event data specific to this event includes audioToggleFrom, audioToggleTo, and isMuted. isMuted reflects the resulting state after the toggle.

"},{"location":"Analytics/#ad-events","title":"Ad Events","text":"

Ad-related events include both ad interaction events (for example OpenedAd, DismissedAd) and paid ad operational events (for example AdOpportunity, AdRequested). Not every field is present on every ad event type.

The following properties may be included in ad-related events:

For Ad Opportunity events, additional fields include:

For Ad Requested events, additional fields include:

For Ad Loaded events, additional fields include:

For Ad Failed To Load events, additional fields include:

For Ad Paid events, additional fields include:

For Story Ad events specifically, additional common fields include:

For Clip Ad events specifically, additional common fields include:

"},{"location":"Analytics/#ad-opportunity","title":"Ad Opportunity","text":"

This event is recorded when the SDK reaches an eligible ad slot and is about to request an ad.

This can happen for:

Whenever an Ad Opportunity event occurs, additional event data specific to this event includes playerSessionId and adSlotType.

AdOpportunity also includes the same contextual ad fields as OpenedAd when they are available at opportunity time (for example storyId, pageId, storyPlaybackMode, categories, currentCategory, pageActionType, pageHasAction, pageActionText, pageActionUrl, clipId, clipActionType, clipHasAction, clipActionText, clipActionUrl).

Some differences between AdOpportunity and OpenedAd are expected by design because they are captured at different moments: AdOpportunity is a slot-time snapshot (before the ad request), while OpenedAd is captured when the rendered ad is opened.

"},{"location":"Analytics/#ad-requested","title":"Ad Requested","text":"

This event is recorded when the SDK initiates an Ad request. This event is emitted only for Google Ad sources (GAM and AdMob).

This can happen for:

Whenever an Ad Requested event occurs, additional event data specific to this event includes playerSessionId, adRequestId, adSlotType, adUnitId, and adSource.

For GAM and AdMob integrations supplied by Storyteller, adUnitId is the exact unit used for that request attempt. If AdMob falls back between native and banner formats, each concrete attempt emits its own AdRequested event with the corresponding unit and the same adRequestId.

If a Google module fails before it can resolve a unit or start a concrete provider load, the SDK preserves the request/failure event pair with adUnitId set to nil.

"},{"location":"Analytics/#ad-loaded","title":"Ad Loaded","text":"

This event is recorded when the SDK successfully loads an ad and considers it available for rendering (even if it is not ultimately shown). This event is emitted only for Google Ad sources (GAM and AdMob).

This can happen for:

Whenever an Ad Loaded event occurs, additional event data specific to this event includes playerSessionId, adRequestId, adSlotType, adUnitId, adSource, adSourceName, adSourceId, adSourceInstanceName, adSourceInstanceId, adAdapterLatencyMillis, adMediationGroupName, adMediationAbTestName, and adMediationAbTestVariant.

adUnitId identifies the successful unit. Response metadata takes precedence when it differs from the requested unit.

"},{"location":"Analytics/#ad-failed-to-load","title":"Ad Failed To Load","text":"

This event is recorded when the SDK fails to load an Ad request (including no-fill). This event is emitted only for Google Ad sources (GAM and AdMob).

This can happen for:

Whenever an Ad Failed To Load event occurs, additional event data specific to this event includes playerSessionId, adRequestId, adSlotType, adUnitId, adSource, adErrorCode, adErrorDomain, adErrorMessage, and adAdapterLatencyMillis.

adUnitId identifies the concrete unit used by the failed request attempt. It is nil when the module failed before resolving a unit or starting the provider load.

"},{"location":"Analytics/#ad-paid","title":"Ad Paid","text":"

This event is recorded when the SDK receives impression-level paid revenue info for an Ad from Google Ad sources.

This can happen for:

Whenever an Ad Paid event occurs, additional event data specific to this event includes playerSessionId, adRequestId, adSlotType, adUnitId, adSource, adSourceName, adSourceId, adSourceInstanceName, adSourceInstanceId, adAdapterLatencyMillis, adValueMicros, adCurrencyCode, and adValuePrecision.

"},{"location":"Analytics/#ad-session-summary","title":"Ad Session Summary","text":"

This event is recorded once when a root Storyteller player session ends (Clips or Stories). If a prior session was persisted without being ended cleanly, this summary can also be emitted on the next SDK initialize. The session spans app background/foreground transitions and is not restarted until the root player session ends.

The summary aggregates paid ads activity for that player session:

adSessionRevenueMicros and adSessionCurrencyCode are only included when all paid events in that session can be represented as a single currency with complete paid data.

Whenever an Ad Session Summary event occurs, additional event data specific to this event includes playerSessionId, adSessionOpportunitiesCount, adSessionRequestsCount, adSessionLoadsCount, adSessionFailedToLoadCount, adSessionPaidCount, adSessionRevenueMicros (optional), and adSessionCurrencyCode (optional).

adUnitId is nil for AdSessionSummary because a session can aggregate requests across multiple ad units.

"},{"location":"Analytics/#opened-ad","title":"Opened Ad","text":""},{"location":"Analytics/#stories","title":"Stories","text":"

This event is recorded when:

Whenever an Opened Ad event occurs, additional event data specific to this event includes adView and openedReason.

"},{"location":"Analytics/#clips","title":"Clips","text":"

This event is recorded when:

Information about Ad View is only sent to client delegates on an OpenedAd event.

Whenever an Opened Ad event occurs, additional event data specific to this event includes adView and openedReason.

"},{"location":"Analytics/#dismissed-ad","title":"Dismissed Ad","text":""},{"location":"Analytics/#stories_1","title":"Stories","text":"

This event is recorded when a user:

Whenever a Dismissed Ad event occurs, additional event data specific to this event includes durationViewed, dismissedReason and pagesViewedCount.

"},{"location":"Analytics/#clips_1","title":"Clips","text":"

This event is recorded when a user:

Whenever a Dismissed Ad event occurs, additional event data specific to this event includes durationViewed, and clipsViewed.

"},{"location":"Analytics/#skipped-ad","title":"Skipped Ad","text":""},{"location":"Analytics/#stories_2","title":"Stories","text":"

This event is recorded when a user:

"},{"location":"Analytics/#clips_2","title":"Clips","text":"

This event is recorded when:

"},{"location":"Analytics/#ad-action-button-tapped","title":"Ad Action Button Tapped","text":""},{"location":"Analytics/#stories_3","title":"Stories","text":"

This event is recorded when a user:

"},{"location":"Analytics/#clips_3","title":"Clips","text":"

This event is recorded when a user:

"},{"location":"Analytics/#finished-ad","title":"Finished Ad","text":""},{"location":"Analytics/#stories_4","title":"Stories","text":"

This event is recorded at the same time as Dismissed Ad, Skipped Ad and Viewed Ad Page Complete and gives an easier way to determine when an ad finishes for any reason.

Whenever a Finished Ad event occurs, additional event data specific to this event includes adView.

"},{"location":"Analytics/#clips_4","title":"Clips","text":"

This event is recorded at the same time as DismissedAd, or SkippedAd.

Whenever a Finished Ad event occurs, additional event data specific to this event includes adView.

"},{"location":"Analytics/#paused-ad","title":"Paused Ad","text":""},{"location":"Analytics/#stories_5","title":"Stories","text":"

This event is recorded when a user pauses a page within an ad by pressing and holding on the page.

"},{"location":"Analytics/#clips_5","title":"Clips","text":"

This event is recorded when a user pauses a clip which is an ad by tapping the screen. It does not fire when a clip is paused automatically for sharing or following an action.

"},{"location":"Analytics/#resumed-ad","title":"Resumed Ad","text":""},{"location":"Analytics/#stories_6","title":"Stories","text":"

This event is recorded when a user resumes playing a page within an ad by releasing their long press which paused the ad.

"},{"location":"Analytics/#clips_6","title":"Clips","text":"

This event is fired when a clip which is an ad is paused and a user taps the screen to resume playback. It does not fire when a clip is resumed automatically.

"},{"location":"Analytics/#viewed-ad-page-first-quartile","title":"Viewed Ad Page First Quartile","text":"

This event is recorded when a user reaches 1/4 of the way through the duration of a page or clip which is an ad.

For clip ads (which loop), it fires for each loop of the clip.

"},{"location":"Analytics/#viewed-ad-page-midpoint","title":"Viewed Ad Page Midpoint","text":"

This event is recorded when a user reaches halfway through the duration of a page or clip which is an ad.

For clip ads (which loop), it fires for each loop of the clip.

"},{"location":"Analytics/#viewed-ad-page-third-quartile","title":"Viewed Ad Page Third Quartile","text":"

This event is recorded when a user reaches 3/4 of the way through the duration of a page or clip which is an ad.

For clip ads (which loop), it fires for each loop of the clip.

"},{"location":"Analytics/#viewed-ad-page-complete","title":"Viewed Ad Page Complete","text":"

This event is recorded when a user reaches the end of the duration for a page or clip which is an ad.

For clip ads (which loop), it fires for each loop of the clip.

"},{"location":"Analytics/#muted-ad","title":"Muted Ad","text":"

This event is recorded when:

"},{"location":"Analytics/#unmuted-ad","title":"Unmuted Ad","text":"

This event is recorded when:

"},{"location":"Analytics/#playback-events","title":"Playback Events","text":"

The following properties are included in all Playback-related events:

"},{"location":"Analytics/#ready-to-play","title":"Ready to Play","text":"

This event is called once per video page at the point when the video player has been loaded.

"},{"location":"Analytics/#media-started","title":"Media Started","text":"

This event is called once per video page at the point when the video starts to play for the first time.

"},{"location":"Analytics/#buffering-started","title":"Buffering Started","text":"

This event is called on video pages whenever the video starts to buffer.

Whenever a Buffering Started event occurs, additional event data specific to this event includes isInitialBuffering.

"},{"location":"Analytics/#buffering-ended","title":"Buffering Ended","text":"

This event is called on video pages whenever the video finishes buffering.

Note: There should be at most one Ready to Play event and one Media Started event for every page. There may be multiple Buffering Started/Buffering Ended pairs of events for an individual page. There may not always be a Buffering Ended event for every Buffering Started event as the user may choose to exit the page during buffering.

Whenever a Buffering Ended event occurs, additional event data specific to this event includes isInitialBuffering and timeSinceBufferingBegan.

"},{"location":"Analytics/#sheet-events","title":"Sheet Events","text":"

The following properties are included in all Sheet-related events:

"},{"location":"Analytics/#opened-sheet","title":"Opened Sheet","text":"

This event is recorded when a user opens a Sheet.

Whenever an Opened Sheet event occurs, additional event data specific to this event includes openedReason.

"},{"location":"Analytics/#dismissed-sheet","title":"Dismissed Sheet","text":"

This event is recorded when a user closes a Sheet.

"},{"location":"Analytics/#search-events","title":"Search Events","text":"

The following properties are included in all Search-related events:

When search is opened from a Story context, additional properties include:

When search is opened from a Clip context, additional properties include:

"},{"location":"Analytics/#opened-search","title":"Opened Search","text":"

The openedSearch event is recorded when:

"},{"location":"Analytics/#dismissed-search","title":"Dismissed Search","text":"

The dismissedSearch event is recorded when a user taps the 'X' button to exit the Search interface.

Whenever an Dismissed Search event occurs, additional event data specific to this event includes dismissedReason.

"},{"location":"Analytics/#performed-search","title":"Performed Search","text":"

The performedSearch event is recorded when:

"},{"location":"Analytics/#opened-filters","title":"Opened Filters","text":"

The openedFilters event is recorded when, after a user has performed as Search, they press the 'Filter' icon to bring up the filter interface.

Note: That filters can only be applied after the initial search has been performed.

"},{"location":"Analytics/#dismissed-filters","title":"Dismissed Filters","text":"

This event is recorded when a user, after calling up the 'Filters' interface, swipes down to exit the interface without applying any.

"},{"location":"Analytics/#used-suggestion","title":"Used Suggestion","text":"

The usedSuggestion event is recorded when:

Whenever a Used Suggestion event occurs, additional event data specific to this event includes initialInput.

"},{"location":"Analytics/#event-data","title":"Event Data","text":"

For each event, data is returned with details about the story and page involved as well as some extra properties with more information about what the user has done. The data is returned as a StorytellerUserActivityData class with the following properties:

"},{"location":"Analytics/#story-id","title":"Story ID","text":"

The storyId: String? is the ID of the story for which the event occurred.

"},{"location":"Analytics/#story-title","title":"Story Title","text":"

The storyTitle: String? is the title of the story for which the event occurred.

"},{"location":"Analytics/#story-display-title","title":"Story Display Title","text":"

The storyDisplayTitle: String? is the display title of the Story for which the event occurred.

"},{"location":"Analytics/#story-index","title":"Story Index","text":"

The storyIndex: Int? is the index of the story for which the event occurred in the row from which it was opened at the point it was opened - this is only included on OpenedStory events.

Note: This value is 1-based.

"},{"location":"Analytics/#story-page-count","title":"Story Page Count","text":"

The storyPageCount: Int? is the number of pages in the story.

"},{"location":"Analytics/#story-read-status","title":"Story Read Status","text":"

The storyReadStatus: String? is whether the story was read or unread at the point the story was opened - this is only included on OpenedStory events.

Note: This will either be read or unread.

"},{"location":"Analytics/#page-id","title":"Page ID","text":"

The pageId: String? is the ID of the page for which the event occurred.

"},{"location":"Analytics/#page-index","title":"Page Index","text":"

The pageIndex: Int? is the index of the page in the story for which the event occurred.

Note: This value is 1-based.

"},{"location":"Analytics/#page-type","title":"Page Type","text":"

The pageType: String? is the type of the page associated with the event. This can have the value image, video or poll.

"},{"location":"Analytics/#story-playback-mode","title":"Story Playback Mode","text":"

The storyPlaybackMode: String? value states if the story was opened during the list or in the single story mode (Storyteller static method.) This is included for all events. The values for this are either list or singleStory.

"},{"location":"Analytics/#page-has-action","title":"Page Has Action","text":"

The pageHasAction: Bool? value states whether the page associated with the event contains an action.

"},{"location":"Analytics/#page-action-type","title":"Page Action Type","text":"

The pageActionType: String? is the type of the action on the page.

"},{"location":"Analytics/#page-action-text","title":"Page Action Text","text":"

The pageActionText: String? is the text call to action if the page has an action.

"},{"location":"Analytics/#page-action-url","title":"Page Action URL","text":"

The pageActionUrl: String? is the URL for the link if the page has an action.

"},{"location":"Analytics/#action-link-id","title":"Action Link ID","text":"

The actionLinkId: String? is the unique identifier of the action associated with the current story page, clip or card. This is not included for Ad events.

"},{"location":"Analytics/#opened-reason","title":"Opened Reason","text":"

The openedReason: String? value states how the user opened a Story or Clip. The possible values for this are: - storyListTap: The user tapped the Story in the Story row. - clipListTap: The user tapped the Clip in a Clip list. - deepLink: openStory or openPage was called to open the Story. - swipe: The user swiped left or right to change the current Story. - automaticPlayback: The user completed the previous Page. - card: The user taps on a Card. - clipActionButton: The user clicked on an action button in the Clips player. - pageActionButton: The user clicked on the action button in the Story player. - tap: The user tapped on the next or previous Story Page to navigate to this page. - instanceMethod: Storyteller.shared.openStory(id:) or Storyteller.shared.openPage(id:) was called to open a Story or a Page. - loop: The user completes a loop of a Clip naturally or by scrubbing to the end of the Clip's duration.

openedReason is only included on OpenedStory, OpenedClip, OpenedPage, StoryInstructionsScreenViewed, CompletedLoop, OpenedAd and OpenedSheet events.

"},{"location":"Analytics/#video-start-reason","title":"Video Start Reason","text":"

The videoStartReason: String? value states why a Card video start was emitted. The possible values are natural (the first visible playback start for the Card session) and loop (the Card video completed a loop and restarted while still visible).

videoStartReason is only included on CardVideoStarted events.

"},{"location":"Analytics/#dismissed-reason","title":"Dismissed Reason","text":"

The dismissedReason: String? value states the way the user dismissed a story or clip. The possible values for this are closeButtonTapped (the user tapped close to dismiss the story); swipedDown (the user swiped down to dismiss the story); swipedFirstStory (the user swiped the first story to dismiss it); swipedFinalStory (the user swiped the final story to dismiss it); skippedFinalPage (the user tapped to skip the final page of the final story); completedFinalPage (the user completed the final page of the final story) and backButtonTapped (the user tapped the back button to dismiss the clip).

dismissedReason is only included on DismissedStory and DismissedClip events.

"},{"location":"Analytics/#duration-viewed","title":"Duration Viewed","text":"

The durationViewed: Float? is the duration the user viewed the story or clip for in milliseconds. This is measured from the most recent OpenedStory or OpenedClip event with an Opened Reason of storyRowTap, deepLink, card, pageActionButton, clipActionButton or clipsListTap.

This timer is reset after any DismissedStory or DismissedClip events.

For FinishedClip, Duration Viewed is the duration the user viewed the clips player for in milliseconds. This is measured from the most recent OpenedClip event with an Opened Reason of swipe.

For CardVideoHeartbeat and CardVideoCompleted, durationViewed is the active playback duration for the current card-video loop in milliseconds. It accumulates through pauses, buffering, backgrounding, and other interruptions within the same loop, and resets when a new loop starts.

"},{"location":"Analytics/#audio-toggle-from-to","title":"Audio Toggle From / To","text":"

The audioToggleFrom: String? and audioToggleTo: String? values state the previous and resulting Cards audio state for CardAudioToggled events. Possible values are muted and unmuted.

"},{"location":"Analytics/#pages-viewed-count","title":"Pages Viewed Count","text":"

The pagesViewedCount: Int? is the total number of pages a user has viewed since the most recent OpenedStory event with an Opened Reason of storyRowTap, pageActionButton, clipActionButton, card or deepLink. This count is reset after any DismissedStory events.

"},{"location":"Analytics/#content-length","title":"Content Length","text":"

The contentLength: Int? is the total duration of the page content in seconds.

"},{"location":"Analytics/#share-method","title":"Share Method","text":"

The shareMethod: String? is the component name of the app which the user has selected for sharing.

"},{"location":"Analytics/#advertisers-name","title":"Advertisers Name","text":"

The advertiserName: String? is the name of the advertiser for a particular ad. This is only included for ad events.

"},{"location":"Analytics/#ad-id","title":"Ad ID","text":"

The adId: String? is the ad ID if an event is associated with an ad.

"},{"location":"Analytics/#ad-view","title":"Ad View","text":"

The adView: View? is the view the ad is rendered in. This is only included for OpenedAd and FinishedAd events.

"},{"location":"Analytics/#ad-type","title":"Ad Type","text":"

The adType: String? is the type of component on which the ad is displayed. This can have values stories or clips.

"},{"location":"Analytics/#ad-format","title":"Ad Format","text":"

The adFormat: String? represents the format of the Ad that was displayed. Possible values can be customNative, native, banner.

"},{"location":"Analytics/#ad-placement","title":"Ad Placement","text":"

The adPlacement: String? represents the placement of the ad. It can be either Between Stories, Between Pages or Between Clips. This is only included for ad events.

For Story ad events, AdOpportunity and OpenedAd use the same placement naming (Between Stories / Between Pages).

"},{"location":"Analytics/#ad-strategy","title":"Ad Strategy","text":"

The adStrategy: String? represents the strategy used to display the ads. It can have the following values: Between Stories, Between Pages, Between Stories and Pages, Between Clips.

"},{"location":"Analytics/#ad-response-identifier","title":"Ad Response Identifier","text":"

The adResponseIdentifier: String? represents the response identifier attached to the ad that was received from the ad provider. Used for debugging ad targeting.

"},{"location":"Analytics/#ad-index","title":"Ad Index","text":"

The adIndex: Int? represents the order of the Ad within the displayed Ads in a Story or Clip collection (1 for the first Ad, 2 for the second, etc.). This field is included in all ad-related events.

"},{"location":"Analytics/#player-session-id","title":"Player Session ID","text":"

The playerSessionId: String? is a unique identifier for the current root player session. This is included on AdOpportunity, AdRequested, AdLoaded, AdFailedToLoad, AdPaid, and AdSessionSummary events.

"},{"location":"Analytics/#ad-request-id","title":"Ad Request ID","text":"

The adRequestId: String? is a unique identifier that correlates an ad request chain. This is included on AdRequested, AdLoaded, AdFailedToLoad, and AdPaid events. Concrete native/banner fallback attempts share the same identifier.

"},{"location":"Analytics/#ad-slot-type","title":"Ad Slot Type","text":"

The adSlotType: String? indicates the type of ad slot for AdOpportunity, AdRequested, AdLoaded, AdFailedToLoad, and AdPaid events. Possible values are fullScreen and bottomBanner.

"},{"location":"Analytics/#ad-unit-id","title":"Ad Unit ID","text":"

The adUnitId: String? is the exact ad unit identifier when it is known. It is available on paid ad operational events and is retained on rendered ad interaction events such as OpenedAd, DismissedAd, quartile events, and FinishedAd.

For Storyteller GAM and AdMob integrations, the SDK records the unit immediately before each concrete request attempt. For GAM VAST ads, it uses the final iu tag parameter after client overrides. Host-supplied custom modules can provide the value through StorytellerAd.adUnitId.

adUnitId is nil for AdOpportunity because provider and unit selection have not occurred yet, and for AdSessionSummary because the event aggregates multiple requests. It can also be nil for Storyteller First Party Ads, direct VAST ads, or custom modules that do not supply a unit.

"},{"location":"Analytics/#ad-source","title":"Ad Source","text":"

The adSource: String? is the high-level source for ad events. Supported values include storyteller for Storyteller First Party Ads, gam, admob, and custom source values provided by integrating-app modules via StorytellerModule.adSource. This is included on all ad-related events. For AdOpportunity, adSource is always nil because the event is emitted before ad module resolution. For other ad events, adSource may still be nil when the source cannot be resolved.

"},{"location":"Analytics/#ad-mediation-group-name","title":"Ad Mediation Group Name","text":"

The adMediationGroupName: String? is the mediation group name returned by the ad provider when available. This is included on AdLoaded events when available.

"},{"location":"Analytics/#ad-mediation-ab-test-name","title":"Ad Mediation Ab Test Name","text":"

The adMediationAbTestName: String? is the mediation A/B test name returned by the ad provider when available. This is included on AdLoaded events when available.

"},{"location":"Analytics/#ad-mediation-ab-test-variant","title":"Ad Mediation Ab Test Variant","text":"

The adMediationAbTestVariant: String? is the mediation A/B test variant returned by the ad provider when available. This is included on AdLoaded events when available.

"},{"location":"Analytics/#ad-adapter-latency-millis","title":"Ad Adapter Latency Millis","text":"

The adAdapterLatencyMillis: Int? is the elapsed time in milliseconds for the concrete ad request attempt that produced the result. When native/banner fallback occurs, load, failure, and paid events use the final attempt's latency. This is included on AdLoaded, AdFailedToLoad, and AdPaid events.

"},{"location":"Analytics/#ad-error-code","title":"Ad Error Code","text":"

The adErrorCode: Int? is the numeric error code reported by the ad provider. This is included on AdFailedToLoad events.

"},{"location":"Analytics/#ad-error-domain","title":"Ad Error Domain","text":"

The adErrorDomain: String? is the error domain reported by the ad provider. This is included on AdFailedToLoad events.

"},{"location":"Analytics/#ad-error-message","title":"Ad Error Message","text":"

The adErrorMessage: String? is the error description reported by the ad provider. This is included on AdFailedToLoad events.

"},{"location":"Analytics/#ad-value-micros","title":"Ad Value Micros","text":"

The adValueMicros: Int? is the paid value in micros (1,000,000 micros = 1 unit of currency). This is only included on AdPaid events.

"},{"location":"Analytics/#ad-currency-code","title":"Ad Currency Code","text":"

The adCurrencyCode: String? is the currency code for the paid value (ISO 4217). This is only included on AdPaid events.

"},{"location":"Analytics/#ad-value-precision","title":"Ad Value Precision","text":"

The adValuePrecision: String? indicates how precise the paid value is. Possible values are UNKNOWN, ESTIMATED, PUBLISHER_PROVIDED, and PRECISE. This is only included on AdPaid events.

"},{"location":"Analytics/#ad-session-opportunities-count","title":"Ad Session Opportunities Count","text":"

The adSessionOpportunitiesCount: Int? is the total number of ad opportunities tracked in the player session. This is only included on AdSessionSummary events.

"},{"location":"Analytics/#ad-session-requests-count","title":"Ad Session Requests Count","text":"

The adSessionRequestsCount: Int? is the total number of ad-module request attempts initiated in the player session. Native/banner fallback attempts are counted separately, and a module failure before provider load counts once, so this value can exceed the number of ad opportunities. This is only included on AdSessionSummary events.

"},{"location":"Analytics/#ad-session-loads-count","title":"Ad Session Loads Count","text":"

The adSessionLoadsCount: Int? is the total number of successful ad loads in the player session. This is only included on AdSessionSummary events.

"},{"location":"Analytics/#ad-session-failed-to-load-count","title":"Ad Session Failed To Load Count","text":"

The adSessionFailedToLoadCount: Int? is the total number of ad load failures in the player session. This is only included on AdSessionSummary events.

"},{"location":"Analytics/#ad-session-paid-count","title":"Ad Session Paid Count","text":"

The adSessionPaidCount: Int? is the total number of paid callbacks received in the player session. This is only included on AdSessionSummary events.

"},{"location":"Analytics/#ad-session-revenue-micros","title":"Ad Session Revenue Micros","text":"

The adSessionRevenueMicros: Int? is the aggregated session paid value in micros. This is only included on AdSessionSummary events when all paid callbacks in the session use one currency and include complete paid data.

"},{"location":"Analytics/#ad-session-currency-code","title":"Ad Session Currency Code","text":"

The adSessionCurrencyCode: String? is the ISO 4217 currency code associated with adSessionRevenueMicros. This is only included on AdSessionSummary events when all paid callbacks in the session use one currency and include complete paid data.

"},{"location":"Analytics/#is-initial-buffering","title":"Is Initial Buffering","text":"

The isInitialBuffering: Boolean? value is returned if the buffering happens at the start of playback for that page. This is only included for BufferingStarted and BufferingEnded events.

"},{"location":"Analytics/#time-since-buffering-began","title":"Time Since Buffering Began","text":"

The timeSinceBufferingBegan: TimeInterval? value is the duration the current buffering lasted for in milliseconds. This is only included for BufferingEnded events.

"},{"location":"Analytics/#categories","title":"Categories","text":"

The categories: [String]? value is the list of categories assigned to the story or clip for which the event occurred. This is included on OpenedStory and TileVisible events, and may be included on other story, clip, ad, card, search, or sheet events when category context is available.

"},{"location":"Analytics/#poll-answer","title":"Poll Answer","text":"

The pollAnswerId: String? is the ID of the answer the user selected when voting. This is only included on VotedPoll events.

"},{"location":"Analytics/#trivia-quiz-id","title":"Trivia Quiz ID","text":"

The triviaQuizId: String? is the ID of the trivia quiz that was completed or answered. This is only included on TriviaQuizQuestionAnswered and TriviaQuizCompleted events.

"},{"location":"Analytics/#trivia-quiz-title","title":"Trivia Quiz Title","text":"

The triviaQuizTitle: String? is the title of the trivia quiz that was completed or answered. This is only included on TriviaQuizQuestionAnswered and TriviaQuizCompleted events.

"},{"location":"Analytics/#trivia-quiz-score","title":"Trivia Quiz Score","text":"

The triviaQuizScore: Int? value is the score of the trivia quiz that was completed. This is only included on TriviaQuizCompleted events.

"},{"location":"Analytics/#trivia-quiz-question-id","title":"Trivia Quiz Question ID","text":"

The triviaQuizQuestionId: String? is the ID of the trivia quiz question which was answered. This is only included on TriviaQuizQuestionAnswered events.

"},{"location":"Analytics/#trivia-quiz-answer-id","title":"Trivia Quiz Answer ID","text":"

The triviaQuizAnswerId: String? is the ID of the selected trivia quiz answer. This is only included on TriviaQuizQuestionAnswered events.

"},{"location":"Analytics/#clip-id","title":"Clip ID","text":"

The clipId: String? is the ID of the clip for which the event occurred.

"},{"location":"Analytics/#clip-title","title":"Clip Title","text":"

The clipTitle: String? is the title of the clip for which the event occurred.

"},{"location":"Analytics/#clip-index","title":"Clip Index","text":"

The clipIndex: Int? is the index of the clip in the row or grid at the point it was selected or the index of the clip in the player inside the original row or grid. For Ad events, clip index refers to the index of the clip before the Ad.

"},{"location":"Analytics/#tile-index","title":"Tile Index","text":"

The tileIndex: Int? is the index of the Story or Clip tile in the row or grid at the point it became visible. This is only included on TileVisible events.

Note: This value is 1-based.

"},{"location":"Analytics/#clip-collection-count","title":"Clip Collection Count","text":"

The clipCollectionCount: Int? is the total number of clips in the collection being viewed.

"},{"location":"Analytics/#clip-feed-type","title":"Clip Feed Type","text":"

The clipFeedType: String? indicates the type of clip feed being viewed. Possible values are default, forYou, and following.

"},{"location":"Analytics/#clips-viewed","title":"Clips Viewed","text":"

The clipsViewed: Int? value is the total number of clips a user has viewed since the most recent OpenedClip event with an Opened Reason of clipListTap, pageActionButton, card, clipActionButton or deepLink. This count should be reset after any DismissedClip events.

"},{"location":"Analytics/#loops-viewed","title":"Loops Viewed","text":"

The loopsViewed: Int? is for DismissedClip, the total number of loops (plays of an individual clip) a user has viewed since the most recent OpenedClip event with an Opened Reason of clipListTap, pageActionButton, card, clipActionButton or deepLink.

This count should be reset after any DismissedClip events. For FinishedClip, the total number of loops.

"},{"location":"Analytics/#is-live","title":"Is Live","text":"

The isLive: Bool? indicates whether a Clip, Story, or Card is currently being broadcast in real-time and is therefore \"Live\".

"},{"location":"Analytics/#airplay-enabled","title":"Airplay Enabled","text":"

The airplayEnabled: Bool? indicates whether the device is currently using AirPlay for audio/video output when the event occurred.

"},{"location":"Analytics/#clip-has-action","title":"Clip Has Action","text":"

The clipHasAction: Bool? value is whether the clip associated with the event contains a primary action.

"},{"location":"Analytics/#clip-action-text","title":"Clip Action Text","text":"

The clipActionText: String? is the text call to action if the clip associated with the event has a primary action link.

"},{"location":"Analytics/#clip-action-url","title":"Clip Action URL","text":"

The clipActionUrl: String? is the URL linked to from the primary action if a clip associated with the event has a primary action.

"},{"location":"Analytics/#clip-action-type","title":"Clip Action Type","text":"

The clipActionType: String? is the type of the primary action on a clip associated with the event. If there is no action button then the value is nil.

"},{"location":"Analytics/#collection","title":"Collection","text":"

The collection is the ID of the collection if a story or clip is being played from a collection.

"},{"location":"Analytics/#collection-title","title":"Collection Title","text":"

The collectionTitle: String? is the title of the collection if clip is being played from a collection.

"},{"location":"Analytics/#container-title","title":"Container Title","text":"

The containerTitle is the title of the collection if a story or clip is being played from a collection.

"},{"location":"Analytics/#category-details","title":"Category Details","text":"

The categoryDetails is a list of Category Detail objects. The details are the name, ID, type and placement of the category.

"},{"location":"Analytics/#category-name","title":"Category Name","text":"

The categoryName of the category being navigated to or dismissed.

"},{"location":"Analytics/#category-id","title":"Category ID","text":"

The categoryId of the category being navigated to or dismissed.

"},{"location":"Analytics/#current-category","title":"Current Category","text":"

The currentCategory is the category for the row that is currently being interacted with. The information provided from this is the category title, ID and placement.

This is only included on story and ad events.

"},{"location":"Analytics/#captions-enabled","title":"Captions Enabled","text":"

The captionsEnabled property indicates whether captions are currently enabled for the Clips Player. This is included in all Clip Analytics Events and represents the state of captions at the time the event occurred.

"},{"location":"Analytics/#start-position","title":"Start Position","text":"

The startPosition: Int? represents the playback position, in milliseconds, when the user started scrubbing the clip. This is only included for ScrubbedClip events.

"},{"location":"Analytics/#end-position","title":"End Position","text":"

The endPosition: Int? represents the playback position, in milliseconds, when the user stopped scrubbing the clip. This is only included for ScrubbedClip events.

"},{"location":"Analytics/#eyebrow","title":"Eyebrow","text":"

The eyebrow: String? is a text field displayed on stories and clips, typically shown above the main title as a subtitle or descriptor.

"},{"location":"Analytics/#scrub-direction","title":"Scrub Direction","text":"

The scrubDirection: String? indicates whether the user scrubbed to a position forward or backward on a Clip. Possible values are forward and backward. This is only included for ScrubbedClip events.

"},{"location":"Analytics/#completion-type","title":"Completion Type","text":"

The completionType: String? indicates how a user finished watching a Clip. Possible values are natural and scrubbed. This is included for FinishedClip and ClipCompletedLoop events.

"},{"location":"Analytics/#sheet-id","title":"Sheet ID","text":"

The ID of the Sheet for which the event occurred.

"},{"location":"Analytics/#sheet-size","title":"Sheet Size","text":"

The height of the Sheet for which the event occurred. Possible values are 50, 75, and 100 (representing % of screen height).

"},{"location":"Analytics/#sheet-title","title":"Sheet Title","text":"

The title of the Sheet for which the event occurred.

"},{"location":"Analytics/#search-from","title":"Search From","text":"

The searchFrom indicates whether the Search for which the event is recorded was opened from Clips or Stories.

"},{"location":"Analytics/#is-suggestion","title":"Is Suggestion","text":"

The isSuggestion indicates whether the Search for which the event is recorded used a suggested Search.

Note: When filters are opened (event), the Is Suggestion value should reflect what was used for the initial search performed before opening filters.

"},{"location":"Analytics/#initial-input","title":"Initial Input","text":"

The initialInput this property tracks the input at the moment the suggestion was used.

"},{"location":"Analytics/#search-filter","title":"Search Filter","text":"

The searchFilter property includes the content type and date posted used by search filter.

"},{"location":"Analytics/#search-sort","title":"Search Sort","text":"

The searchSort field indicates method by which the relevant Story / Clip's search results were sorted.

"},{"location":"Analytics/#search-term","title":"Search Term","text":"

The searchTerm by which the Clips / Stories were searched, either entered in the search bar by the user or selected / filled from search suggestions.

"},{"location":"Analytics/#action-text","title":"Action Text","text":"

The actionText: String? property is used for general action text and can apply to both page actions and clip actions depending on the placement context.

"},{"location":"Analytics/#action-type","title":"Action Type","text":"

The actionType: String? property is used for general action types, and can apply to both page actions and clip actions depending on the placement context.

"},{"location":"Analytics/#action-url","title":"Action URL","text":"

The actionUrl: String? is the URL for the action link. This property is used for general action URLs in events and can apply to both page actions and clip actions depending on the placement context.

"},{"location":"Analytics/#action-class","title":"Action Class","text":"

The actionClass: String? identifies whether the action button that was tapped is a primary or secondary action. Possible values are primary and secondary. This is only included for ClipActionButtonTapped events.

"},{"location":"Analytics/#action-index","title":"Action Index","text":"

The actionIndex: Int? is the 1-based index of the secondary action that was tapped. This is only included for ClipActionButtonTapped events when a secondary action is tapped.

"},{"location":"Analytics/#tapped-clip-action-text","title":"Tapped Clip Action Text","text":"

The tappedClipActionText: String? is the text of the specific action button (primary or secondary) that was tapped. This is only included for ClipActionButtonTapped events.

"},{"location":"Analytics/#tapped-clip-action-url","title":"Tapped Clip Action URL","text":"

The tappedClipActionUrl: String? is the URL of the specific action button (primary or secondary) that was tapped. This is only included for ClipActionButtonTapped events.

"},{"location":"Analytics/#tapped-clip-action-type","title":"Tapped Clip Action Type","text":"

The tappedClipActionType: String? is the type of the specific action button (primary or secondary) that was tapped. This is only included for ClipActionButtonTapped events.

"},{"location":"Analytics/#has-secondary-actions","title":"Has Secondary Actions","text":"

The clipHasSecondaryActions: Bool? indicates whether the clip has any secondary actions. This is included in all Clip Analytics Events.

"},{"location":"Analytics/#secondary-actions-text","title":"Secondary Actions Text","text":"

The clipSecondaryActionsText: [String]? is an array of all the text CTAs on secondary actions for the clip. This is included in all Clip Analytics Events when the clip has secondary actions.

"},{"location":"Analytics/#secondary-action-urls","title":"Secondary Action URLs","text":"

The clipSecondaryActionUrls: [String]? is an array of all the URLs on secondary actions for the clip. This is included in all Clip Analytics Events when the clip has secondary actions.

"},{"location":"Analytics/#secondary-action-types","title":"Secondary Action Types","text":"

The clipSecondaryActionTypes: [String]? is an array of all the types of secondary actions for the clip. This is included in all Clip Analytics Events when the clip has secondary actions.

"},{"location":"Analytics/#card-id","title":"Card ID","text":"

The cardId: String? is the ID of the Card for which the event occurred. This is included for CardTapped event.

"},{"location":"Analytics/#card-action-type","title":"Card Action Type","text":"

The cardActionType: String? is the type of the action on the Card. This is included for CardTapped event.

"},{"location":"Analytics/#card-action-url","title":"Card Action URL","text":"

The cardActionUrl: String? is the URL for the link if the Card has an action. This is included for CardTapped event.

"},{"location":"Analytics/#card-aspect-ratio","title":"Card Aspect Ratio","text":"

The cardAspectRatio: String? is the aspect ratio of the Card. This is included for CardTapped event.

"},{"location":"Analytics/#card-background-type","title":"Card Background Type","text":"

The cardBackgroundType: String? is the type of background on the Card. This can have the value image or video. This is included for CardTapped event.

"},{"location":"Analytics/#card-collection-id","title":"Card Collection ID","text":"

The cardCollectionId: String? is the ID of the collection the Card belongs to. This is included for CardTapped event.

"},{"location":"Analytics/#card-index","title":"Card Index","text":"

The cardIndex: Int? is the index of the Card in the collection.

Note: This value is 1-based.

"},{"location":"Analytics/#card-subtitle","title":"Card Subtitle","text":"

The cardSubtitle: String? is the subtitle text displayed on the Card. This is included for CardTapped event.

"},{"location":"Analytics/#card-title","title":"Card Title","text":"

The cardTitle: String? is the title text displayed on the Card. This is included for CardTapped event.

"},{"location":"Analytics/#has-button","title":"Has Button","text":"

The hasButton: Bool? indicates whether the Card displayed a button. This is included for CardViewed and CardTapped events.

"},{"location":"Analytics/#has-action","title":"Has Action","text":"

The SDK does not emit a hasAction property. Use pageHasAction (story/page-based ad events) or clipHasAction (clip-based ad events) depending on the ad placement context.

"},{"location":"Analytics/#followable-category-limit-dialogue","title":"Followable Category Limit Dialogue","text":"

The followableCategoryLimitDialogue: String? is the text displayed in the Followable Category Limit dialogue box. This is included for FollowableCategoryLimitShown, FollowableCategoryLimitActionButtonTapped, and FollowableCategoryLimitDismissed events.

"},{"location":"Analytics/#followable-category-limit-action-text","title":"Followable Category Limit Action Text","text":"

The followableCategoryLimitActionText: String? is the text displayed on the customisable action button in the Followable Category Limit dialogue box. This is included for FollowableCategoryLimitShown, FollowableCategoryLimitActionButtonTapped, and FollowableCategoryLimitDismissed events.

"},{"location":"Analytics/#followable-category-limit-action-url","title":"Followable Category Limit Action URL","text":"

The followableCategoryLimitActionUrl: String? is the URL associated with the customisable action button in the Followable Category Limit dialogue box. This is included for FollowableCategoryLimitShown, FollowableCategoryLimitActionButtonTapped, and FollowableCategoryLimitDismissed events.

"},{"location":"Analytics/#is-muted","title":"Is Muted","text":"

The isMuted: Bool? indicates whether the audio is currently muted when the event occurred. This property is included in all Story, Clip, Ad, and video Card analytics events when the mute state is known and represents the mute state at the time the event was tracked. Permanently muted video Cards and video Cards marked as having no audio report true; image and non-video Card events report nil.

"},{"location":"Analytics/#metadata","title":"Metadata","text":"

The metadata: [String: String]? contains custom metadata associated with the content for which the event occurred. For Clip events, this contains the metadata from the associated clip. For Story events, this contains the metadata from the associated page. This property is included in all Story and Clip analytics events.

"},{"location":"Analytics/#context","title":"Context","text":"

context: StorytellerAnalyticsContext? contains host-defined attribution data. StorytellerAnalyticsContext is a type alias for [String: String]; the SDK does not prescribe the keys.

You can provide context through:

The SDK carries that context into StorytellerUserActivityData.context for events it can attribute to the configured surface and content opened from it. Consume it in StorytellerDelegate.onUserActivityOccurred:

import StorytellerSDK\n\nlet analyticsContext: StorytellerAnalyticsContext = [\n    \"location\": \"home\",\n    \"campaign\": \"summer-league\"\n]\n\nlet clipsConfiguration = StorytellerClipsListConfiguration(\n    collectionId: \"top-plays\",\n    context: analyticsContext\n)\n\nfinal class AnalyticsDelegate: StorytellerDelegate {\n    func onUserActivityOccurred(\n        type: StorytellerUserActivity.EventType,\n        data: StorytellerUserActivityData\n    ) {\n        guard let location = data.context?[\"location\"] else { return }\n        print(\"Storyteller event \\(type) came from \\(location)\")\n    }\n}\n

The callback is delivered only when enableUserActivityTracking is enabled. Ad events are additionally gated by enableAdTracking.

The Showcase app demonstrates an optional app-defined key namespace and consumption in StorytellerTrackingDelegate.

"},{"location":"AnalyticsIntegration/","title":"Integrate Analytics","text":"

Storyteller delivers user activity events to your app through StorytellerDelegate.onUserActivityOccurred(type:data:). This guide shows how to retain the delegate, select the tracking behavior during initialization, forward events to your analytics layer, and add host-defined attribution context.

Use the Analytics Event Reference after setup to choose the event types and payload fields your analytics implementation needs.

"},{"location":"AnalyticsIntegration/#retain-a-delegate-and-forward-events","title":"Retain a Delegate and Forward Events","text":"

Storyteller.shared.delegate is weak. Keep the delegate in app-owned state for as long as you need callbacks, and assign the same object that handles your other global Storyteller callbacks. If another part of the app later replaces Storyteller.shared.delegate, the original object stops receiving events.

The following complete example forwards the serialized event key (type.rawValue), selected content identifiers, and any analytics context into a provider-independent host analytics layer. Replace ConsoleAnalytics with your own analytics adapter.

import StorytellerSDK\n\nstruct HostAnalyticsEvent {\n    let name: String\n    let storyId: String?\n    let clipId: String?\n    let context: StorytellerAnalyticsContext?\n}\n\nprotocol HostAnalyticsTracking: AnyObject {\n    func track(_ event: HostAnalyticsEvent)\n}\n\nfinal class ConsoleAnalytics: HostAnalyticsTracking {\n    func track(_ event: HostAnalyticsEvent) {\n        print(\n            \"Storyteller event: \\(event.name), \"\n                + \"story: \\(event.storyId ?? \"none\"), \"\n                + \"clip: \\(event.clipId ?? \"none\"), \"\n                + \"context: \\(event.context ?? [:])\"\n        )\n    }\n}\n\nfinal class StorytellerAnalyticsDelegate: StorytellerDelegate {\n    private let analytics: any HostAnalyticsTracking\n\n    init(analytics: any HostAnalyticsTracking) {\n        self.analytics = analytics\n    }\n\n    func onUserActivityOccurred(\n        type: StorytellerUserActivity.EventType,\n        data: StorytellerUserActivityData\n    ) {\n        analytics.track(\n            HostAnalyticsEvent(\n                name: type.rawValue,\n                storyId: data.storyId,\n                clipId: data.clipId,\n                context: data.context\n            )\n        )\n    }\n}\n\n@MainActor\nfinal class StorytellerIntegration {\n    private let storytellerDelegate: StorytellerAnalyticsDelegate\n\n    init(analytics: any HostAnalyticsTracking) {\n        let delegate = StorytellerAnalyticsDelegate(analytics: analytics)\n        storytellerDelegate = delegate\n        Storyteller.shared.delegate = delegate\n    }\n\n    func initialize(\n        apiKey: String,\n        userId: String,\n        trackingOptions: StorytellerEventTrackingOptions\n    ) async throws {\n        try await Storyteller.shared.initialize(\n            apiKey: apiKey,\n            userInput: StorytellerUserInput(externalId: userId),\n            eventTrackingOptions: trackingOptions\n        )\n    }\n}\n\n@MainActor\nfinal class AppServices {\n    private let storyteller = StorytellerIntegration(\n        analytics: ConsoleAnalytics()\n    )\n\n    func start() async throws {\n        // Use .enableAll only when it matches your app's consent policy.\n        try await storyteller.initialize(\n            apiKey: \"your-api-key\",\n            userId: \"your-user-id\",\n            trackingOptions: .enableAll\n        )\n    }\n}\n

StorytellerUserActivityData is an event-specific payload, so most properties are optional. Forward only the fields your analytics contract needs, using the event reference to determine which fields apply to each event. The Showcase app demonstrates provider-specific mapping in StorytellerTrackingDelegate.

"},{"location":"AnalyticsIntegration/#choose-tracking-options-during-initialization","title":"Choose Tracking Options During Initialization","text":"

Pass StorytellerEventTrackingOptions when you call initialize(...). The value is fixed for that initialization; reinitialize the SDK to apply a later consent change.

For host analytics delivery, these options have distinct effects:

Option Effect on onUserActivityOccurred enableUserActivityTracking Must be enabled for the integrating app to receive user activity events. enableAdTracking Must also be enabled for Ad-related user activity events. It does not control whether a host-supplied Ad loading callback is requested. enableStorytellerTracking Controls Storyteller's own analytics collection; enableUserActivityTracking remains the host callback gate. enableFullVideoAnalytics When disabled, callbacks still arrive, but content identifiers and titles listed in Privacy and Tracking are removed from their payloads.

The other options affect personalization, viewing state, and functional behavior. Choose the complete configuration from your app's consent requirements; see Privacy and Tracking before changing defaults.

"},{"location":"AnalyticsIntegration/#add-analytics-context","title":"Add Analytics Context","text":"

StorytellerAnalyticsContext is a type alias for [String: String]. The SDK does not prescribe its keys. Add a context dictionary to the configuration for the surface or presentation you want to attribute:

For example, an Embedded Clips configuration can identify both its screen and placement:

let clipsConfiguration = StorytellerClipCollectionConfiguration(\n    collectionId: \"top-plays\",\n    context: [\n        \"screen\": \"home\",\n        \"placement\": \"primary-clips-feed\"\n    ]\n)\n

The SDK carries the dictionary into StorytellerUserActivityData.context when an event can be attributed to that configured surface or to content opened from it. The property remains optional: events without an attributable configured surface do not receive a context value. Set context before loading or opening the content whose events you want to attribute.

See Context in the Analytics Event Reference for the complete attribution contract and another consumption example.

"},{"location":"AnalyticsIntegration/#verify-the-integration","title":"Verify the Integration","text":"

After initialization succeeds:

  1. Load known published content using a configuration with a distinctive context value.
  2. Open or interact with that content to produce a documented event, such as openedStory or openedClip.
  3. Confirm your analytics adapter receives the expected type.rawValue and payload.
  4. Confirm data.context contains the value supplied by the originating configuration when that event is attributable to the surface.

Initialization success alone does not exercise this callback path or generate a host user activity callback. Trigger a supported content interaction when testing the integration.

"},{"location":"AnalyticsIntegration/#troubleshoot-missing-events-or-context","title":"Troubleshoot Missing Events or Context","text":"

If no event arrives:

If the callback arrives but data is missing:

Use Callbacks or Analytics Events Do Not Arrive to separate analytics delivery from component loading, app navigation, and Ad loading callbacks.

"},{"location":"AnalyticsIntegration/#continue-with-the-event-reference","title":"Continue with the Event Reference","text":"

Use the Analytics Event Reference for all public event keys, the common fields for each feature, event-specific fields, and enum value definitions.

"},{"location":"Brightcove/","title":"Storyteller Brightcove Integration","text":"

This package is a utility to record player events from an AVPlayer and feed them into Brightcove analytics.

"},{"location":"Brightcove/#setup","title":"Setup","text":"

Add Storyteller Brightcove Collector using SPM:

  1. Add the package dependency: https://github.com/getstoryteller/storyteller-brightcove-collector-swift
  2. Add the StorytellerBrightcoveIntegration target to your app target

To use the module, StorytellerSDK needs to be set to version 11.0.0 or higher.

In the file where you setup the Storyteller SDK, import the added package, set up the module and set it on the Storyteller class:

import StorytellerBrightcoveIntegration\n\nfunc initializeStoryteller() {\n    let brightcoveConfiguration = StorytellerBrightcoveModuleConfiguration(\n        account: \"<account ID>\",\n        playerName: \"Video Player\", // optional\n        source: \"<source>\",\n        destination: \"<destination>\"\n    )\n\n    Storyteller.shared.modules.append(StorytellerBrightcoveModule(configuration: brightcoveConfiguration))\n\n    // other Storyteller initialization code\n}\n

See the Brightcove module setup example in the Showcase app: AppDelegate.setupStoryteller.

"},{"location":"Cards/","title":"Storyteller Cards","text":"

Storyteller Cards are flexible, themeable components designed to promote content or direct users to key sections within your app. They can display a background image or video, along with an optional title, subtitle, and button. Tapping on a Card can trigger various actions, such as opening a specific Story, a Story Category, a Clip, a Clip Collection or any other action defined in the CMS. The server or personalization engine can choose which Cards to return for a given user.

Cards currently support 1:1, 2:3, 3:4, 4:5, 9:16, 16:9, and 4:1 aspect ratios from CMS payloads.

"},{"location":"Cards/#usage","title":"Usage","text":"

You can integrate Storyteller Cards into your app using either SwiftUI or UIKit.

"},{"location":"Cards/#swiftui","title":"SwiftUI","text":"

For SwiftUI, use the StorytellerCard view component.

  1. Configuration: Create a StorytellerCardConfiguration object, specifying the collectionId for the Card collection you want to display. You can also provide optional context data for analytics attribution. When configured, context will be included in all analytics events when users interact with the Card. See Analytics for more details.
  2. Model: Initialize a StorytellerCardModel (which conforms to ObservableObject) with the configuration.
  3. View: Create the StorytellerCard view, passing in the StorytellerCardModel instance.
  4. Actions (Optional): Provide an optional callback closure to the StorytellerCard initializer to handle events like onDataLoadComplete. This allows you to react to data loading success or failure (e.g., by hiding the component).
import SwiftUI\nimport StorytellerSDK\n\n@available(iOS 14.0, *)\nstruct SwiftUIView: View {\n    @StateObject private var cardModel = StorytellerCardModel(\n        configuration: StorytellerCardConfiguration(\n            collectionId: \"card-collection-id\",\n            context: [\"source\": \"hero-banner\"]\n        )\n    )\n\n    var body: some View {\n        VStack {\n            Text(\"Storyteller Card Section\")\n            StorytellerCard(model: cardModel) { action in\n                switch action {\n                case .onDataLoadComplete(let result):\n                    switch result {\n                    case .success:\n                        print(\"Card data loaded successfully!\")\n                    case .failure(let error):\n                        print(\"Card data failed to load: \\(error.localizedDescription)\")\n                    }\n                @unknown default:\n                    break\n                }\n            }\n\n            Button(\"Reload Card\") {\n                cardModel.reload()\n            }\n        }\n        .padding()\n    }\n}\n

See the Showcase StorytellerCard integration in StorytellerItemView.

See the Showcase card callback handling in StorytellerItemView.cardAction.

"},{"location":"Cards/#uikit","title":"UIKit","text":"

For UIKit, use the StorytellerCardView class, which subclasses UIView.

  1. Configuration: Create a StorytellerCardConfiguration with the desired collectionId. You can also provide optional context data for analytics. When configured, context will be included in all analytics events when users interact with the Card. See Analytics for more details.
  2. View Initialization: Instantiate StorytellerCardView using the configuration.
  3. Delegate (Optional): Assign an object conforming to StorytellerCardViewDelegate to the view's delegate property to receive callbacks like onDataLoadComplete.
  4. Add to View Hierarchy: Add the StorytellerCardView instance as a subview.
class CardView: UIView, StorytellerCardViewDelegate {\n\n    private var storytellerCardView: StorytellerCardView?\n\n    // ...\n\n    func configure(with collectionId: String, delegate: StorytellerCardViewDelegate?) {\n        let configuration = StorytellerCardConfiguration(\n            collectionId: collectionId,\n            context: [\n                \"source\": \"hero-banner\",\n            ]\n        )\n        let cardView = StorytellerCardView(configuration: configuration)\n        cardView.delegate = delegate\n\n        addSubview(cardView)\n        // Add constraints\n\n        self.storytellerCardView = cardView\n    }\n\n    func reloadCard() {\n        storytellerCardView?.reload()\n    }\n\n    nonisolated func onDataLoadComplete(result: Result<Void, Error>) {\n        // Respond to the load result as needed.\n    }\n}\n

For UIKit integration patterns using table view cells, see the CocoaPods sample in MultipleListsDataSource.

We also provide cells to include inside collection and table views - StorytellerCardCollectionViewCell and StorytellerCardTableViewCell. They also follow the above pattern to setup.

"},{"location":"Cards/#reloading","title":"Reloading","text":"

Both StorytellerCardModel (for SwiftUI) and the UIKit flavours provide a reload() method. Call this method to manually trigger a refresh of the Card data from the server.

"},{"location":"Cards/#viewedtapped-ordering","title":"Viewed/Tapped Ordering","text":"

In the CMS you can make Card collections be ordered based on viewed or tapped status, so that once a Card is viewed/tapped, the next Card from the collection will be shown to the user. This will enable users to always see fresh content.

"},{"location":"Cards/#video-card-audio","title":"Video Card Audio","text":"

Video Cards start from the Cards audio behavior in tenant settings. For the usual muted-toggle setup, the active video Card shows a mute/unmute control and starts muted. The selected Cards audio state is shared across the current Cards surface, so if a user unmutes one video Card, newly active video Cards stay unmuted until the user mutes again or an audio interruption occurs.

Only the active video Card can be audible. Inactive video Cards stay muted, and image Cards do not show an audio control. If the API marks a video Card as having no audio, the active Card does not show an audio control and remains muted.

Cards audio behavior is controlled by the CMS/API settings theme under theme.behavior.cards:

"},{"location":"Cards/#theming","title":"Theming","text":"

Card appearance and behavior are primarily configured directly within the Storyteller CMS for each Card Collection. The following properties can be configured in the CMS and influence the Card's presentation and behaviour:

"},{"location":"Cards/#button-behavior","title":"Button Behavior","text":""},{"location":"Cards/#button-theme-properties","title":"Button Theme Properties","text":""},{"location":"Cards/#behavior-properties","title":"Behavior Properties","text":""},{"location":"Changelog/","title":"Changelog","text":""},{"location":"Changelog/#1160-07082026","title":"11.6.0 - 07/08/2026","text":""},{"location":"Changelog/#new-features","title":"New Features","text":""},{"location":"Changelog/#improvements","title":"Improvements","text":""},{"location":"Changelog/#bug-fixes","title":"Bug fixes","text":""},{"location":"Changelog/#1154-05082026","title":"11.5.4 - 05/08/2026","text":""},{"location":"Changelog/#bug-fixes_1","title":"Bug fixes","text":""},{"location":"Changelog/#1153-30072026","title":"11.5.3 - 30/07/2026","text":""},{"location":"Changelog/#improvements_1","title":"Improvements","text":""},{"location":"Changelog/#bug-fixes_2","title":"Bug fixes","text":""},{"location":"Changelog/#1152-27072026","title":"11.5.2 - 27/07/2026","text":""},{"location":"Changelog/#bug-fixes_3","title":"Bug fixes","text":""},{"location":"Changelog/#1151-22072026","title":"11.5.1 - 22/07/2026","text":""},{"location":"Changelog/#new-features_1","title":"New Features","text":""},{"location":"Changelog/#improvements_2","title":"Improvements","text":""},{"location":"Changelog/#1150-01072026","title":"11.5.0 - 01/07/2026","text":""},{"location":"Changelog/#new-features_2","title":"New Features","text":""},{"location":"Changelog/#improvements_3","title":"Improvements","text":""},{"location":"Changelog/#bug-fixes_4","title":"Bug fixes","text":""},{"location":"Changelog/#1141-12062026","title":"11.4.1 - 12/06/2026","text":""},{"location":"Changelog/#new-features_3","title":"New Features","text":""},{"location":"Changelog/#improvements_4","title":"Improvements","text":""},{"location":"Changelog/#bug-fixes_5","title":"Bug fixes","text":""},{"location":"Changelog/#1140-18052026","title":"11.4.0 - 18/05/2026","text":""},{"location":"Changelog/#new-features_4","title":"New Features","text":""},{"location":"Changelog/#improvements_5","title":"Improvements","text":""},{"location":"Changelog/#bug-fixes_6","title":"Bug fixes","text":""},{"location":"Changelog/#1133-06052026","title":"11.3.3 - 06/05/2026","text":""},{"location":"Changelog/#bug-fixes_7","title":"Bug fixes","text":""},{"location":"Changelog/#1132-01052026","title":"11.3.2 - 01/05/2026","text":""},{"location":"Changelog/#new-features_5","title":"New Features","text":""},{"location":"Changelog/#bug-fixes_8","title":"Bug fixes","text":""},{"location":"Changelog/#1131-14042026","title":"11.3.1 - 14/04/2026","text":"

Important: 11.3.1 supersedes 11.3.0. Do not use 11.3.0, as it shipped with a broken distributed Swift interface in the packaged SDK binary that could prevent consumer apps from importing the SDK.

"},{"location":"Changelog/#bug-fixes_9","title":"Bug fixes","text":""},{"location":"Changelog/#1130-13042026","title":"11.3.0 - 13/04/2026","text":"

Superseded by 11.3.1. Do not use 11.3.0.

"},{"location":"Changelog/#breaking-changes","title":"Breaking Changes","text":""},{"location":"Changelog/#new-features_6","title":"New Features","text":""},{"location":"Changelog/#bug-fixes_10","title":"Bug fixes","text":""},{"location":"Changelog/#1121-27032026","title":"11.2.1 - 27/03/2026","text":""},{"location":"Changelog/#bug-fixes_11","title":"Bug fixes","text":""},{"location":"Changelog/#1120-21012026","title":"11.2.0 - 21/01/2026","text":""},{"location":"Changelog/#new-features_7","title":"New Features","text":""},{"location":"Changelog/#improvements_6","title":"Improvements","text":""},{"location":"Changelog/#bug-fixes_12","title":"Bug fixes","text":""},{"location":"Changelog/#1110-26122025","title":"11.1.0 - 26/12/2025","text":""},{"location":"Changelog/#breaking-changes_1","title":"Breaking Changes","text":""},{"location":"Changelog/#new-features_8","title":"New Features","text":""},{"location":"Changelog/#bug-fixes_13","title":"Bug fixes","text":""},{"location":"Changelog/#1105-24112025","title":"11.0.5 - 24/11/2025","text":""},{"location":"Changelog/#bug-fixes_14","title":"Bug fixes","text":""},{"location":"Changelog/#1104-12112025","title":"11.0.4 - 12/11/2025","text":""},{"location":"Changelog/#improvements_7","title":"Improvements","text":""},{"location":"Changelog/#1103-11112025","title":"11.0.3 - 11/11/2025","text":""},{"location":"Changelog/#bug-fixes_15","title":"Bug fixes","text":""},{"location":"Changelog/#improvements_8","title":"Improvements","text":""},{"location":"Changelog/#1102-29102025","title":"11.0.2 - 29/10/2025","text":""},{"location":"Changelog/#bug-fixes_16","title":"Bug fixes","text":""},{"location":"Changelog/#improvements_9","title":"Improvements","text":""},{"location":"Changelog/#1101-06102025","title":"11.0.1 - 06/10/2025","text":""},{"location":"Changelog/#bug-fixes_17","title":"Bug fixes","text":""},{"location":"Changelog/#improvements_10","title":"Improvements","text":""},{"location":"Changelog/#1100-03102025","title":"11.0.0 - 03/10/2025","text":""},{"location":"Changelog/#breaking-changes_2","title":"Breaking Changes","text":""},{"location":"Changelog/#new-features_9","title":"New Features","text":""},{"location":"Changelog/#improvements_11","title":"Improvements","text":""},{"location":"Changelog/#bug-fixes_18","title":"Bug fixes","text":""},{"location":"Changelog/#10134-24092025","title":"10.13.4 - 24/09/2025","text":""},{"location":"Changelog/#bug-fixes_19","title":"Bug fixes","text":""},{"location":"Changelog/#improvements_12","title":"Improvements","text":""},{"location":"Changelog/#10133-18082025","title":"10.13.3 - 18/08/2025","text":""},{"location":"Changelog/#bug-fixes_20","title":"Bug fixes","text":""},{"location":"Changelog/#10132-12082025","title":"10.13.2 - 12/08/2025","text":""},{"location":"Changelog/#improvements_13","title":"Improvements","text":""},{"location":"Changelog/#bug-fixes_21","title":"Bug fixes","text":""},{"location":"Changelog/#10131-07082025","title":"10.13.1 - 07/08/2025","text":""},{"location":"Changelog/#bug-fixes_22","title":"Bug fixes","text":""},{"location":"Changelog/#10130-05082025","title":"10.13.0 - 05/08/2025","text":""},{"location":"Changelog/#new-features_10","title":"New Features","text":""},{"location":"Changelog/#improvements_14","title":"Improvements","text":""},{"location":"Changelog/#bug-fixes_23","title":"Bug fixes","text":""},{"location":"Changelog/#10122-10072025","title":"10.12.2 - 10/07/2025","text":""},{"location":"Changelog/#bug-fixes_24","title":"Bug fixes","text":""},{"location":"Changelog/#10121-01072025","title":"10.12.1 - 01/07/2025","text":"

Note - Due to a bug discovered post-release, we do not recommend upgrading to this version. Please use 10.12.2 or above which contains the fix.

"},{"location":"Changelog/#bug-fixes_25","title":"Bug fixes","text":""},{"location":"Changelog/#10120-26062025","title":"10.12.0 - 26/06/2025","text":"

Note - Due to a bug discovered post-release, we do not recommend upgrading to this version. Please use 10.12.2 or above which contains the fix.

"},{"location":"Changelog/#improvements_15","title":"Improvements","text":""},{"location":"Changelog/#bug-fixes_26","title":"Bug fixes","text":""},{"location":"Changelog/#10111-20062025","title":"10.11.1 - 20/06/2025","text":"

Note - Due to a bug discovered post-release, we do not recommend upgrading to this version. Please use 10.12.2 or above which contains the fix.

"},{"location":"Changelog/#bug-fixes_27","title":"Bug fixes","text":""},{"location":"Changelog/#10110-16062025","title":"10.11.0 - 16/06/2025","text":"

Note - Due to a bug discovered post-release, we do not recommend upgrading to this version. Please use 10.12.2 or above which contains the fix.

"},{"location":"Changelog/#bug-fixes_28","title":"Bug fixes","text":""},{"location":"Changelog/#improvements_16","title":"Improvements","text":""},{"location":"Changelog/#deprecations","title":"Deprecations","text":""},{"location":"Changelog/#breaking-changes_3","title":"Breaking Changes","text":""},{"location":"Changelog/#10100-26052025","title":"10.10.0 - 26/05/2025","text":""},{"location":"Changelog/#new-features_11","title":"New Features","text":""},{"location":"Changelog/#improvements_17","title":"Improvements","text":""},{"location":"Changelog/#bug-fixes_29","title":"Bug fixes","text":""},{"location":"Changelog/#deprecations_1","title":"Deprecations","text":""},{"location":"Changelog/#1092-01042025","title":"10.9.2 - 01/04/2025","text":""},{"location":"Changelog/#bug-fixes_30","title":"Bug fixes","text":""},{"location":"Changelog/#1091-26032025","title":"10.9.1 - 26/03/2025","text":""},{"location":"Changelog/#bug-fixes_31","title":"Bug fixes","text":""},{"location":"Changelog/#1090-24032025","title":"10.9.0 - 24/03/2025","text":""},{"location":"Changelog/#new-features_12","title":"New Features","text":""},{"location":"Changelog/#improvements_18","title":"Improvements","text":""},{"location":"Changelog/#bug-fixes_32","title":"Bug fixes","text":""},{"location":"Changelog/#1084-180325","title":"10.8.4 - 18/03/25","text":""},{"location":"Changelog/#bug-fixes_33","title":"Bug fixes","text":""},{"location":"Changelog/#1083-110325","title":"10.8.3 - 11/03/25","text":""},{"location":"Changelog/#improvements_19","title":"Improvements","text":""},{"location":"Changelog/#1082-250225","title":"10.8.2 - 25/02/25","text":""},{"location":"Changelog/#bug-fixes_34","title":"Bug fixes","text":""},{"location":"Changelog/#1081-180225","title":"10.8.1 - 18/02/25","text":""},{"location":"Changelog/#bug-fixes_35","title":"Bug fixes","text":""},{"location":"Changelog/#1080-140225","title":"10.8.0 - 14/02/25","text":""},{"location":"Changelog/#new-features_13","title":"New Features","text":""},{"location":"Changelog/#improvements_20","title":"Improvements","text":""},{"location":"Changelog/#bug-fixes_36","title":"Bug fixes","text":""},{"location":"Changelog/#1077-100225","title":"10.7.7 - 10/02/25","text":""},{"location":"Changelog/#bug-fixes_37","title":"Bug fixes","text":""},{"location":"Changelog/#1076-280125","title":"10.7.6 - 28/01/25","text":""},{"location":"Changelog/#bug-fixes_38","title":"Bug fixes","text":""},{"location":"Changelog/#1075-230125","title":"10.7.5 - 23/01/25","text":""},{"location":"Changelog/#bug-fixes_39","title":"Bug fixes","text":""},{"location":"Changelog/#new-features_14","title":"New Features","text":""},{"location":"Changelog/#1074-241224","title":"10.7.4 - 24/12/24","text":""},{"location":"Changelog/#bug-fixes_40","title":"Bug fixes","text":""},{"location":"Changelog/#1073-171224","title":"10.7.3 - 17/12/24","text":""},{"location":"Changelog/#improvements_21","title":"Improvements","text":""},{"location":"Changelog/#bug-fixes_41","title":"Bug fixes","text":""},{"location":"Changelog/#1072-021224","title":"10.7.2 - 02/12/24","text":""},{"location":"Changelog/#improvements_22","title":"Improvements","text":""},{"location":"Changelog/#1071-271124","title":"10.7.1 - 27/11/24","text":""},{"location":"Changelog/#bug-fixes_42","title":"Bug fixes","text":""},{"location":"Changelog/#1070-191124","title":"10.7.0 - 19/11/24","text":""},{"location":"Changelog/#new-features_15","title":"New Features","text":""},{"location":"Changelog/#improvements_23","title":"Improvements","text":""},{"location":"Changelog/#bug-fixes_43","title":"Bug fixes","text":""},{"location":"Changelog/#1065-080125","title":"10.6.5 - 08/01/25","text":""},{"location":"Changelog/#improvements_24","title":"Improvements","text":""},{"location":"Changelog/#1064-011124","title":"10.6.4 - 01/11/24","text":""},{"location":"Changelog/#improvements_25","title":"Improvements","text":""},{"location":"Changelog/#1063-311024","title":"10.6.3 - 31/10/24","text":""},{"location":"Changelog/#bug-fixes_44","title":"Bug fixes","text":""},{"location":"Changelog/#1062-251024","title":"10.6.2 - 25/10/24","text":""},{"location":"Changelog/#new-features_16","title":"New Features","text":""},{"location":"Changelog/#improvements_26","title":"Improvements","text":""},{"location":"Changelog/#bug-fixes_45","title":"Bug fixes","text":""},{"location":"Changelog/#1061-151024","title":"10.6.1 - 15/10/24","text":""},{"location":"Changelog/#bug-fixes_46","title":"Bug fixes","text":""},{"location":"Changelog/#1060-041024","title":"10.6.0 - 04/10/24","text":""},{"location":"Changelog/#new-features_17","title":"New Features","text":""},{"location":"Changelog/#improvements_27","title":"Improvements","text":""},{"location":"Changelog/#bug-fixes_47","title":"Bug fixes","text":""},{"location":"Changelog/#1053-160924","title":"10.5.3 - 16/09/24","text":""},{"location":"Changelog/#new-features_18","title":"New Features","text":""},{"location":"Changelog/#1052-110924","title":"10.5.2 - 11/09/24","text":""},{"location":"Changelog/#bug-fixes_48","title":"Bug fixes","text":""},{"location":"Changelog/#1051-090924","title":"10.5.1 - 09/09/24","text":""},{"location":"Changelog/#bug-fixes_49","title":"Bug fixes","text":""},{"location":"Changelog/#1050-260824","title":"10.5.0 - 26/08/24","text":""},{"location":"Changelog/#new-features_19","title":"New Features","text":""},{"location":"Changelog/#improvements_28","title":"Improvements","text":""},{"location":"Changelog/#bug-fixes_50","title":"Bug fixes","text":""},{"location":"Changelog/#1041-160824","title":"10.4.1 - 16/08/24","text":""},{"location":"Changelog/#bug-fixes_51","title":"Bug fixes","text":""},{"location":"Changelog/#1040-090824","title":"10.4.0 - 09/08/24","text":""},{"location":"Changelog/#new-features_20","title":"New Features","text":""},{"location":"Changelog/#improvements_29","title":"Improvements","text":""},{"location":"Changelog/#bug-fixes_52","title":"Bug fixes","text":""},{"location":"Changelog/#1031-170724","title":"10.3.1 - 17/07/24","text":""},{"location":"Changelog/#bug-fixes_53","title":"Bug fixes","text":""},{"location":"Changelog/#1030-150724","title":"10.3.0 - 15/07/24","text":""},{"location":"Changelog/#new-features_21","title":"New Features","text":""},{"location":"Changelog/#improvements_30","title":"Improvements","text":""},{"location":"Changelog/#bug-fixes_54","title":"Bug fixes","text":""},{"location":"Changelog/#1021-270624","title":"10.2.1 - 27/06/24","text":""},{"location":"Changelog/#improvements_31","title":"Improvements","text":""},{"location":"Changelog/#1020-19062024","title":"10.2.0 19/06/2024","text":""},{"location":"Changelog/#breaking-changes_4","title":"Breaking Changes","text":""},{"location":"Changelog/#improvements_32","title":"Improvements","text":""},{"location":"Changelog/#bug-fixes_55","title":"Bug Fixes","text":""},{"location":"Changelog/#1012-130624","title":"10.1.2 13/06/24","text":""},{"location":"Changelog/#bug-fixes_56","title":"Bug Fixes","text":""},{"location":"Changelog/#1011-160524","title":"10.1.1 16/05/24","text":""},{"location":"Changelog/#bug-fixes_57","title":"Bug Fixes","text":""},{"location":"Changelog/#1010-150524","title":"10.1.0 15/05/24","text":""},{"location":"Changelog/#new-features_22","title":"New Features","text":""},{"location":"Changelog/#improvements_33","title":"Improvements","text":""},{"location":"Changelog/#bug-fixes_58","title":"Bug Fixes","text":""},{"location":"Changelog/#1001-070524","title":"10.0.1 07/05/24","text":""},{"location":"Changelog/#bug-fixes_59","title":"Bug fixes","text":""},{"location":"Changelog/#1000-180424","title":"10.0.0 18/04/24","text":""},{"location":"Changelog/#new-features_23","title":"New Features","text":""},{"location":"Changelog/#breaking-changes_5","title":"Breaking Changes","text":""},{"location":"Changelog/#improvements_34","title":"Improvements","text":""},{"location":"Changelog/#bug-fixes_60","title":"Bug fixes","text":""},{"location":"Changelog/#9131-020424","title":"9.13.1 02/04/24","text":""},{"location":"Changelog/#improvements_35","title":"Improvements","text":""},{"location":"Changelog/#9130-290324","title":"9.13.0 29/03/24","text":""},{"location":"Changelog/#bug-fixes_61","title":"Bug fixes","text":""},{"location":"Changelog/#new-features_24","title":"New Features","text":""},{"location":"Changelog/#9121-260324","title":"9.12.1 26/03/24","text":""},{"location":"Changelog/#improvements_36","title":"Improvements","text":""},{"location":"Changelog/#9120-200324","title":"9.12.0 20/03/24","text":""},{"location":"Changelog/#bug-fixes_62","title":"Bug fixes","text":""},{"location":"Changelog/#9110-120324","title":"9.11.0 12/03/24","text":""},{"location":"Changelog/#improvements_37","title":"Improvements","text":""},{"location":"Changelog/#9100-280224","title":"9.10.0 28/02/24","text":""},{"location":"Changelog/#improvements_38","title":"Improvements","text":""},{"location":"Changelog/#bug-fixes_63","title":"Bug fixes","text":""},{"location":"Changelog/#991-130224","title":"9.9.1 13/02/24","text":""},{"location":"Changelog/#bug-fixes_64","title":"Bug fixes","text":""},{"location":"Changelog/#990-300124","title":"9.9.0 30/01/24","text":""},{"location":"Changelog/#new-features_25","title":"New Features","text":""},{"location":"Changelog/#breaking-changes_6","title":"Breaking Changes","text":""},{"location":"Changelog/#bug-fixes_65","title":"Bug fixes","text":""},{"location":"Changelog/#981-090124","title":"9.8.1 09/01/24","text":""},{"location":"Changelog/#bug-fixes_66","title":"Bug fixes","text":""},{"location":"Changelog/#980-131223","title":"9.8.0 - 13/12/23","text":""},{"location":"Changelog/#new-features_26","title":"New Features","text":""},{"location":"Changelog/#improvements_39","title":"Improvements","text":""},{"location":"Changelog/#bug-fixes_67","title":"Bug fixes","text":""},{"location":"Changelog/#976-221123","title":"9.7.6 - 22/11/23","text":""},{"location":"Changelog/#bug-fixes_68","title":"Bug fixes","text":""},{"location":"Changelog/#975-211123","title":"9.7.5 - 21/11/23","text":""},{"location":"Changelog/#bug-fixes_69","title":"Bug fixes","text":""},{"location":"Changelog/#974-091123","title":"9.7.4 - 09/11/23","text":""},{"location":"Changelog/#bug-fixes_70","title":"Bug fixes","text":""},{"location":"Changelog/#973-271023","title":"9.7.3 - 27/10/23","text":""},{"location":"Changelog/#bug-fixes_71","title":"Bug fixes","text":""},{"location":"Changelog/#972-131023","title":"9.7.2 - 13/10/23","text":""},{"location":"Changelog/#bug-fixes_72","title":"Bug fixes","text":""},{"location":"Changelog/#971-101023","title":"9.7.1 - 10/10/23","text":""},{"location":"Changelog/#bug-fixes_73","title":"Bug fixes","text":""},{"location":"Changelog/#970-021023","title":"9.7.0 - 02/10/23","text":""},{"location":"Changelog/#new-features_27","title":"New Features","text":""},{"location":"Changelog/#960-190923","title":"9.6.0 - 19/09/23","text":""},{"location":"Changelog/#new-features_28","title":"New Features","text":""},{"location":"Changelog/#improvements_40","title":"Improvements","text":""},{"location":"Changelog/#950-310823","title":"9.5.0 - 31/08/23","text":""},{"location":"Changelog/#new-features_29","title":"New Features","text":""},{"location":"Changelog/#breaking-changes_7","title":"Breaking Changes","text":""},{"location":"Changelog/#improvements_41","title":"Improvements","text":""},{"location":"Changelog/#940-160823","title":"9.4.0 - 16/08/23","text":"

New features:

"},{"location":"Changelog/#930-200723","title":"9.3.0 - 20/07/23","text":"

New features:

Bug fixes:

"},{"location":"Changelog/#921-050723","title":"9.2.1 - 05/07/23","text":"

New features:

"},{"location":"Changelog/#920-080623","title":"9.2.0 - 08/06/23","text":"

New features:

Bug fixes:

Improvements:

"},{"location":"Changelog/#917-310523","title":"9.1.7 - 31/05/23","text":"

Bug fixes:

"},{"location":"Changelog/#916-250523","title":"9.1.6 - 25/05/23","text":"

Bug fixes:

"},{"location":"Changelog/#915-220523","title":"9.1.5 - 22/05/23","text":"

Bug fixes:

Improvements:

"},{"location":"Changelog/#914-170523","title":"9.1.4 - 17/05/23","text":"

Bug fixes:

Improvements:

"},{"location":"Changelog/#913-110523","title":"9.1.3 - 11/05/23","text":"

Bug fixes:

Improvements:

"},{"location":"Changelog/#912-080523","title":"9.1.2 - 08/05/23","text":"

Bug fixes:

"},{"location":"Changelog/#911-030523","title":"9.1.1 - 03/05/23","text":"

Improvements:

"},{"location":"Changelog/#910-020523","title":"9.1.0 - 02/05/23","text":"

New features:

Bug Fixes:

"},{"location":"Changelog/#905-260423","title":"9.0.5 - 26/04/23","text":"

Bug Fixes:

"},{"location":"Changelog/#904-190423","title":"9.0.4 - 19/04/23","text":"

Bug Fixes:

"},{"location":"Changelog/#903-180423","title":"9.0.3 - 18/04/23","text":"

Bug Fixes:

Improvements:

"},{"location":"Changelog/#902-120423","title":"9.0.2 - 12/04/23","text":"

Bug Fixes:

Improvements:

"},{"location":"Changelog/#901-070423","title":"9.0.1 - 07/04/23","text":"

Bug Fixes:

"},{"location":"Changelog/#900-060423","title":"9.0.0 - 06/04/23","text":"

New features:

 StorytellerListView\n \u251c\u2500\u2500 StorytellerRowView\n \u2502   \u251c\u2500\u2500 StorytellerStoriesRowView\n \u2502   \u2514\u2500\u2500 StorytellerClipsRowView\n \u2514\u2500\u2500 StorytellerGridView\n     \u251c\u2500\u2500 StorytellerStoriesGridView\n     \u2514\u2500\u2500 StorytellerClipsGridView\n

Bug Fixes:

Improvements:

"},{"location":"Changelog/#844-80923","title":"8.4.4 - 8/09/23","text":"

Improvements:

"},{"location":"Changelog/#843-270323","title":"8.4.3 - 27/03/23","text":"

Improvements:

"},{"location":"Changelog/#842-160323","title":"8.4.2 - 16/03/23","text":"

Bug Fixes:

Improvements:

"},{"location":"Changelog/#841-150223","title":"8.4.1 - 15/02/23","text":"

Bug Fixes:

"},{"location":"Changelog/#840-130123","title":"8.4.0 - 13/01/23","text":"

Bug Fixes:

"},{"location":"Changelog/#831-201222","title":"8.3.1 - 20/12/22","text":"

Bug Fixes:

Improvements:

"},{"location":"Changelog/#830-091222","title":"8.3.0 - 09/12/22","text":"

Bug Fixes:

Improvements:

"},{"location":"Changelog/#824-301122","title":"8.2.4 - 30/11/22","text":"

Improvements:

"},{"location":"Changelog/#823-251122","title":"8.2.3 - 25/11/22","text":"

Improvements:

"},{"location":"Changelog/#822-101122","title":"8.2.2 - 10/11/22","text":"

Improvements:

Bug Fixes:

"},{"location":"Changelog/#821-011122","title":"8.2.1 - 01/11/22","text":"

Bug Fixes:

Improvements:

"},{"location":"Changelog/#820-111022","title":"8.2.0 - 11/10/22","text":"

New Features:

Bug Fixes:

Improvements:

Deprecations and Changes:

"},{"location":"Changelog/#8114-171022","title":"8.1.14 - 17/10/22","text":"

New Features:

"},{"location":"Changelog/#8113-210922","title":"8.1.13 - 21/09/22","text":"

Bug Fixes:

Deprecations and Changes:

"},{"location":"Changelog/#8112-010922","title":"8.1.12- 01/09/22","text":"

Bug Fixes:

"},{"location":"Changelog/#8111-250822","title":"8.1.11 - 25/08/22","text":"

Bug Fixes:

"},{"location":"Changelog/#8110-240822","title":"8.1.10 - 24/08/22","text":"

Bug Fixes:

"},{"location":"Changelog/#819-230822","title":"8.1.9 - 23/08/22","text":"

Bug Fixes:

New Features:

Improvements:

"},{"location":"Changelog/#818-120822","title":"8.1.8 - 12/08/22","text":"

Bug Fixes:

UI Changes:

"},{"location":"Changelog/#817-100822","title":"8.1.7 - 10/08/22","text":"

Bug Fixes:

New Features:

"},{"location":"Changelog/#816-100822","title":"8.1.6 - 10/08/22","text":"

Bug Fixes:

New Features:

Deprecations and Changes:

"},{"location":"Changelog/#815-050822","title":"8.1.5 - 05/08/22","text":"

Bug Fixes:

"},{"location":"Changelog/#814-030822","title":"8.1.4 - 03/08/22","text":"

Deprecations and Changes:

"},{"location":"Changelog/#813-020822","title":"8.1.3 - 02/08/22","text":"

Bug Fixes:

"},{"location":"Changelog/#812-020822","title":"8.1.2 - 02/08/22","text":"

UI Changes:

"},{"location":"Changelog/#811-290722","title":"8.1.1 - 29/07/22","text":"

Bug Fixes:

UI Changes:

"},{"location":"Changelog/#810-130722","title":"8.1.0 - 13/07/22","text":"

Bug Fixes:

"},{"location":"Changelog/#802-110722","title":"8.0.2 - 11/07/22","text":"

UI Changes:

Deprecations and Changes:

"},{"location":"Changelog/#801-240622","title":"8.0.1 - 24/06/22","text":"

UI Changes:

New Features:

Deprecations and Changes:

"},{"location":"Deeplinking/","title":"Deep linking","text":"

To make sharing and direct content links work, first complete the shared domain and CMS setup, then implement the URL-receiving route for either UIKit or SwiftUI. Both frameworks use Storyteller.shared.isStorytellerDeepLink(url:) and Storyteller.shared.openDeepLink(url:) after the app receives a URL.

"},{"location":"Deeplinking/#understanding-link-types","title":"Understanding Link Types","text":"

iOS apps support two types of deep links, each serving different purposes:

"},{"location":"Deeplinking/#universal-links-https-urls","title":"Universal Links (HTTPS URLs)","text":""},{"location":"Deeplinking/#url-scheme-links-custom-urls","title":"URL Scheme Links (Custom URLs)","text":"

Important: Push notifications on iOS do not support Universal Links for directly opening apps. You must use URL Scheme Links in push notification payloads to ensure your app opens correctly.

"},{"location":"Deeplinking/#add-associated-domain-to-your-project-settings-in-xcode","title":"Add Associated Domain to Your Project Settings in Xcode","text":"

At first you need to add associated domain to your projects.

1. Go to your project settings in Xcode -> Signing & Capabilities

2. Press +Capability

3. Choose Associated Domains

4. Add the following domains:

"},{"location":"Deeplinking/#add-bundle-identifier-to-storyteller-cms","title":"Add Bundle Identifier to Storyteller CMS","text":"

After setting up an associated domain you need to add a bundle identifier to Storyteller CMS.

1. Log into Storyteller CMS

2. Go to Apps

3. Create a new iOS app or edit existing one

4. Fill out App ID

App ID has the form <Application Identifier Prefix>.<Bundle Identifier> e.g. ABCDE12345.com.example.app

5. Press Save

"},{"location":"Deeplinking/#register-a-custom-url-scheme-for-your-app","title":"Register a Custom URL Scheme for your app","text":"

Our SDK supports deeplinking through custom URL schemes. Custom URL schemes allow your application to be launched in a specific context from a custom URL. This is essential for push notifications, as iOS does not support Universal Links from push notifications.

In order to use the custom URL scheme supported by our SDK, you need to register it with the following format: [TENANT_NAME]stories://, E.g. gosportsstories://.

You can follow the next steps to do so:

1. Go to Info tab in your Xcode project settings

2. Expand URL Types section and add a new URL Type entry. For the Identifier field, you should use a unique identifier, like your app's bundle identifier for example. In URL Schemes, enter [TENANT_NAME]stories, replacing [TENANT_NAME] with your respective Storyteller tenant name. The Role field is only used for macOS applications, and can be ignored on iOS and other platforms.

After following these steps, your app should be able to directly launch our SDK in a specific context from a URL with a custom scheme.

Push Notifications: URL scheme links are essential for opening your app from push notifications. See the Handling URL Scheme Links from Push Notifications section below for implementation details.

This feature can be used for example, to directly open a story or a clip with a deeplink url. To directly open a story, the SDK will handle deeplinks with the following format:

Or to open a clip:

"},{"location":"Deeplinking/#handle-links-in-your-app","title":"Handle Links in Your App","text":"

StorytellerSDK provides two framework-independent methods:

let url = URL(string: \"https://example.shar.estori.es/open/story-id/page-id\")!\nlet isStorytellerLink = Storyteller.shared.isStorytellerDeepLink(url: url)\n

This method takes in a URL and returns true if the URL is Storyteller deep link.

let url = URL(string: \"https://example.shar.estori.es/open/story-id/page-id\")!\ntry await Storyteller.shared.openDeepLink(url: url)\n

This method opens the Story/Clip that was specified in the URL.

"},{"location":"Deeplinking/#examples","title":"Examples","text":"

Choose the URL-receiving route for your app. UIKit receives Universal Links and custom schemes through app- or scene-delegate methods, depending on the lifecycle your app uses. SwiftUI receives both link types through .onOpenURL.

UIKitSwiftUI

Apply .onOpenURL to a stable root view. SwiftUI sends both Universal Links and custom URL schemes to this modifier.

import StorytellerSDK\nimport SwiftUI\n\n@available(iOS 14.0, *)\nstruct StorytellerAppRootView: View {\n    var body: some View {\n        Text(\"App content\")\n            .onOpenURL { url in\n                openStorytellerURL(url)\n            }\n    }\n\n    private func openStorytellerURL(_ url: URL) {\n        guard Storyteller.shared.isStorytellerDeepLink(url: url) else { return }\n\n        Task { @MainActor in\n            do {\n                try await Storyteller.shared.openDeepLink(url: url)\n            } catch {\n                print(\"Unable to open Storyteller link: \\(error.localizedDescription)\")\n            }\n        }\n    }\n}\n

The Showcase app demonstrates forwarding the received URL from .onOpenURL into a shared AppDelegate handler.

After completing the shared setup and one framework route, test both an HTTPS Universal Link and your tenant's custom URL scheme.

"},{"location":"Deeplinking/#add-handling-deep-link-to-your-appdelegate-or-uiscenedelegate","title":"Add handling deep link to your AppDelegate or UISceneDelegate","text":"

Use UIApplicationDelegate when your app owns lifecycle handling there:

import UIKit\nimport StorytellerSDK\n\nfinal class AppDelegate: UIResponder, UIApplicationDelegate {\n    func application(\n        _ application: UIApplication,\n        continue userActivity: NSUserActivity,\n        restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void\n    ) -> Bool {\n        guard userActivity.activityType == NSUserActivityTypeBrowsingWeb,\n              let url = userActivity.webpageURL else {\n            return false\n        }\n\n        return openStorytellerURL(url)\n    }\n\n    func application(\n        _ app: UIApplication,\n        open url: URL,\n        options: [UIApplication.OpenURLOptionsKey: Any] = [:]\n    ) -> Bool {\n        openStorytellerURL(url)\n    }\n\n    private func openStorytellerURL(_ url: URL) -> Bool {\n        guard Storyteller.shared.isStorytellerDeepLink(url: url) else {\n            return false\n        }\n\n        Task { @MainActor in\n            do {\n                try await Storyteller.shared.openDeepLink(url: url)\n            } catch {\n                print(\"Unable to open Storyteller link: \\(error.localizedDescription)\")\n            }\n        }\n        return true\n    }\n}\n

If your app uses scenes, add cold-start handling to your existing scene(_:willConnectTo:options:) implementation and keep the continuation methods for links received while the scene is already connected:

import UIKit\nimport StorytellerSDK\n\nfinal class SceneDelegate: UIResponder, UIWindowSceneDelegate {\n    func scene(\n        _ scene: UIScene,\n        willConnectTo session: UISceneSession,\n        options connectionOptions: UIScene.ConnectionOptions\n    ) {\n        if let url = connectionOptions.userActivities.lazy\n            .filter({ $0.activityType == NSUserActivityTypeBrowsingWeb })\n            .compactMap(\\.webpageURL)\n            .first(where: { Storyteller.shared.isStorytellerDeepLink(url: $0) }) {\n            openStorytellerURL(url)\n            return\n        }\n\n        guard let url = connectionOptions.urlContexts.lazy\n            .map(\\.url)\n            .first(where: { Storyteller.shared.isStorytellerDeepLink(url: $0) })\n        else {\n            return\n        }\n\n        openStorytellerURL(url)\n    }\n\n    func scene(_ scene: UIScene, continue userActivity: NSUserActivity) {\n        guard userActivity.activityType == NSUserActivityTypeBrowsingWeb,\n              let url = userActivity.webpageURL else {\n            return\n        }\n\n        openStorytellerURL(url)\n    }\n\n    func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {\n        guard let url = URLContexts.lazy\n            .map(\\.url)\n            .first(where: { Storyteller.shared.isStorytellerDeepLink(url: $0) })\n        else {\n            return\n        }\n\n        openStorytellerURL(url)\n    }\n\n    private func openStorytellerURL(_ url: URL) {\n        guard Storyteller.shared.isStorytellerDeepLink(url: url) else { return }\n\n        Task { @MainActor in\n            do {\n                try await Storyteller.shared.openDeepLink(url: url)\n            } catch {\n                print(\"Unable to open Storyteller link: \\(error.localizedDescription)\")\n            }\n        }\n    }\n}\n

For a UIKit app entrypoint using CocoaPods, see the Showcase AppDelegate.

"},{"location":"Deeplinking/#handling-url-scheme-links-from-push-notifications","title":"Handling URL Scheme Links from Push Notifications","text":"

When using push notifications to deep link into Storyteller content, you must use URL scheme links (not Universal Links) in your notification payload. Here's how to implement this:

"},{"location":"Deeplinking/#push-notification-payload","title":"Push Notification Payload","text":"

Include a custom URL scheme link in your push notification payload:

{\n    \"aps\": {\n        \"alert\": {\n            \"title\": \"Check out this story!\",\n            \"body\": \"Tap to view the latest content\"\n        }\n    },\n    \"deeplink_url\": \"[tenant_name]stories://open/STORY_ID/PAGE_ID\"\n}\n
"},{"location":"Deeplinking/#handling-the-deep-link","title":"Handling the Deep Link","text":"

The notification should open the custom-scheme URL through the same framework route configured in Handle Links in Your App:

There is no second Storyteller integration path for push notifications. Extract the URL from the notification payload, ask the system to open it, and let your existing URL handler validate and open the Storyteller content.

"},{"location":"Deeplinking/#extracting-deep-links-from-push-notifications","title":"Extracting Deep Links from Push Notifications","text":"

In your UNUserNotificationCenterDelegate:

@MainActor\nfunc userNotificationCenter(_ center: UNUserNotificationCenter, didReceive response: UNNotificationResponse) async {\n    let userInfo = response.notification.request.content.userInfo\n\n    guard\n        let deepLink = userInfo[\"deeplink_url\"] as? String,\n        let url = URL(string: deepLink)\n    else {\n        return\n    }\n\n    // This will trigger onOpenURL in SwiftUI or application(_:open:options:) in UIKit\n    await UIApplication.shared.open(url)\n}\n
"},{"location":"Deeplinking/#deep-link-handling-details","title":"Deep Link Handling Details","text":"

The Storyteller.shared.openDeepLink function intelligently parses the provided URL (which can be either an HTTPS link via Associated Domains or a custom scheme link) to determine the type of content to open.

"},{"location":"Deeplinking/#story-category","title":"Story Category","text":""},{"location":"Deeplinking/#clip-collection","title":"Clip Collection","text":""},{"location":"Deeplinking/#story-page","title":"Story / Page","text":""},{"location":"Deeplinking/#sheet","title":"Sheet","text":""},{"location":"Deeplinking/#manual-deep-link-handling","title":"Manual Deep Link Handling","text":"

While Storyteller.shared.openDeepLink provides convenience, you might require more control over your app's state or navigation when a deep link is handled. In such cases, it's recommended to parse the URL yourself (after checking it with Storyteller.shared.isStorytellerDeepLink) and then use the specific Storyteller methods like openStory(id:), openPage(id:), openCollection(configuration:), openCategory(category:), or openSheet(id:) to present the content. This approach allows for custom transitions, loading states, or error handling specific to your application flow. Refer to the Open Player documentation for details on these methods.

"},{"location":"Deeplinking/#api-reference","title":"API Reference","text":""},{"location":"Deeplinking/#isstorytellerdeeplink","title":"isStorytellerDeepLink","text":"
let url = URL(string: \"exampletenantstories://open/story-id/page-id\")!\nlet isStorytellerLink = Storyteller.shared.isStorytellerDeepLink(url: url)\n

Checks if the given url is Storyteller deep link.

"},{"location":"Deeplinking/#opendeeplink","title":"openDeepLink","text":"
let url = URL(string: \"exampletenantstories://open/story-id/page-id\")!\ntry await Storyteller.shared.openDeepLink(url: url)\n

This call makes Storyteller open the provided deep link (showing the requested Page / Story / Clip).

Parameters:

  1. url - deep link url.

Throws if there is an issue with opening the Deeplink (e.g. the requested content is not available).

"},{"location":"EmbeddedClips/","title":"Embedded Clips","text":"

Use Embedded Clips when you want the full Clips Player inside your own view hierarchy rather than presenting it programmatically. UIKit apps use StorytellerClipsViewController; SwiftUI apps use StorytellerClipsView with a StorytellerClipsModel.

If you need Clip tiles in a row or grid rather than an embedded Player, use Storyteller List Views.

topLevelBackButtonEnabled defaults to false in both framework routes.

"},{"location":"EmbeddedClips/#adding-it-in-the-ui","title":"Adding it in the UI","text":"UIKitSwiftUI

Place StorytellerClipsViewController inside a UITabBarController:

let embeddedClipsVC = StorytellerClipsViewController()\nlet tabBarVC = UITabBarController()\nlet otherVC = UIViewController()\ntabBarVC.setViewControllers([embeddedClipsVC, otherVC], animated: false)\n

Or add it to a custom view-controller hierarchy:

final class ClipsHostViewController: UIViewController {\n    private let embeddedClipsVC = StorytellerClipsViewController()\n\n    override func viewDidLoad() {\n        super.viewDidLoad()\n\n        addChild(embeddedClipsVC)\n        view.addSubview(embeddedClipsVC.view)\n        // Add Auto Layout constraints here.\n        embeddedClipsVC.didMove(toParent: self)\n    }\n}\n

StorytellerClipsViewController exposes:

For a UIKit integration using CocoaPods, see EmbeddedClipsViewController.

Create and retain a StorytellerClipsModel, then pass it to StorytellerClipsView. Handle actions in the view callback rather than assigning a delegate.

import SwiftUI\nimport StorytellerSDK\n\n@available(iOS 14.0, *)\nstruct ExampleSwiftUIView: View {\n    @Environment(\\.presentationMode) private var presentationMode\n    @StateObject var model = StorytellerClipsModel(\n        configuration: StorytellerClipCollectionConfiguration(collectionId: \"test-collection\"),\n        topLevelBackButtonEnabled: true\n    )\n\n    var body: some View {\n        StorytellerClipsView(model: model) { action in\n            if case .onTopLevelBackTapped = action {\n                presentationMode.wrappedValue.dismiss()\n            }\n        }\n    }\n}\n

StorytellerClipsModel exposes the shared configuration, topLevelBackButtonEnabled, and canGoBack values, plus reloadData(), willShow(), and willHide().

For a SwiftUI integration with configuration, reload cadence, and context injection, see the Showcase implementation in ClipsViewModel and ClipsView.

"},{"location":"EmbeddedClips/#back-navigation","title":"Back navigation","text":"

canGoBack is a read-only capability query; it does not perform navigation and it does not describe the host app's navigation stack. When it is true, the SDK owns navigation back from the current nested category screen. At the collection root it is false, even if the host app itself has somewhere to navigate back to.

To expose host-owned back navigation at the collection root, set topLevelBackButtonEnabled to true, then handle the callback for your framework:

UIKitSwiftUI

Handle topLevelBackTapped() on the delegate. The default implementation for delegates that are also UIViewController instances pops the nearest host navigation controller. Override it for a custom route:

import StorytellerSDK\nimport UIKit\n\nfinal class ClipsHostViewController: UIViewController, StorytellerClipsViewControllerDelegate {\n    func topLevelBackTapped() {\n        navigationController?.popViewController(animated: true)\n    }\n\n    func onDataLoadStarted() {}\n\n    func onDataLoadComplete(success: Bool, error: Error?) {}\n}\n

Handle .onTopLevelBackTapped in the StorytellerClipsView action closure and perform host-owned navigation, as shown in the SwiftUI setup above. model.canGoBack has the same root and nested behavior as the UIKit property.

In SDK versions 10.6.0 through 11.5.1, canGoBack returned the inverse result because of a regression. Version 11.6.0 restores the contract described above. If your integration negated canGoBack as a workaround, remove that negation when upgrading.

"},{"location":"EmbeddedClips/#loading-clips","title":"Loading Clips","text":"

Use StorytellerClipCollectionConfiguration when configuring an embedded or programmatically presented Clip Player. Use StorytellerClipsListConfiguration only for Clip row and grid tile views such as StorytellerClipsRowView and StorytellerClipsGridView. The types are not interchangeable: list configuration controls tile layout and limits, while collection configuration controls Player destination, presentation theme, analytics context, and Ad placements.

StorytellerClipCollectionConfiguration has the following properties:

Apply the shared configuration through the route for your framework:

UIKitSwiftUI

Call configure(with:) on the embedded view controller:

let embeddedClipsVC = StorytellerClipsViewController()\nlet configuration = StorytellerClipCollectionConfiguration(collectionId: \"top-plays\")\nembeddedClipsVC.configure(with: configuration)\n

Calling configure(with:) does not reload data when collectionId and destination are unchanged. Call reloadData() to force a refresh.

Supply the configuration when creating StorytellerClipsModel. Update the model or call its methods to control the existing embedded Player:

let model = StorytellerClipsModel(\n    configuration: StorytellerClipCollectionConfiguration(collectionId: \"collection-id\"),\n    topLevelBackButtonEnabled: true\n)\n\nlet configuration = model.configuration\nlet showsTopLevelBackButton = model.topLevelBackButtonEnabled\nlet canGoBack = model.canGoBack\n\nmodel.reloadData()\nmodel.willShow()\nmodel.willHide()\n

SwiftUI reloads when the supplied model changes. Call model.reloadData() to refresh without changing its configuration.

To opt an embedded Clips presentation into opening pre-roll Ads, set the placement on the shared configuration:

let preRollConfiguration = StorytellerClipCollectionConfiguration(\n    collectionId: \"top-plays\",\n    adConfiguration: StorytellerClipsAdConfiguration(preRollEnabled: true)\n)\n

To opt an embedded Clips presentation into bottom banner Ads:

let bottomBannerConfiguration = StorytellerClipCollectionConfiguration(\n    collectionId: \"top-plays\",\n    adConfiguration: StorytellerClipsAdConfiguration(bottomBannerEnabled: true)\n)\n

Supply either configuration to the UIKit view controller or SwiftUI model. Local opt-in does not replace the matching tenant and provider configuration described in Ads.

Possible values for StorytellerClipCollectionConfiguration.Destination are:

let categoryDestination: StorytellerClipCollectionConfiguration.Destination = .category(id: \"category-id\")\nlet clipDestination: StorytellerClipCollectionConfiguration.Destination = .clip(id: \"clip-id\")\n

An invalid or unavailable destination falls back to the first Clip.

"},{"location":"EmbeddedClips/#auto-pause","title":"Auto-pause","text":"

Besides when the user pauses the Clips Player, the SDK automatically pauses or plays based on visibility changes, such as backgrounding the app or switching tabs. If you have a scenario that is not covered, such as displaying a modal over the Player, send visibility hints through the UIKit view controller or SwiftUI model:

Note: Auto-pausing respects the user's explicit pause state. If the user manually paused, willShow() will not automatically resume playback.

"},{"location":"EmbeddedClips/#reloaddata","title":"ReloadData","text":"

Call reloadData() on the UIKit view controller or SwiftUI model to trigger a new request and reset the Player to its initial state.

Note: If category filters are currently applied when reloadData() is called, the player will navigate back one level in the category stack instead of reloading the entire collection. If no category filters are applied, it reloads the top-level collection data.

"},{"location":"EmbeddedClips/#delegate","title":"Delegate","text":"

Use the callback mechanism for your framework:

Event UIKit SwiftUI Loading starts StorytellerClipsViewControllerDelegate.onDataLoadStarted() .onDataLoadStarted action Loading completes StorytellerClipsViewControllerDelegate.onDataLoadComplete(success:error:) .onDataLoadComplete(success:error:) action Top-level back tapped StorytellerClipsViewControllerDelegate.topLevelBackTapped() .onTopLevelBackTapped action

The view controller holds its delegate weakly, so retain the delegate in your app. SwiftUI receives the same events through the StorytellerClipsView action closure shown above.

"},{"location":"EmbeddedClips/#safe-area-inset-management","title":"Safe Area / Inset Management","text":"

Constrain the UIKit view controller or SwiftUI wrapper to a non-zero area that respects the host safe area. This prevents Player controls from being obscured by navigation, status, or tab bars.

"},{"location":"EmbeddedClips/#continue-your-integration","title":"Continue Your Integration","text":""},{"location":"MigrationGuideV11/","title":"Migrating to version 11","text":"

This guide helps you migrate from Storyteller SDK version 10.x.x to 11.0.x. Version 11.0.x introduces several breaking changes that improve the SDK's architecture and consistency. Version 11 focuses on three major architectural improvements:

"},{"location":"MigrationGuideV11/#storyteller-shared-instance","title":"Storyteller shared instance","text":"

The Storyteller class has moved from using static methods to a shared instance pattern. All API calls must now use Storyteller.shared instead of calling static methods directly on the class.

"},{"location":"MigrationGuideV11/#usage-example","title":"Usage example","text":"

Before (10.x.x):

Storyteller.delegate = myDelegate\n

After (11.x.x):

final class DelegateObject: StorytellerDelegate {}\nlet myDelegate = DelegateObject()\nStoryteller.shared.delegate = myDelegate\n

See the shared instance pattern in the Showcase app where Storyteller.shared.modules, Storyteller.shared.theme, and Storyteller.shared.delegate are configured in AppDelegate.setupStoryteller.

"},{"location":"MigrationGuideV11/#storyteller-prefix-for-public-types","title":"Storyteller Prefix for Public Types","text":"

All public types now start with the Storyteller prefix for better namespace consistency and to avoid naming conflicts with your app code.

"},{"location":"MigrationGuideV11/#type-renames","title":"Type Renames","text":"Old Name New Name UserInput StorytellerUserInput ClipCollectionConfiguration StorytellerClipCollectionConfiguration Placement StorytellerPlacement Category StorytellerCategory CategoryDetail StorytellerCategoryDetail CurrentCategoryData StorytellerCurrentCategoryData UserActivity StorytellerUserActivity UserActivityData StorytellerUserActivityData CodableIgnored StorytellerCodableIgnored Alignment StorytellerAlignment FontProvider StorytellerFontProvider TextCasing StorytellerTextCasing PlayerIcons StorytellerPlayerIcons InstructionIcons StorytellerInstructionIcons"},{"location":"MigrationGuideV11/#asyncawait-functions","title":"Async/Await functions","text":"

All callback-based APIs have been replaced with modern Swift async/await patterns. The following Storyteller.shared methods are now async functions:

"},{"location":"MigrationGuideV11/#migration-examples","title":"Migration Examples","text":"

Before (10.x.x):

Storyteller.initialize(\n    apiKey: \"your-api-key\",\n    onComplete: {\n        print(\"SDK initialized successfully\")\n    },\n    onError: { error in\n        print(\"Initialization failed: \\(error)\")\n    }\n)\n

After (11.x.x):

Task {\n    do {\n        try await Storyteller.shared.initialize(apiKey: \"your-api-key\")\n        print(\"SDK initialized successfully\")\n    } catch {\n        print(\"Initialization failed: \\(error)\")\n    }\n}\n

See the Showcase initialization flow using async/await in StorytellerService.setup.

"},{"location":"MigrationGuideV11/#additional-breaking-changes","title":"Additional Breaking Changes","text":""},{"location":"MigrationGuideV11/#event-tracking-options","title":"Event Tracking Options","text":"

eventTrackingOptions can now only be set during SDK initialization:

Before (10.x.x):

// Initialize SDK\nStoryteller.initialize(\n    apiKey: \"your-api-key\",\n    onComplete: {\n        print(\"SDK initialized successfully\")\n    },\n    onError: { error in\n        print(\"Initialization failed: \\(error)\")\n    }\n)\n\n// Later in the code, modify tracking options\nStoryteller.eventTrackingOptions = StorytellerEventTrackingOptions(\n    enablePersonalization: true,\n    enableStorytellerTracking: true,\n    enableUserActivityTracking: true,\n    enableAdTracking: true,\n    enableFullVideoAnalytics: true,\n    enableRemoteViewingStore: true,\n    disabledFunctionalFeatures: []\n)\n

After (11.x.x):

// Set tracking options during initialization\nlet trackingOptions = StorytellerEventTrackingOptions(\n    enablePersonalization: true,\n    enableStorytellerTracking: true,\n    enableUserActivityTracking: true,\n    enableAdTracking: true,\n    enableFullVideoAnalytics: true,\n    enableRemoteViewingStore: true,\n    disabledFunctionalFeatures: []\n)\n\nlet userInput = StorytellerUserInput(externalId: \"user-id\")\n\nTask {\n    try await Storyteller.shared.initialize(\n        apiKey: \"your-api-key\",\n        userInput: userInput,\n        eventTrackingOptions: trackingOptions\n    )\n}\n

See how the Showcase app builds StorytellerEventTrackingOptions and passes them during initialization in StorytellerService.setup.

To change tracking options after initialization, you must reinitialize the SDK. See Privacy and Tracking for more information.

"},{"location":"MigrationGuideV11/#swiftui-grids","title":"SwiftUI Grids","text":"

The isScrollable parameter no longer has a default value and must be explicitly provided:

Before (10.x.x):

// isScrollable defaulted to false\nStorytellerStoriesGrid(model: storiesModel)\nStorytellerClipsGrid(model: clipsModel)\n

After (11.x.x):

// isScrollable must be explicitly provided\nlet storiesModel = StorytellerStoriesListModel(\n    configuration: StorytellerStoriesListConfiguration(categories: [\"category-id\"])\n)\nlet clipsModel = StorytellerClipsListModel(\n    configuration: StorytellerClipsListConfiguration(collectionId: \"collection-id\")\n)\nStorytellerStoriesGrid(isScrollable: false, model: storiesModel)\nStorytellerClipsGrid(isScrollable: false, model: clipsModel)\n

See the Showcase SwiftUI grid usage in StoriesListView.

"},{"location":"MigrationGuideV11/#storytellerlistviewdelegate","title":"StorytellerListViewDelegate","text":"

The onTileTapped method now provides richer context via the StorytellerTileType enum:

Before (10.x.x):

extension MyViewController: StorytellerListViewDelegate {\n    func onTileTapped(id: String) {\n        print(\"Tapped tile with ID: \\(id)\")\n    }\n}\n

After (11.x.x):

final class MyViewController: UIViewController, StorytellerListViewDelegate {\n    nonisolated func onTileTapped(type: StorytellerTileType) {\n        switch type {\n        case .clip(let clipId, let collectionId, let categories):\n            print(\"Tapped clip: \\(clipId) in collection: \\(collectionId), categories: \\(categories)\")\n        case .story(let storyId, let categories):\n            print(\"Tapped story: \\(storyId), categories: \\(categories)\")\n        @unknown default:\n            break\n        }\n    }\n}\n

See the Showcase onTileTapped flow (including categories) in StorytellerItemView.listAction.

"},{"location":"MigrationGuideV11/#other-breaking-changes","title":"Other breaking changes","text":"

The following theme properties have been removed and are now configured in the CMS:

"},{"location":"MigrationGuideV11/#need-help","title":"Need Help","text":"

If you encounter any issues during the migration:

  1. Check the Changelog for a detailed version history
  2. Don't hesitate to reach out if you continue to face difficulties
"},{"location":"NavigatingToApp/","title":"Navigating to App","text":"

A StorytellerDelegate has a method for managing in app navigation. It can be used for custom handling of deeplink URLs which can configured per page in CMS. This method will be called when user presses on the action button with the deeplink navigation type.

"},{"location":"NavigatingToApp/#how-to-use","title":"How to Use","text":"

To use global userNavigatedToApp, implement the StorytellerDelegate interface by overriding the required methods and set it in Storyteller object. userNavigatedToApp(url: String) is the method responsible for handling these deeplink URLs.

The Showcase app wires this end-to-end: userNavigatedToApp is implemented in StorytellerInstanceDelegate.userNavigatedToApp and routes to Router.navigateToActionLink.

"},{"location":"NavigatingToApp/#navigation-to-the-integrating-app","title":"Navigation to the Integrating App","text":"

The callback userNavigatedToApp is called when a user taps on an action button on a page which has its link type set to deeplink. In this case, your app will be passed a URL which has been entered in the Storyteller CMS and your app is then responsible for parsing this URL and following it to the correct location within your app.

Example:

func userNavigatedToApp(url: String) {\n    // parse the url and navigate to the destination\n}\n
"},{"location":"OpenPlayer/","title":"Open Player","text":"

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\n\nfunc openFeaturedStory() {\n    Task { @MainActor in\n        do {\n            try await Storyteller.shared.openStory(id: \"featured-story\")\n        } catch {\n            print(\"Unable to open Story: \\(error.localizedDescription)\")\n        }\n    }\n}\n
"},{"location":"OpenPlayer/#opening-stories-categories","title":"Opening Stories & Categories","text":""},{"location":"OpenPlayer/#opencategory","title":"openCategory","text":"

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

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

See the Showcase usage of openCategory in FeedImageView.

Parameters:

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

"},{"location":"OpenPlayer/#openstory-by-id","title":"openStory (by ID)","text":"

Opens a single Story by its specific ID.

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

Parameters:

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

"},{"location":"OpenPlayer/#openstory-by-external-id","title":"openStory (by External ID)","text":"

Opens a single Story by its assigned external ID.

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

Parameters:

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

"},{"location":"OpenPlayer/#openpage","title":"openPage","text":"

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\")\n

Parameters:

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

"},{"location":"OpenPlayer/#opening-clips-collections","title":"Opening Clips & Collections","text":""},{"location":"OpenPlayer/#opencollection","title":"openCollection","text":"

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

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

Parameters:

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\n\nfunc openTopPlays() {\n    let configuration = StorytellerClipCollectionConfiguration(\n        collectionId: \"top-plays\",\n        context: [\"location\": \"home\"]\n    )\n\n    Task { @MainActor in\n        do {\n            try await Storyteller.shared.openCollection(configuration: configuration)\n        } catch {\n            print(\"Unable to open Clips: \\(error.localizedDescription)\")\n        }\n    }\n}\n
"},{"location":"OpenPlayer/#open-reason-enum","title":"Open Reason Enum","text":"

The optional openReason parameter accepts values of StorytellerOpenReason:

let openReason: StorytellerOpenReason = .instanceMethod\n

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

"},{"location":"OpenPlayer/#openclipbyexternalid","title":"openClipByExternalId","text":"

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(\n    collectionId: \"collection-id\",\n    externalId: \"clip-external-id\"\n)\n

Parameters:

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

"},{"location":"PrivacyAndTracking/","title":"Privacy and Tracking","text":"

The eventTrackingOptions property customizes Storyteller's analytics and tracking behavior. It allows certain features to be disabled based on user privacy choices. It is an object of type StorytellerEventTrackingOptions and by default, all of its properties are enabled.

To receive and forward events in your own analytics system, follow Integrate Analytics. This page defines the privacy and tracking controls used by that setup.

Important: eventTrackingOptions can only be set during SDK initialization. To configure tracking options, pass a StorytellerEventTrackingOptions object to the initialize method. The default value is .enableAll:

// Using custom tracking options\nlet trackingOptions = StorytellerEventTrackingOptions(\n    enablePersonalization: false,\n    enableStorytellerTracking: false,\n    enableUserActivityTracking: false,\n    enableAdTracking: false,\n    enableFullVideoAnalytics: false,\n    enableRemoteViewingStore: false,\n    disabledFunctionalFeatures: []\n)\n\ntry await Storyteller.shared.initialize(\n    apiKey: \"your-api-key\",\n    userInput: StorytellerUserInput(externalId: \"user-id\"),\n    eventTrackingOptions: trackingOptions\n)\n\n// Or use the default .enableAll (all tracking enabled)\ntry await Storyteller.shared.initialize(\n    apiKey: \"your-api-key\",\n    userInput: StorytellerUserInput(externalId: \"user-id\")\n)\n

For a full integration, see how the Showcase app builds StorytellerEventTrackingOptions and initializes the SDK in StorytellerService.setup.

The property remains publicly readable via Storyteller.shared.eventTrackingOptions, but can no longer be modified at runtime. To change tracking options after initialization, you must reinitialize the SDK with new options.

If an expected event or Ad callback is missing, follow Callbacks or Analytics Events Do Not Arrive before changing privacy settings; data loading, user-activity delivery, and Ad analytics use different callback paths.

"},{"location":"PrivacyAndTracking/#user-personalization","title":"User Personalization","text":"

When enablePersonalization is enabled, supported Storyteller requests include user attributes so the returned content can be personalized. The standard userId query parameter is included on supported personalization requests only when both enablePersonalization and enableRemoteViewingStore are enabled.

enableRemoteViewingStore also controls separate requests used to retrieve and record viewing activity and synchronize followed categories. When it is enabled, those requests can include the stored hashed user ID even when enablePersonalization is disabled.

"},{"location":"PrivacyAndTracking/#storyteller-tracking","title":"Storyteller tracking","text":"

When enableStorytellerTracking is enabled, we will record analytics events on our servers. Note that some events are necessary for user functionality and will still be transmitted (but not stored) even when this setting is off.

"},{"location":"PrivacyAndTracking/#user-activity-tracking","title":"User Activity tracking","text":"

When enableUserActivityTracking is enabled, we call the Storyteller delegate's method onUserActivityOccurred(), which allows integrating apps to record our analytics events on their own systems. When it is disabled, the callback is not invoked. Ad loading callbacks such as getAd and getBottomBannerAd are separate integration APIs and do not change that user-activity callback gate.

"},{"location":"PrivacyAndTracking/#ads-tracking","title":"Ads tracking","text":"

When enableAdTracking is disabled, ad-related events will not be tracked through onUserActivityOccurred() Storyteller delegate method and on our servers. Additionally, only necessary fields like Ad Unit Id and Custom Template Id's will be included in GAM requests.

"},{"location":"PrivacyAndTracking/#videos-tracking","title":"Videos tracking","text":"

When enableFullVideoAnalytics is disabled, sensitive video event data for Story ID, Page ID, Story Title, Page Title, Clip ID, Clip Title, Story Display Title, Item Title, Container Title, Card Id, Card Title and Card Subtitle will not be included in the onUserActivityOccurred() Storyteller delegate method.

"},{"location":"PrivacyAndTracking/#remote-viewing-store","title":"Remote viewing store","text":"

When enableRemoteViewingStore is disabled, user IDs are never stored or sent to backend services, and all user viewing activity is only kept locally on the device. This mode ensures the SDK operates in a privacy-enhanced mode designed to address VPPA (Video Privacy Protection Act) compliance concerns.

"},{"location":"PrivacyAndTracking/#independent-functional-behavior-toggles","title":"Independent Functional Behavior Toggles","text":"

The disabledFunctionalFeatures property allows to conditionally disable functional features of the SDK for privacy compliance. When a feature is disabled, the SDK will behave as if that functionality is disabled from the server.

"},{"location":"PrivacyAndTracking/#pagereadstatus","title":"pageReadStatus","text":"

Summary: Controls whether read/unread status is enabled for Story pages.

When disabled, the SDK will not store read/unread behavior for pages. All Lists and Players will act as if read/unread tracking is disabled from the server, meaning users will not see visual indicators of which Stories they have previously viewed.

"},{"location":"PrivacyAndTracking/#clipviewedstatus","title":"clipViewedStatus","text":"

Summary: Controls whether viewed/not viewed status is enabled for individual Clips.

When disabled, the SDK will not store viewed/not viewed information for Clips. All Lists and Players will act as if viewed/not viewed tracking is disabled from the server, removing visual indicators of previously watched content.

"},{"location":"PrivacyAndTracking/#pollvotes","title":"pollVotes","text":"

Summary: Controls whether Poll voting responses are persistently stored.

When disabled, users can still interact with Polls and see immediate UI updates when they vote, but their votes are not persistently stored. If they navigate away and return to the same Poll, they can vote again. Since this is coupled with disabled Storyteller Analytics, their votes will not contribute to overall Poll statistics.

"},{"location":"PrivacyAndTracking/#triviaquizanswers","title":"triviaQuizAnswers","text":"

Summary: Controls whether Trivia Quiz responses and progress are persistently stored.

When disabled, users can still answer trivia questions and see immediate UI feedback, but their answers are not persistently stored. If they navigate away and return to the same Quiz, they can answer questions again. The results page will be hidden since the SDK is not allowed to display persistent Quiz results.

"},{"location":"PrivacyAndTracking/#cliplikes","title":"clipLikes","text":"

Summary: Controls whether Clip like/unlike interactions are persistently stored.

When disabled, users can still tap to like/unlike Clips and see immediate UI updates, but these interactions are not persistently stored. If they swipe away and return to the same Clip, it will appear in its original unliked state.

"},{"location":"PrivacyAndTracking/#clipshares","title":"clipShares","text":"

Summary: Disables Clip Share tracking and storage (but not the sharing action itself).

When disabled, users can still tap on Share Clip button and see immediate UI updates, but this interaction is not persistently stored. If they swipe away and returns to the same Clip, the original share count will be displayed.

"},{"location":"PrivacyAndTracking/#all","title":"all","text":"

Summary: Disables all functional feature behaviors.

When disabled using .all, the SDK will behave as if every individual functional toggle is turned off.

"},{"location":"Quickstart/","title":"iOS Quickstart Guide","text":"

This guide takes a new native iOS integration from an empty screen to a visible row of published Storyteller Stories. Choose either the complete UIKit or SwiftUI path below, then use the Showcase app and component guides for more advanced integrations.

For Apple TV, use the dedicated tvOS Guide.

"},{"location":"Quickstart/#before-you-start","title":"Before You Start","text":"

You need:

Keep the API key, category identifier, and published content in the same tenant and environment. A valid key cannot load a category from another tenant.

"},{"location":"Quickstart/#install-the-sdk","title":"Install the SDK","text":""},{"location":"Quickstart/#swift-package-manager-recommended","title":"Swift Package Manager (Recommended)","text":"
  1. In Xcode, open File > Add Packages\u2026.
  2. Enter https://github.com/getstoryteller/storyteller-sdk-swift-package.
  3. Add the StorytellerSDK product to your app target.

The package resolves StorytellerLottie 4.6.0 transitively, so you do not need to add StorytellerLottie separately. If your app also uses upstream Airbnb Lottie, keep it as its own dependency; its Lottie module can coexist with Storyteller's namespaced StorytellerLottie module.

"},{"location":"Quickstart/#cocoapods","title":"CocoaPods","text":"

Add the Storyteller sources and SDK to your Podfile:

source 'https://github.com/getstoryteller/storyteller-sdk-ios-podspec.git'\nsource 'https://github.com/getstoryteller/storyteller-lottie-ios-podspec.git'\nsource 'https://cdn.cocoapods.org/'\n\nuse_frameworks!\n\ntarget 'MyAwesomeApp' do\n  pod 'StorytellerSDK'\nend\n

Both Storyteller source lines are required: the first contains the SDK podspec and the second contains its StorytellerLottie dependency. The CocoaPods CDN supplies public dependencies.

Then run pod install and open the generated .xcworkspace, not the .xcodeproj. CocoaPods installs StorytellerLottie transitively, so you do not need to add it separately. If your app also uses upstream Airbnb Lottie, keep it as its own dependency; it can coexist with StorytellerLottie.

"},{"location":"Quickstart/#xcframeworks","title":"XCFrameworks","text":"
  1. Download and unzip StorytellerSDK 11.6.0.
  2. Download and unzip StorytellerLottie 4.6.0.
  3. Add StorytellerSDK.xcframework and StorytellerLottie.xcframework to the same app target. StorytellerLottie is required by the SDK. If your app also uses upstream Airbnb Lottie, include it separately; it can coexist with StorytellerLottie, but it does not replace it.
  4. In the app target's General > Frameworks, Libraries, and Embedded Content section, select Embed & Sign for both XCFrameworks.
"},{"location":"Quickstart/#add-your-first-stories-row","title":"Add Your First Stories Row","text":"

Replace these placeholders before running either example:

Both examples deliberately finish Storyteller.shared.initialize(...) before configuring and loading the row. They also expose initialization, loading, empty, failure, and success states so a blank screen is not the only diagnostic signal.

"},{"location":"Quickstart/#uikit","title":"UIKit","text":"

Use this view controller directly or copy the same initialization, constraints, and delegate handling into your own screen.

import StorytellerSDK\nimport UIKit\n\n// MARK: - UIKitQuickstartViewController\n\nfinal class UIKitQuickstartViewController: UIViewController {\n    // MARK: Internal\n\n    override func viewDidLoad() {\n        super.viewDidLoad()\n\n        configureLayout()\n\n        Task { [weak self] in\n            await self?.loadStories()\n        }\n    }\n\n    // MARK: Private\n\n    private let statusLabel = UILabel()\n    private let storiesRow = StorytellerStoriesRowView()\n\n    private func configureLayout() {\n        view.backgroundColor = .systemBackground\n\n        statusLabel.numberOfLines = 0\n        statusLabel.text = \"Initializing Storyteller\u2026\"\n        statusLabel.translatesAutoresizingMaskIntoConstraints = false\n        storiesRow.translatesAutoresizingMaskIntoConstraints = false\n\n        view.addSubview(statusLabel)\n        view.addSubview(storiesRow)\n\n        NSLayoutConstraint.activate([\n            statusLabel.topAnchor.constraint(equalTo: view.safeAreaLayoutGuide.topAnchor, constant: 24),\n            statusLabel.leadingAnchor.constraint(equalTo: view.layoutMarginsGuide.leadingAnchor),\n            statusLabel.trailingAnchor.constraint(equalTo: view.layoutMarginsGuide.trailingAnchor),\n\n            storiesRow.topAnchor.constraint(equalTo: statusLabel.bottomAnchor, constant: 16),\n            storiesRow.leadingAnchor.constraint(equalTo: view.leadingAnchor),\n            storiesRow.trailingAnchor.constraint(equalTo: view.trailingAnchor),\n            storiesRow.heightAnchor.constraint(equalToConstant: 180),\n            storiesRow.bottomAnchor.constraint(lessThanOrEqualTo: view.safeAreaLayoutGuide.bottomAnchor),\n        ])\n    }\n\n    private func loadStories() async {\n        do {\n            try await Storyteller.shared.initialize(\n                apiKey: \"<API_KEY>\",\n                userInput: StorytellerUserInput(externalId: \"<USER_ID>\")\n            )\n\n            storiesRow.delegate = self\n            storiesRow.configure(\n                with: StorytellerStoriesListConfiguration(\n                    categories: [\"<CATEGORY_ID>\"]\n                )\n            )\n            storiesRow.reloadData()\n        } catch {\n            statusLabel.isHidden = false\n            statusLabel.text = \"Storyteller could not initialize: \\(error.localizedDescription)\"\n        }\n    }\n}\n\n// MARK: StorytellerListViewDelegate\n\nextension UIKitQuickstartViewController: StorytellerListViewDelegate {\n    nonisolated func onDataLoadStarted() {\n        Task { @MainActor [weak self] in\n            self?.statusLabel.isHidden = false\n            self?.statusLabel.text = \"Loading Stories\u2026\"\n        }\n    }\n\n    nonisolated func onDataLoadComplete(success: Bool, error: Error?, dataCount: Int) {\n        let statusText: String?\n        if let error {\n            statusText = \"Stories could not load: \\(error.localizedDescription)\"\n        } else if !success {\n            statusText = \"Stories could not load. Check the Xcode console for details.\"\n        } else if dataCount == 0 {\n            statusText = \"No published Stories were found for this category.\"\n        } else {\n            statusText = nil\n        }\n\n        Task { @MainActor [weak self] in\n            self?.statusLabel.isHidden = statusText == nil\n            self?.statusLabel.text = statusText\n        }\n    }\n}\n

The explicit leading, trailing, top, and height constraints are required. Adding a StorytellerStoriesRowView to a hierarchy without giving it a non-zero layout can load data successfully while displaying nothing.

"},{"location":"Quickstart/#swiftui","title":"SwiftUI","text":"

Place SwiftUIQuickstartView anywhere in your SwiftUI hierarchy. The model is created only after initialization succeeds; inserting the row then triggers its initial load.

import StorytellerSDK\nimport SwiftUI\n\nstruct SwiftUIQuickstartView: View {\n    // MARK: Internal\n\n    var body: some View {\n        VStack(alignment: .leading, spacing: 16) {\n            statusView\n\n            if let storiesModel {\n                StorytellerStoriesRow(model: storiesModel) { action in\n                    Task { @MainActor in\n                        handle(action)\n                    }\n                }\n                .frame(height: 180)\n            }\n        }\n        .padding(.vertical, 24)\n        .onAppear {\n            Task { @MainActor in\n                await loadStories()\n            }\n        }\n    }\n\n    // MARK: Private\n\n    private enum LoadState {\n        case initializing\n        case loading\n        case empty\n        case ready\n        case failed(String)\n    }\n\n    @State private var hasStarted = false\n    @State private var loadState = LoadState.initializing\n    @State private var storiesModel: StorytellerStoriesListModel?\n\n    @ViewBuilder\n    private var statusView: some View {\n        switch loadState {\n        case .initializing:\n            Text(\"Initializing Storyteller\u2026\")\n        case .loading:\n            Text(\"Loading Stories\u2026\")\n        case .empty:\n            Text(\"No published Stories were found for this category.\")\n        case .ready:\n            EmptyView()\n        case .failed(let message):\n            Text(message)\n        }\n    }\n\n    @MainActor\n    private func loadStories() async {\n        guard !hasStarted else { return }\n        hasStarted = true\n\n        do {\n            try await Storyteller.shared.initialize(\n                apiKey: \"<API_KEY>\",\n                userInput: StorytellerUserInput(externalId: \"<USER_ID>\")\n            )\n\n            loadState = .loading\n            storiesModel = StorytellerStoriesListModel(\n                configuration: StorytellerStoriesListConfiguration(\n                    categories: [\"<CATEGORY_ID>\"]\n                )\n            )\n        } catch {\n            loadState = .failed(\n                \"Storyteller could not initialize: \\(error.localizedDescription)\"\n            )\n        }\n    }\n\n    @MainActor\n    private func handle(_ action: StorytellerListAction) {\n        switch action {\n        case .onDataLoadStarted:\n            loadState = .loading\n        case let .onDataLoadComplete(success, error, dataCount):\n            if let error {\n                loadState = .failed(\n                    \"Stories could not load: \\(error.localizedDescription)\"\n                )\n            } else if !success {\n                loadState = .failed(\n                    \"Stories could not load. Check the Xcode console for details.\"\n                )\n            } else if dataCount == 0 {\n                loadState = .empty\n            } else {\n                loadState = .ready\n            }\n        default:\n            break\n        }\n    }\n}\n

Keep the explicit .frame(height: 180) or give the row an equivalent non-zero height within your own layout.

"},{"location":"Quickstart/#initialization-order","title":"Initialization Order","text":"

Storyteller.shared.initialize(...) is async throws. Its isInitialized value becomes true only after initialization succeeds and is reset to false whenever initialization starts again. Across Storyteller's public methods, the stable StorytellerError cases are networkError(Error), contentNotFound(String), and wrongInputData. Initialization may also surface an underlying transport or response-decoding error, so keep a general catch path.

The SDK currently defers a list reload requested before initialization. If an initialization attempt fails, the reload remains pending and can resume after a later successful attempt, provided the list identifier has not changed. This is a safeguard, not the recommended integration sequence. Await initialization explicitly as shown above.

"},{"location":"Quickstart/#confirm-success","title":"Confirm Success","text":"

A successful load calls onDataLoadComplete with success == true, no error, and dataCount > 0. The status text disappears and a horizontal row of Story tiles appears. Tapping a tile opens the Story Player unless your theme disables Player opening.

The tile artwork and shape depend on your tenant content and theme, but the populated row will look similar to the Story tiles in this visual:

"},{"location":"Quickstart/#diagnose-a-blank-or-failed-result","title":"Diagnose a Blank or Failed Result","text":"Observable result What it establishes What to check Storyteller could not initialize The content request did not start. Confirm the API key, tenant/environment, connectivity, and the underlying error in Xcode. Stories could not load Initialization succeeded, but the content request failed. Inspect the returned error and Xcode logs; verify network access and tenant configuration. No published Stories were found The request succeeded with dataCount == 0. Confirm <CATEGORY_ID>, category assignment, publication status, schedule/expiry, and any targeting rules for <USER_ID>. success == true and dataCount > 0, but no tiles are visible Content loaded and the problem is presentation. Confirm that the UIKit row has non-zero constraints or that the SwiftUI row has a non-zero frame. The screen remains in a loading state A request has not completed. Confirm initialization is awaited, keep the delegate/action callback alive, inspect Xcode logs, and check connectivity."},{"location":"Quickstart/#go-further","title":"Go Further","text":"

The Quickstart intentionally stops after the first reliable row. Continue with:

"},{"location":"Search/","title":"Search","text":"

The Search component allows users to search for Storyteller Clips and Stories. As users type, a list of suggestions will appear, from which users can either select a suggestion or search using their entered term. Results are categorized into two sections: Stories and Clips, based on their type. Filters allow users to narrow down their search results, enabling them to find specific content that meets their criteria more efficiently. For instance, users can apply filters such as date posted, content type or they can sort it by certain criteria.

"},{"location":"Search/#search-filters","title":"Search Filters","text":"

Date Posted possible values:

Content Type possible values:

Sort By values:

"},{"location":"Search/#how-to-use","title":"How to Use","text":"

The Search feature must first be enabled by the Storyteller team for your specific tenant. Once enabled, the Search functionality will be available within the Story and Clip players.

Additional Search functionality is available through the Storyteller class:

openSearch() is asynchronous and non-throwing. When Search is disabled, it returns without presenting anything, so check isSearchEnabled first if your app needs to show a disabled state or diagnostic:

import StorytellerSDK\n\nfunc searchButtonTapped() {\n    Task { @MainActor in\n        guard Storyteller.shared.isSearchEnabled else {\n            print(\"Storyteller Search is not enabled for this tenant\")\n            return\n        }\n\n        await Storyteller.shared.openSearch()\n    }\n}\n

The Showcase app triggers openSearch from the home header button - see HomeView.headerView.

"},{"location":"Search/#customization","title":"Customization","text":"

The Search background, input, filter button, suggestions, no-results state and filter sheet can be customized independently for light and dark themes. All appearance properties are optional and retain the existing UI when omitted. For the full property contract and inheritance rules, see Search themes.

"},{"location":"StorytellerDelegate/","title":"Implementing Storyteller Delegate Callbacks","text":"

Storyteller has a framework-independent global delegate and framework-specific component callback routes:

What you need to observe UIKit SwiftUI Player lifecycle, analytics, Ads, sharing, logging, or in-app navigation StorytellerDelegate assigned to Storyteller.shared.delegate The same StorytellerDelegate Story or Clip row/grid loading, taps, or Player dismissal StorytellerListViewDelegate assigned to the UIKit view StorytellerListActionCallback passed to the SwiftUI wrapper Embedded Clips loading or top-level back navigation StorytellerClipsViewControllerDelegate StorytellerClipsView action closure; see Embedded Clips

StorytellerDelegate is the global route for events and integration hooks associated with Story and Clip Players. It inherits from StorytellerModule, described in StorytellerModule. Component callbacks are separate and do not replace the global delegate.

For a full implementation, see the Showcase delegate in StorytellerInstanceDelegate and the analytics forwarding in StorytellerTrackingDelegate.

If an expected callback does not arrive, use the shared callback and analytics troubleshooting route to distinguish load callbacks, interaction callbacks, and analytics gates.

"},{"location":"StorytellerDelegate/#storytellerdelegate","title":"StorytellerDelegate","text":"

This protocol applies to both UIKit and SwiftUI apps. Assign one app-owned instance to Storyteller.shared.delegate and retain it strongly because the SDK property is weak. Implement only the optional callbacks your integration needs.

"},{"location":"StorytellerDelegate/#onuseractivityoccurred","title":"onUserActivityOccurred","text":"

The onUserActivityOccurred(type: StorytellerUserActivity.EventType, data: StorytellerUserActivityData) method is called when an analytics event is triggered within the SDK. This allows the integrating app to observe and potentially forward these events to their own analytics systems. Follow Integrate Analytics for setup and verification, then use the Analytics Event Reference for event types and data.

"},{"location":"StorytellerDelegate/#getad","title":"getAd","text":"

The getAd(for adRequestInfo: StorytellerAdRequestInfo) async throws -> StorytellerAd method is called when the tenant is configured in the CMS to request full-screen ads from the integrating app. The app should fetch ad data asynchronously and return it directly to the SDK, or throw an error if no ad is available. See the Ads page for more details.

"},{"location":"StorytellerDelegate/#getbottombannerad","title":"getBottomBannerAd","text":"

getBottomBannerAd(for adRequestInfo: StorytellerAdRequestInfo, maxHeight: CGFloat) async throws -> StorytellerAd method is similar to getAd, but is called when the tenant is configured in the CMS to request bottom banner ads (displayed at the bottom of clips) from the integrating app. The maxHeight parameter indicates the maximum allowed height for the banner based on the current layout constraints. See the Ads page for more details.

"},{"location":"StorytellerDelegate/#usernavigatedtoapp","title":"userNavigatedToApp","text":"

The userNavigatedToApp(url: String) method is called when a user presses an action button on a page which should direct the user to a specific place within the integrating app. More information on In App links Navigating to App. For more information on deep linking, see the dedicated Deep linking page.

"},{"location":"StorytellerDelegate/#onsharebuttontapped","title":"onShareButtonTapped","text":"

The onShareButtonTapped(text: String, title: String, url: String) method is called when Storyteller.shared.useCustomShareHandling is set to true and a user taps the Share button in a Story or Clip. The SDK pauses the current Story or Clip, skips presenting the iOS share sheet, and forwards the same payload it would normally share so your app can present its own share flow.

When Storyteller.shared.useCustomShareHandling remains false (the default), the SDK continues to present the native iOS share sheet and this callback is not invoked.

When your custom share UI is dismissed, call Storyteller.shared.resumePlayer() to resume Storyteller playback.

"},{"location":"StorytellerDelegate/#configurewebview","title":"configureWebView","text":"

This method allows you to configure the WebView with custom settings or actions when the Storyteller SDK is about to display a WebView. This method is called before displaying WebView on the screen.

It receives a configuration object which is a collection of properties that you use to initialize a web view.

Note: configureWebView is available only on iOS.

"},{"location":"StorytellerDelegate/#categoryfollowactiontaken","title":"categoryFollowActionTaken","text":"

The method categoryFollowActionTaken(category: StorytellerCategory, isFollowing: Bool) is invoked when a user follows or unfollows a category of clips (the category can represent a player, a team etc.) from within the SDK's UI.

The callback reports the affected category and whether it is now followed:

Note: This method is only called when your tenant is setup in App-Managed Following mode.

"},{"location":"StorytellerDelegate/#log","title":"log","text":"

The log(message:) method receives Storyteller SDK error and informational log messages. Implement it on the app-owned object assigned to Storyteller.shared.delegate when you need to capture diagnostics in debug or release builds. The SDK holds the delegate weakly, so keep that object strongly retained. Failed-request messages can include full request URLs containing a hashed user ID when enableRemoteViewingStore is enabled, even when personalization is disabled; they can also include custom-attribute values when personalization is enabled. Redact those values before forwarding logs to a third-party service or sharing them. Storyteller API keys can remain intact when sharing logs directly with Storyteller support.

"},{"location":"StorytellerDelegate/#onplayerpresented","title":"onPlayerPresented","text":"

The method onPlayerPresented() is invoked when a story or clip player is presented on screen. This can be useful for pausing background audio, videos or animations in your app while the player is visible.

"},{"location":"StorytellerDelegate/#onplayerdismissed","title":"onPlayerDismissed","text":"

The method onPlayerDismissed() is invoked when a story or clip player is dismissed from screen. This can be useful for resuming background audio, videos or animations in your app that were paused when the player was presented.

"},{"location":"StorytellerDelegate/#viewcontrollerfor-storytellercategory","title":"viewController(for: StorytellerCategory)","text":"

The method viewController(for category: StorytellerCategory) -> UIViewController? is invoked when the user taps on the category icon inside a clip or interactively swipes to the left. You can provide a custom view controller to push to. This method is optional, and if an implementation is not provided, the SDK will push a UIViewController with a Story Row and Clip Grid based on the Category.

This delegate method receives the following parameter:

"},{"location":"StorytellerDelegate/#minimal-storytellerdelegate-implementation","title":"Minimal StorytellerDelegate implementation","text":"

Every StorytellerDelegate method has a default implementation, including the Ad methods inherited from StorytellerModule. Implement only the callbacks your app needs. This minimal analytics delegate is valid without placeholder return values:

import StorytellerSDK\n\nfinal class AnalyticsDelegate: StorytellerDelegate {\n    func onUserActivityOccurred(\n        type: StorytellerUserActivity.EventType,\n        data: StorytellerUserActivityData\n    ) {\n        print(\"Storyteller event: \\(type), context: \\(data.context ?? [:])\")\n    }\n}\n\nfinal class StorytellerIntegration {\n    private let delegate = AnalyticsDelegate()\n\n    func configure() {\n        Storyteller.shared.delegate = delegate\n    }\n}\n

Keep the delegate strongly referenced, as shown by StorytellerIntegration; Storyteller.shared.delegate is weak. Implement getAd or getBottomBannerAd only when your tenant requests host-supplied Ads, and return a real StorytellerAd or throw an error as described in Ads.

WebKit types are not re-exported by StorytellerSDK. A delegate that customizes Storyteller WebViews must import WebKit explicitly:

import StorytellerSDK\nimport WebKit\n\nfinal class WebViewDelegate: StorytellerDelegate {\n    func configureWebView(configuration: inout WKWebViewConfiguration) {\n        MainActor.assumeIsolated {\n            let script = WKUserScript(\n                source: \"document.body.style.backgroundColor = 'red';\",\n                injectionTime: .atDocumentEnd,\n                forMainFrameOnly: true\n            )\n            configuration.userContentController.addUserScript(script)\n        }\n    }\n}\n

Storyteller invokes configureWebView while constructing UI on the main actor. The released protocol requirement predates WebKit's strict-concurrency annotations, so MainActor.assumeIsolated keeps host code warning-free on newer toolchains while preserving compatibility with the released SDK.

"},{"location":"StorytellerDelegate/#storytellerlistviewdelegate","title":"StorytellerListViewDelegate","text":"

StorytellerListViewDelegate is the UIKit callback interface for StorytellerRowView and StorytellerGridView subclasses. SwiftUI list wrappers report the same event values through StorytellerListActionCallback; choose the corresponding wiring example below.

"},{"location":"StorytellerDelegate/#ondataloadstarted","title":"onDataLoadStarted","text":"

UIKit calls onDataLoadStarted() and SwiftUI emits .onDataLoadStarted when a list request begins.

"},{"location":"StorytellerDelegate/#ondataloadcomplete","title":"onDataLoadComplete","text":"

UIKit calls onDataLoadComplete(success:error:dataCount:) and SwiftUI emits .onDataLoadComplete(success:error:dataCount:) when the request finishes.

Property Description success This confirms whether or not the request was successful error The HTTP error if the request was not successful dataCount The number of Stories loaded"},{"location":"StorytellerDelegate/#ontiletapped","title":"onTileTapped","text":"

UIKit calls onTileTapped(type:) and SwiftUI emits .onTileTapped(type:) when a user taps a tile inside a row or grid. This happens before the Player is opened.

Property Description type A StorytellerTileType enum that contains tile information. Can be either .story(storyId: String, categories: [StorytellerCategoryDetail]) or .clip(clipId: String, collectionId: String, categories: [StorytellerCategoryDetail])

Note: When theme.lists.enablePlayerOpen is set to false, the SDK will not automatically open the player and you should handle your custom tile interaction logic via this callback. For lists in SDK\u2011owned screens (Storyteller Home, Followable Categories, and Search), the SDK always opens the player when a tile is tapped, regardless of theme.lists.enablePlayerOpen.

Example:

// Assuming `theme.lists.enablePlayerOpen` is set to `false`\nfunc onTileTapped(type: StorytellerTileType) {\n    switch type {\n    case .story(let storyId, let categories):\n        let categoryIds = categories.map(\\.id)\n        // Handle story tile tap\n    case .clip(let clipId, let collectionId, let categories):\n        let categoryIds = categories.map(\\.id)\n        // Handle clip tile tap\n    @unknown default:\n        break\n    }\n}\n
"},{"location":"StorytellerDelegate/#onplayerdismissed_1","title":"onPlayerDismissed","text":"

UIKit calls onPlayerDismissed() and SwiftUI emits .onPlayerDismissed when a Player opened from the list is dismissed.

"},{"location":"StorytellerDelegate/#error-handling","title":"Error Handling","text":"

By using the callback function onDataLoadComplete and the data it provides, you can handle the current state of the StorytellerRowView appropriately in your app.

Note: dataCount is the total number of Stories in the existing StorytellerRowView at any given time

Example:

func onDataLoadComplete(success: Bool, error: Error?, dataCount: Int) {\n    if success {\n        // stories data has been loaded successfully\n        // dataCount is the current total number of content, including newly added/removed data\n    } else if let newError = error {\n        // an error has occurred, use the unwrapped value `newError`\n    }\n}\n

Another example:

let storytellerRowView = StorytellerStoriesRowView()\n\nfunc onDataLoadComplete(success: Bool, error: Error?, dataCount: Int) {\n    if let _ = error, dataCount == 0 {\n        // content have failed to load with error and there is no data to show\n        // you may wish to hide the `StorytellerRowView` instance here\n        storytellerRowView.isHidden = true\n        // Example: storytellerRowViewHeightConstraint.constant = 0\n    }\n}\n
"},{"location":"StorytellerDelegate/#wire-list-callbacks","title":"Wire List Callbacks","text":"

Choose the callback route for your framework:

UIKitSwiftUI

Pass an action closure to the SwiftUI list wrapper and switch over StorytellerListAction:

import StorytellerSDK\nimport SwiftUI\n\n@available(iOS 14.0, *)\nstruct StoriesRowWithActions: View {\n    @State private var model = StorytellerStoriesListModel(\n        configuration: StorytellerStoriesListConfiguration(categories: [\"sports\"])\n    )\n\n    var body: some View {\n        StorytellerStoriesRow(model: model) { action in\n            switch action {\n            case .onDataLoadStarted:\n                print(\"Storyteller list started loading\")\n            case .onDataLoadComplete(let success, let error, let dataCount):\n                print(\"Loaded \\(dataCount) items; success: \\(success); error: \\(error?.localizedDescription ?? \"none\")\")\n            case .onTileTapped(let type):\n                print(\"Tapped Storyteller tile: \\(type)\")\n            case .onPlayerDismissed:\n                print(\"Storyteller Player dismissed\")\n            @unknown default:\n                break\n            }\n        }\n    }\n}\n

The wrapper owns the internal UIKit delegate bridge. Your SwiftUI code should consume the action closure rather than constructing a StorytellerListViewDelegate.

See Storyteller List Views for complete list configuration and reload examples.

"},{"location":"StorytellerDelegate/#example-implementation-of-storytellerlistviewdelegate","title":"Example implementation of StorytellerListViewDelegate","text":"

Implement StorytellerListViewDelegate:

class DelegateObject : StorytellerListViewDelegate {\n\n    func onDataLoadStarted() {\n        // Action on start of data network requests\n    }\n\n    func onDataLoadComplete(success: Bool, error: Error?, dataCount: Int) {\n        // Action on completion of data network requests\n    }\n\n    func onTileTapped(type: StorytellerTileType) {\n        // Action when a tile is tapped\n    }\n\n    func onPlayerDismissed() {\n        // Action on dismissal of player\n    }\n}\n

Retain the delegate strongly, assign it to the UIKit view, and then load the content:

import StorytellerSDK\nimport UIKit\n\nfinal class StoriesListViewController: UIViewController {\n    private let storytellerStoriesRow = StorytellerStoriesRowView()\n    private let delegate = DelegateObject()\n\n    override func viewDidLoad() {\n        super.viewDidLoad()\n\n        storytellerStoriesRow.delegate = delegate\n        storytellerStoriesRow.reloadData()\n    }\n\n    private final class DelegateObject: StorytellerListViewDelegate {}\n}\n

Assign the delegate before reloadData() or the delegate will not receive the initial loading callbacks.

"},{"location":"StorytellerHome/","title":"Storyteller Home","text":"

StorytellerHome is a component that allows multiple Stories and Clips Rows or Grids to be embedded in a single screen in your application in a list.

"},{"location":"StorytellerHome/#how-to-use","title":"How to Use","text":"

Create one shared configuration, then choose either the SwiftUI or UIKit implementation below. Both routes display the same CMS-configured Home content and support manual refresh through reloadData; pull-to-refresh is available in the SwiftUI component from iOS 15.

"},{"location":"StorytellerHome/#step-1-create-a-configuration-object","title":"Step 1: Create a configuration object","text":"

Begin by constructing a StorytellerHomeConfiguration. Pass this configuration to the model or view for the framework you use. It has the following properties:

let theme = StorytellerTheme()\n// Customize the theme\nlet config = StorytellerHomeConfiguration(\n    homeId: \"YOUR_HOME_ID\",\n    theme: theme,\n    uiStyle: .auto,\n    context: [\n      \"source\": \"main-tab\",\n      \"user_segment\": \"premium\",\n      \"variant\": \"personalized\"\n  ]\n)\n
"},{"location":"StorytellerHome/#choose-your-ui-framework","title":"Choose Your UI Framework","text":"

The framework routes are alternatives; follow only the tab that matches your app.

UIKitSwiftUI"},{"location":"StorytellerHome/#step-3-using-uikit","title":"Using UIKit","text":"

Create a StorytellerHomeView from the shared configuration and add it to a view hierarchy with non-zero constraints.

For a UIKit sample that renders multiple Storyteller lists in a table view, see the CocoaPods Showcase implementation in MultipleListsViewController.

class MyViewController: UIViewController {\n  override func viewDidLoad() {\n    super.viewDidLoad()\n\n    let config = StorytellerHomeConfiguration(homeId: \"YOUR_HOME_ID\")\n    let storytellerHomeView = StorytellerHomeView(configuration: config)\n    storytellerHomeView.translatesAutoresizingMaskIntoConstraints = false\n    view.addSubview(storytellerHomeView)\n\n    // Set up constraints\n    NSLayoutConstraint.activate([\n        storytellerHomeView.topAnchor.constraint(equalTo: view.topAnchor),\n        storytellerHomeView.bottomAnchor.constraint(equalTo: view.bottomAnchor),\n        storytellerHomeView.leadingAnchor.constraint(equalTo: view.leadingAnchor),\n        storytellerHomeView.trailingAnchor.constraint(equalTo: view.trailingAnchor)\n    ])\n  }\n}\n
"},{"location":"StorytellerHome/#step-2-using-swiftui","title":"Using SwiftUI","text":"

Create a StorytellerHomeModel from the shared configuration and retain it as view state. The StorytellerHome view includes built-in pull-to-refresh support from iOS 15.

@available(iOS 14.0, *)\nstruct ContentView: View {\n  // Initialize model with configuration\n  @StateObject private var model = StorytellerHomeModel(\n    configuration: StorytellerHomeConfiguration(homeId: \"YOUR_HOME_ID\")\n  )\n\n  var body: some View {\n    StorytellerHome(model: model)\n  }\n}\n
"},{"location":"StorytellerHome/#continue-your-integration","title":"Continue Your Integration","text":""},{"location":"StorytellerListViews/","title":"The Storyteller List Views","text":"

Use Storyteller List Views to embed a row or grid of Stories or Clips in your own UIKit or SwiftUI screen. If you have not displayed Storyteller content before, complete the iOS Quickstart Guide first.

Choose the content, layout, and framework independently:

Content and layout UIKit SwiftUI Stories row StorytellerStoriesRowView StorytellerStoriesRow with StorytellerStoriesListModel Stories grid StorytellerStoriesGridView StorytellerStoriesGrid with StorytellerStoriesListModel Clips row StorytellerClipsRowView StorytellerClipsRow with StorytellerClipsListModel Clips grid StorytellerClipsGridView StorytellerClipsGrid with StorytellerClipsListModel

The StorytellerStoriesListConfiguration and StorytellerClipsListConfiguration values are shared by both frameworks. UIKit views report loading and interaction through StorytellerListViewDelegate; SwiftUI wrappers expose the equivalent events through StorytellerListActionCallback.

"},{"location":"StorytellerListViews/#uikit-list-types","title":"UIKit List Types","text":"

The four final UIKit List views have the following class hierarchy (root class is at the top):

 StorytellerListView\n \u251c\u2500\u2500 StorytellerRowView\n \u2502   \u251c\u2500\u2500 StorytellerStoriesRowView\n \u2502   \u2514\u2500\u2500 StorytellerClipsRowView\n \u2514\u2500\u2500 StorytellerGridView\n     \u251c\u2500\u2500 StorytellerStoriesGridView\n     \u2514\u2500\u2500 StorytellerClipsGridView\n

Choose the one you need depending on content and UI behavior. Use a Stories or Clips list, then choose between these layouts:

Rows are horizontal scrolling lists, that you create by simply calling:

let storiesRow = StorytellerStoriesRowView()\n

or

let clipsRow = StorytellerClipsRowView()\n

For a UIKit table view integration (including configuration and delegate wiring), see the CocoaPods sample in StorytellerStoriesRowTableViewCell.

When using rows, you can either provide explicit height constraints or let the SDK manage the height automatically. When no explicit height constraint is set, the SDK will automatically calculate and adjust the row height, including adjustments for iOS Dynamic Type settings to improve accessibility.

Grids are vertical lists, organized into columns (number of columns can be set on the Theme), and can be scrollable or not. They can be constructed like so:

let storiesGrid = StorytellerStoriesGridView(isScrollable: true) // scrollable\nlet clipsGrid = StorytellerClipsGridView(isScrollable: false) // non-scrollable\n

For a full SwiftUI Showcase Home feed that composes rows, grids, and Cards, see how the Showcase app assembles the feed in HomeView, renders items in StorytellerItemView, and uses list wrappers in StoriesListView.

"},{"location":"StorytellerListViews/#scrollable-vs-non-scrollable-grids","title":"Scrollable vs non-scrollable Grids","text":"

The choice between scrollable and non-scrollable grids applies to both frameworks. In UIKit, non-scrollable grids can be used inside a vertical feed where you might also have rows or other UI elements in the same view. Constrain just the width of the grid and leave its height to be calculated automatically by Auto Layout. Auto-resize can happen whenever the delegate callback onDataLoadComplete is triggered (see more list events).

Note - if you use a non-scrollable grid with many items (hundreds) your app might hang when it loads due to the fact that it is not optimized to handle a huge amount of items. For that you would either set a displayLimit or use a scrollable Grid. When no limit is provided, non-scrollable grids default to rendering at most 30 items.

Scrollable grids on the other hand support recycling and can be used with a large number of items. It has scrolling and even pull-to-refresh builtin. It is recommended to build a \"More\" screen for example, where the grid is the main view on the screen. You need to constrain both its width and height when integrating it in a view hierarchy.

"},{"location":"StorytellerListViews/#interface-builder-support","title":"Interface Builder support","text":"

This section applies only to UIKit. UIKit List views support being created in XIBs and storyboards. Type one of the four custom final classes in the Class field in the Identity Inspector of the desired view.

Remember grids default to non-scrolling. We added an IBInspectable property so that you can enable scrolling, but it seems Xcode doesn't detect it when using a custom view class from a 3rd party framework. The workaround is to select the grid, open the Identity Inspector, and under User Defined Runtime Attributes add a key path with the value isScrollable of type Boolean and ensure the checkbox next to it is selected.

For examples on how to construct the lists in various ways, refer to the Showcase implementations of rows/grids in StoriesListView and list callbacks in StorytellerItemView.listAction.

"},{"location":"StorytellerListViews/#further-configuration","title":"Further configuration","text":"

The configuration values in this section are shared by UIKit and SwiftUI. UIKit views receive a configuration through configure(with:); SwiftUI wrappers receive a model initialized with the same configuration type.

UIKit views expose a weak delegate property for list events. Keep that delegate strongly referenced in your app. SwiftUI wrappers instead receive a StorytellerListActionCallback through their action parameter.

For stories you pass in a StorytellerStoriesListConfiguration, containing this specific Stories parameter:

For clips you pass in a StorytellerClipsListConfiguration, containing this specific Clips parameter:

StorytellerClipsListConfiguration configures Clip tiles in a row or grid. It is different from StorytellerClipCollectionConfiguration, which configures an embedded or programmatically presented Clip Player, including its destination and Ad placements. See Embedded Clips for the Player configuration.

The next parameters are common for both the configuration objects:

After configuring a UIKit view, call reloadData() to perform its initial fetch. Call it again after changing the configuration or whenever you need to refresh its content. SwiftUI wrappers perform their initial load from the supplied model; call reloadData() on the model when you need a later refresh without changing its configuration.

"},{"location":"StorytellerListViews/#configure-example","title":"Configure Example","text":"UIKitSwiftUI

Create a UIKit view, configure it, then call reloadData() to perform the initial fetch. Call it again whenever you need to refresh the content. Assign a strongly retained StorytellerListViewDelegate before loading when you need lifecycle or interaction callbacks.

import StorytellerSDK\n\nlet storytellerStoriesRow = StorytellerStoriesRowView()\nlet storytellerClipsRow = StorytellerClipsRowView()\n\n// Stories configuration with context\nstorytellerStoriesRow.configure(with: StorytellerStoriesListConfiguration(\n    categories: [\"sports\", \"entertainment\"],\n    context: [\n        \"source\": \"home-screen-stories\",\n        \"campaign\": \"summer-league\"\n    ]\n))\nstorytellerStoriesRow.reloadData()\n\n// Clips configuration with context\nstorytellerClipsRow.configure(with: StorytellerClipsListConfiguration(\n    collectionId: \"trending-clips\",\n    context: [\n        \"source\": \"home-screen-clips\",\n        \"campaign\": \"summer-league\"\n    ]\n))\nstorytellerClipsRow.reloadData()\n

Construct models from the shared configuration types, retain them as view state, and supply a StorytellerListActionCallback to each wrapper. For a real-world setup, see the Showcase wrappers in StoriesListView.

import StorytellerSDK\nimport SwiftUI\n\n@available(iOS 15.0, *)\nstruct StorytellerListsView: View {\n    @State private var storiesModel = StorytellerStoriesListModel(\n        configuration: StorytellerStoriesListConfiguration(\n            categories: [\"sports\"],\n            context: [\"location\": \"stories-grid\"]\n        )\n    )\n    @State private var clipsModel = StorytellerClipsListModel(\n        configuration: StorytellerClipsListConfiguration(\n            collectionId: \"top-plays\",\n            context: [\"location\": \"clips-grid\"]\n        )\n    )\n\n    private let handleListAction: StorytellerListActionCallback = { action in\n        switch action {\n        case .onDataLoadStarted:\n            print(\"Storyteller list started loading\")\n        case .onDataLoadComplete(let success, let error, let dataCount):\n            print(\"Loaded \\(dataCount) items; success: \\(success); error: \\(error?.localizedDescription ?? \"none\")\")\n        case .onTileTapped(let type):\n            print(\"Tapped Storyteller tile: \\(type)\")\n        case .onPlayerDismissed:\n            print(\"Storyteller Player dismissed\")\n        @unknown default:\n            break\n        }\n    }\n\n    var body: some View {\n        VStack {\n            StorytellerStoriesGrid(\n                isScrollable: true,\n                model: storiesModel,\n                action: handleListAction\n            )\n            .frame(height: 300)\n\n            StorytellerClipsGrid(\n                isScrollable: true,\n                model: clipsModel,\n                action: handleListAction\n            )\n            .frame(height: 300)\n        }\n        .refreshable {\n            storiesModel.reloadData()\n            clipsModel.reloadData()\n        }\n    }\n}\n

Use the same models with StorytellerStoriesRow or StorytellerClipsRow when you need horizontal rows. SwiftUI reloads a component when its model changes; call the model's reloadData() method to reload without changing its configuration.

"},{"location":"StorytellerListViews/#continue-your-integration","title":"Continue Your Integration","text":""},{"location":"StorytellerModule/","title":"StorytellerModule","text":"

The StorytellerModule module is a protocol you can adopt to handle fetching ads and recording user activity events from Storyteller.

"},{"location":"StorytellerModule/#properties","title":"Properties","text":""},{"location":"StorytellerModule/#adsource","title":"adSource","text":"

adSource: StorytellerAdSource? identifies the ad source for ads provided by your module.

This value is attached to ad analytics payloads when available.

If not implemented, the default value is nil.

The SDK-provided StorytellerGAMModule, StorytellerAdMobModule, and StorytellerVASTModule set this value automatically.

See how the Showcase app registers modules in AppDelegate.setupStoryteller.

"},{"location":"StorytellerModule/#methods","title":"Methods","text":""},{"location":"StorytellerModule/#analytics","title":"Analytics","text":"

The callback onUserActivityOccurred provides analytics events and corresponding data triggered internally by the SDK. This information can be used in your app.

The following parameters are passed to the callback method:

Example:

func onUserActivityOccurred(type: StorytellerUserActivity.EventType, data: StorytellerUserActivityData) {\n    if type == .OpenedStory {\n        // Retrieve the story id value\n        let openedStoryId = data.storyId\n        // Retrieve the story title value\n        let openedStoryTitle = data.storyTitle\n\n        // Report retrieved values from your app\n    }\n}\n

For a detailed discussion of all the relevant events and properties please see the dedicated Analytics page.

"},{"location":"StorytellerModule/#ads","title":"Ads","text":"

By implementing getAd and getBottomBannerAd, you can provide custom ad data for the SDK to render. This is only applicable when the ad configuration is set to Integrating App in the CMS. Ad data can be obtained asynchronously using async/await, and should be returned directly or throw an error if no ad is available.

When building ad CTAs, StorytellerAdAction supports StorytellerActionType.web, StorytellerActionType.inApp, StorytellerActionType.externalApp, and StorytellerActionType.store.

"},{"location":"StorytellerModule/#getad","title":"getAd","text":"

The getAd method is called when the SDK needs a fullscreen ad:

final class CustomAdsModule: StorytellerModule {\n    enum AdLoadingError: Error {\n        case unavailable\n    }\n\n    let loadAd: () async -> StorytellerAd?\n\n    init(loadAd: @escaping () async -> StorytellerAd?) {\n        self.loadAd = loadAd\n    }\n\n    func getAd(for adRequestInfo: StorytellerAdRequestInfo) async throws -> StorytellerAd {\n        guard let ad = await loadAd() else {\n            throw AdLoadingError.unavailable\n        }\n        return ad\n    }\n}\n
"},{"location":"StorytellerModule/#bottom-banner-ads","title":"Bottom Banner Ads","text":"

The getBottomBannerAd method is called when the SDK needs a bottom banner ad (displayed at the bottom of clips). The maxHeight parameter indicates the maximum allowed banner height for the current layout:

final class CustomBannerAdsModule: StorytellerModule {\n    enum AdLoadingError: Error {\n        case unavailable\n    }\n\n    let loadBannerAd: (CGFloat) async -> StorytellerAd?\n\n    init(loadBannerAd: @escaping (CGFloat) async -> StorytellerAd?) {\n        self.loadBannerAd = loadBannerAd\n    }\n\n    func getBottomBannerAd(for adRequestInfo: StorytellerAdRequestInfo, maxHeight: CGFloat) async throws -> StorytellerAd {\n        guard let ad = await loadBannerAd(maxHeight) else {\n            throw AdLoadingError.unavailable\n        }\n        return ad\n    }\n}\n
"},{"location":"StorytellerModule/#request-aware-ad-modules","title":"Request-aware ad modules","text":"

Host-provided GAM or AdMob modules that know the exact ad unit only when starting a provider request can adopt StorytellerAdRequestTrackingModule. Set adSource to .gam or .admob so the SDK emits paid operational events. The protocol extends StorytellerModule with request-aware full-screen and bottom-banner methods:

Await onAdRequested immediately before each concrete provider load. Call it once for each native or banner attempt, including fallback attempts, invoke it serially, and do not retain it after the method returns. The SDK uses each reported value for Google AdRequested events and correlates the final attempt with load, failure, and paid events.

Set the same value on the returned StorytellerAd.adUnitId so rendered Ad lifecycle events retain it. The optional slot identifies the active full-screen request; modules that support cancelling their underlying load should honor its cancellation state. SDK-provided GAM and AdMob modules adopt this capability automatically.

For a detailed discussion of all the relevant considerations, please see the dedicated Ads page.

"},{"location":"StorytellerModule/#technical-consideration","title":"Technical Consideration","text":"

Because the StorytellerDelegate also conforms to StorytellerModule, the way our SDK works is as following:

"},{"location":"Themes/","title":"Themes","text":"

The appearance of the SDK can be customized by setting the theme property. This requires a StorytellerTheme configurable object.

let myTheme = StorytellerTheme()\nStoryteller.shared.theme = myTheme\n

This object is used as the global theme for every StorytellerListView included in your application. We, therefore, recommend setting it as early as possible in the application's lifecycle (for example, in the didFinishLaunchingWithOptions callback in the AppDelegate).

It is also possible to apply a specific theme to a specific StorytellerListView instance by passing it in the configuration. For example:

let myRowTheme = StorytellerTheme()\nlet storytellerStoriesRow = StorytellerStoriesRowView()\nstorytellerStoriesRow.configure(with: StorytellerStoriesListConfiguration(\n    categories: [\"category-id\"],\n    theme: myRowTheme\n))\n

For more information on setting a theme on an individual list, see StorytellerListView.

The Showcase app keeps all theme customization in a single place; see StorytellerThemeManager.globalTheme for a full example (colors, fonts, list styling, and per-item overrides).

If a supported change does not appear, follow Appearance or Configuration Does Not Change to check global and per-component precedence, the active light/dark branch, and reload behavior.

"},{"location":"Themes/#configuring-a-storytellertheme","title":"Configuring a StorytellerTheme","text":"

A StorytellerTheme consists of the following properties:

Which property is used depends on the uiStyle property of the StorytellerListView.

"},{"location":"Themes/#creating-themes","title":"Creating Themes","text":"

The Theme object contains all of the properties which can be customized in the SDK.

Some properties take their default value from others. For example, setting the primaryColor to #FF0000 will also result in the New Indicator for Rectangular Tiles being colored red. Such properties are indicated in the table below.

Note that theme properties may be used for other situations in future.

"},{"location":"Themes/#colors","title":"Colors","text":"

The colors property on theme is used to establish a set of base colors for the SDK to use.

Property Default Value Data Type Description primary #1C62EB UIColor The default accent color used throughout the UI. In general, this should be the primary brand color. success #3BB327 UIColor Used to indicate correct answers in Quizzes. alert #E21219 UIColor Used to indicate incorrect answers in Quizzes. white.primary #FFFFFF UIColor Used for white text white.secondary white.primary at 85% opacity UIColor Used for light text white.tertiary white.primary at 70% opacity UIColor Used for gray text black.primary #000000 UIColor Used for black text black.secondary black.primary at 85% opacity UIColor Used for light black text black.tertiary black.primary at 70% opacity UIColor Used for gray text"},{"location":"Themes/#font","title":"Font","text":"

Use the customFont property on the light and dark themes to set a custom font throughout the UI.

StorytellerFontProvider is an open class. Subclass it and override font(weight:size:) to provide the appropriate UIFont for each requested weight:

import StorytellerSDK\nimport UIKit\n\nfinal class CustomFontProvider: StorytellerFontProvider, @unchecked Sendable {\n    override func font(weight: StorytellerFontWeight, size: CGFloat) -> UIFont? {\n        switch weight {\n        case .light, .regular, .medium:\n            return UIFont(name: \"MyCustomFont\", size: size)\n        default:\n            return UIFont(name: \"MyCustomFontBold\", size: size)\n        }\n    }\n}\n\nvar theme = StorytellerTheme()\nlet customFont = CustomFontProvider()\ntheme.light.customFont = customFont\ntheme.dark.customFont = customFont\nStoryteller.shared.theme = theme\n

StorytellerFontWeight includes .light for custom providers that expose a light face. Existing integrations with an exhaustive switch over this public enum must add .light or an @unknown default branch when recompiling with SDK 11.5.1.

"},{"location":"Themes/#primitives","title":"Primitives","text":"

The primitives object contains base values which are used throughout the UI.

Property Default Value Data Type Description cornerRadius 8 CGFloat The corner radius used for rectangular tiles, buttons and poll/quiz answers"},{"location":"Themes/#lists","title":"Lists","text":"

The lists customizes properties of the various list types available from the SDK.

Property Default Value Data Type Description backgroundColor colors.white.primary UIColor Required for outline on Live chip and fade to the side of the row on the Web SDK enablePlayerOpen true Bool Controls whether the SDK opens the player when a tile is tapped. When set to false, the SDK will not open the player and the app must handle tile taps via StorytellerListViewDelegate.onTileTapped(type: StorytellerTileType) (includes categories: [StorytellerCategoryDetail] for both clips and stories). This setting is not applied for lists on SDK\u2011owned screens (Storyteller Home, Followable Categories, and Search) where the SDK always opens the player. animateTilesOnReorder true Bool When the reloadData() method is called to update lists, a reorder animation is added to visualise the updating process. row.tileSpacing 8 CGFloat The space between each Tile in a row row.startInset 12 CGFloat The space before the first Tile in a row row.endInset 12 CGFloat The space after the last Tile in a row grid.tileSpacing 8 CGFloat The space between each Tile in a grid, both vertically and horizontally grid.columns 2 CGFloat The number of columns in a grid. Not applicable to Search and Category screens. grid.topInset 12 CGFloat The space before the first row in a grid grid.bottomInset 12 CGFloat The space after the last row in a grid title.font nil StorytellerFontProvider Defines the font of the Title in Section title.textSize 22 CGFloat Size of the Title in Section title.lineHeight 28 CGFloat The line height of the Title in Section title.textCase default StorytellerTextCasing Sets the text case for the Title in Section. Possible values are upper, lower and default title.textColor nil UIColor Color of Title in Section"},{"location":"Themes/#gradient","title":"Gradient","text":"

The Gradient struct allows for the creation of a color gradient, with options to customize both the colors and the positions at which the gradient starts and ends.

Property Default Value Data Type Description startColor Required UIColor The color where the gradient begins. endColor Required UIColor The color where the gradient ends. startPosition Required Theme.Gradient.GradientPosition The position indicating where the gradient starts. endPosition Required Theme.Gradient.GradientPosition The position indicating where the gradient ends."},{"location":"Themes/#enum-gradientposition","title":"Enum: GradientPosition","text":"

Defines positions for starting and ending points of the gradient.

Value Description bottomLeft Bottom left corner of the gradient area. bottomCenter Bottom center edge of the gradient area. bottomRight Bottom right corner of the gradient area. centerLeft Center left edge of the gradient area. centerCenter Center of the gradient area. centerRight Center right edge of the gradient area. topLeft Top left corner of the gradient area. topCenter Top center edge of the gradient area. topRight Top right corner of the gradient area.

GradientPosition is a nested enum, not an Int-backed value. Construct a gradient by supplying all four required values:

import StorytellerSDK\nimport UIKit\n\nlet brandGradient = Theme.Gradient(\n    startColor: UIColor.systemBlue,\n    endColor: UIColor.systemPurple,\n    startPosition: .topCenter,\n    endPosition: .bottomCenter\n)\n
"},{"location":"Themes/#tiles","title":"Tiles","text":"

The tiles property can be used to customize the appearance of the Tiles.

Property Default Value Data Type Description chip.textSize 11 CGFloat Text size for the New Indicator and Live Indicator. chip.show true Bool Used to show/hide the new/live chip title.textSize 11 CGFloat Size of the Title on a Tile title.lineHeight 13 CGFloat The line height of the Title on a Tile title.alignment center StorytellerAlignment The alignment of the Title on a Tile. Possible values are left, center and right circularTile.title.unreadTextColor inherits colors.black.primary for light, colors.white.primary for dark UIColor The text color of the Title for a circular tile when the story or the clip is unread circularTile.title.readTextColor inherits colors.black.tertiary for light, colors.white.tertiary for dark UIColor The text color of the Tile for a circular tile when the story or the clip is read circularTile.unreadIndicatorColor inherits colors.primary UIColor The color of the ring around a circular tile when the story or the clip is unread circularTile.readIndicatorColor #C5C5C5 UIColor The color of the ring around a circular tile when the story or the clip is read circularTile.unreadIndicatorGradient nil Gradient? The gradient of the ring around a circular tile when the story or the clip is unread. If set, overrides circularTile.unreadIndicatorColor circularTile.unreadIndicatorBorderColor nil UIColor? The border color of the ring around a circular tile when the story or the clip is unread circularTile.readIndicatorBorderColor nil UIColor? The border color of the ring around a circular tile when the story or the clip is read circularTile.unreadBorderWidth 2 CGFloat The width of Circular Tile ring border in unread state circularTile.readBorderWidth 2 CGFloat The width of Circular Tile ring border in read state circularTile.liveChip.readImage null UIImage? Image to be used in place of default read Live Indicator. circularTile.liveChip.unreadImage null UIImage? Image to be used in place of default unread Live Indicator circularTile.liveChip.unreadBackgroundColor colors.alert UIColor Background color of the Live Indicator when the story contains unread pages or the clip has not been viewed. circularTile.liveChip.readBackgroundColor colors.black.tertiary UIColor Background color of the Live Indicator when all story pages have been read or the clip has been viewed. circularTile.liveChip.unreadBackgroundGradient nil Gradient? The gradient of the ring around a live tile and background of the Live Indicator. If set, overrides circularTile.liveChip.unreadBackgroundColor circularTile.liveChip.unreadTextColor colors.white.primary UIColor Text color of the Live Indicator when the story contains unread pages or the clip has not been viewed. circularTile.liveChip.readTextColor colors.white.primary UIColor Text color of the Live Indicator when all story pages have been read or the clip has been viewed. circularTile.liveChip.unreadBorderColor null UIColor? Border color of the Live Indicator when the story contains unread pages or the clip has not been viewed. circularTile.liveChip.readBorderColor null UIColor? Boder color of the Live Indicator when all story pages have been read or the clip has been viewed. rectangularTile.padding 8 CGFloat The internal padding for a rectangular story or the clip tile rectangularTile.title.textColor inherits colors.white.primary UIColor The text color of the Title for a rectangular tile rectangularTile.chip.alignment right StorytellerAlignment The alignment of the New Indicator and Live Indicator in Rectangular Tiles. Possible values are left, center or right rectangularTile.unreadIndicator.image null UIImage? An image which can be used in place of the default unread indicator for a rectangular tile. If set, overrides rectangularTile.unreadIndicator.gradient rectangularTile.unreadIndicator.gradient nil Gradient? The background gradient of the unread indicator for a rectangular tile. If set, overrides rectangularTile.unreadIndicator.backgroundColor rectangularTile.unreadIndicator.backgroundColor inherits colors.primary UIColor The background color of the unread indicator for a rectangular tile rectangularTile.unreadIndicator.textColor inherits colors.white.primary UIColor The text color of the unread indicator for a rectangular tile rectangularTile.unreadIndicator.borderColor null UIColor? Border color of the unread indicator for a rectangular tile rectangularTile.liveChip.readImage null UIImage? Image to be used in place of default read Live Indicator. rectangularTile.liveChip.unreadImage null UIImage? Image to be used in place of default unread Live Indicator. If set, overrides rectangularTile.liveChip.unreadBackgroundGradient rectangularTile.liveChip.unreadBackgroundGradient nil Gradient? Gradient background to be used for the Live Indicator. If set, overrides rectangularTile.liveChip.unreadBackgroundColor rectangularTile.liveChip.unreadBackgroundColor colors.alert UIColor Background color of the Live Indicator when the story contains unread pages or the clip has not been viewed. rectangularTile.liveChip.readBackgroundColor colors.black.tertiary UIColor Background color of the Live Indicator when all pages have been read or the clip has been viewed rectangularTile.liveChip.unreadTextColor colors.white.primary UIColor Text color of the Live Indicator when the story contains unread pages or the clip has not been viewed. rectangularTile.liveChip.readTextColor colors.white.primary UIColor Text color of the Live Indicator when all story pages have been read or the clip has been viewed. rectangularTile.liveChip.unreadBorderColor null UIColor? Border color of the Live Indicator when the story contains unread pages or the clip has not been viewed. rectangularTile.liveChip.readBorderColor null UIColor? Border color of the Live Indicator when all story pages have been read or the clip has been viewed.

"},{"location":"Themes/#player","title":"Player","text":"

The player property is used to customize properties relating to the Story and Clips Player.

Property Default Value Data Type Description showStoryIcon false Bool Shows the round story icon before the Story Title in the Player showTimestamp true Bool Shows the timestamp after the Story Title in the Player, indicating how long ago a story was published showShareButton true Bool Shows the share button in the Player. Setting this to false entirely disables sharing in Storyteller showLikeButton true Bool Shows the like button in the Clips Player. Setting this to false entirely disables liking in Storyteller enableFollowableCategorySwipeFromRightEdge true Bool Enables opening the Followable Category screen with a right-edge swipe in the Clips Player. Set to false to disable this gesture showShareCount true Bool Shows the share count label in the Clips Player. Does not affect share button visibility showLikeCount true Bool Shows the like count label in the Clips Player. Does not affect like button visibility clips.showButtonBackgrounds true Bool Controls whether the Clips Player renders the default button backgrounds for like, share, mute, and captions buttons clips.actionIconSize 32 CGFloat Size in points for Clips Player action icons. Values outside the supported 24...38 range are clamped during theme resolution clips.feedSwitcher.selected.fontWeight selection-style default StorytellerFontWeight? Optional selected For You / Following tab weight. When set, it overrides the weight implied by theme.behavior.following.feedSwitcher.selectionStyle clips.feedSwitcher.selected.textSize 16 CGFloat? Optional selected For You / Following tab text size clips.feedSwitcher.selected.lineHeight nil CGFloat? Optional selected For You / Following tab line height clips.feedSwitcher.unselected.fontWeight selection-style default StorytellerFontWeight? Optional unselected For You / Following tab weight. When set, it overrides the weight implied by theme.behavior.following.feedSwitcher.selectionStyle clips.feedSwitcher.unselected.textSize 16 CGFloat? Optional unselected For You / Following tab text size clips.feedSwitcher.unselected.lineHeight nil CGFloat? Optional unselected For You / Following tab line height clips.eyebrow.font inherits theme.customFont StorytellerFontProvider? Font family used for the Clips Player eyebrow row. The SDK requests the .regular weight at render time clips.eyebrow.textSize 15 CGFloat Text size used for the Clips Player eyebrow row clips.eyebrow.lineHeight nil CGFloat? Optional line height for the Clips Player eyebrow row. nil preserves the current UIKit spacing for the resolved font clips.eyebrow.textColor inherits theme.colors.white.secondary UIColor? Text color used for the Clips Player eyebrow row clips.title.font inherits theme.customFont StorytellerFontProvider? Font family used for the Clips Player main title. The SDK requests clips.title.fontWeight, defaulting to .bold clips.title.fontWeight .bold StorytellerFontWeight? Optional weight requested from the Clips Player title font provider clips.title.textSize 16 CGFloat Text size used for the Clips Player main title clips.title.lineHeight nil CGFloat? Optional line height for the Clips Player main title. nil preserves the system default line spacing for the resolved font clips.title.textColor inherits theme.colors.white.primary UIColor? Text color used for the Clips Player main title clips.categoryNavigation.fontWeight .bold StorytellerFontWeight? Optional category-navigation label weight requested from theme.customFont clips.categoryNavigation.textSize 15 CGFloat? Optional category-navigation label text size clips.categoryNavigation.lineHeight nil CGFloat? Optional category-navigation label line height clips.topGradient black at 60% opacity from .topCenter to clear at .bottomCenter Theme.Gradient? Customizes the existing 96-point top readability scrim without changing its bounds or visibility clips.bottomGradient clear at .topCenter to black at 60% opacity at .bottomCenter Theme.Gradient? Customizes the existing title-backed bottom readability scrim without changing its bounds or title-empty visibility rule clips.progressBar.position .bottom Theme.Player.Clips.ProgressBar.Position Sets the Clips progress bar to .bottom or .aboveAction. .aboveAction applies only to Embedded Clips with a visible primary action clips.spacing.backButtonStartInset 0 CGFloat Left inset in points for the Clips Player back/close button clips.spacing.contentInsetHorizontal 16 CGFloat Horizontal (start/end) padding in points for the description and action content areas clips.spacing.contentInsetBottom 16 CGFloat Bottom padding in points for the description and action content areas clips.spacing.actionSpacing 12 CGFloat Vertical spacing in points between action icons (follow, like, share, mute, caption) clips.spacing.eyebrowToTitleSpacing 4 CGFloat Spacing in points between the eyebrow text and the clip title clips.spacing.titleToActionSpacing 16 CGFloat Horizontal gap in points between the title/description text and the action icons column clips.spacing.titleToCategoriesSpacing nil CGFloat? Vertical gap in points between the rendered title/description block and categories in Embedded Clips clips.spacing.categoriesToMoreSpacing nil CGFloat? Vertical gap in points between categories and the existing expansion/collapse affordance in Embedded Clips clips.spacing.metadataToProgressBarSpacing nil CGFloat? Minimum vertical gap in points between the metadata block and the visible progress track in Embedded Clips clips.spacing.progressBarToActionSpacing nil CGFloat? Minimum vertical gap in points between the visible progress track and primary action in Embedded Clips, independent of progress-bar ordering liveChip.image null UIImage? Image used in place of Live Chip before Live Story or Clip Titles. If set, it overrides liveChip.backgroundGradient liveChip.textColor null UIColor? Text color used for badge label for Live Story or Clip liveChip.backgroundGradient null Gradient? Background gradient of the badge for Live Story or Clip. If set, it overrides liveChip.backgroundColor liveChip.backgroundColor theme.colors.alert UIColor? Background color of the badge for Live Story or Clip liveChip.borderColor null UIColor Border color of the badge for Live Story or Clip icons.share null UIImage? An image to be used in place of the default share icon icons.refresh null UIImage? Refresh button image to be used in place of refresh share icon, used in the error state icons.back null UIImage? Back button image to be used in place of the default Clips back icon icons.like.initial null UIImage? An image to be used in place of the default like icon when the clip is not liked icons.like.liked null UIImage? An image to be used in place of the default like icon when the clip is liked icons.like.animation.liked null StorytellerPlayerIcons.LikeIcons.Animation.Resource? Bundled Lottie animation played when the Clips like button changes from unliked to liked icons.like.animation.unliked null StorytellerPlayerIcons.LikeIcons.Animation.Resource? Bundled Lottie animation played when the Clips like button changes from liked to unliked icons.mute.muted null UIImage? Image used for the mute button when audio is muted in Stories and Clips icons.mute.unmuted null UIImage? Image used for the mute button when audio is unmuted in Stories and Clips icons.captions.enabled null UIImage? Image used for the captions button when captions are enabled in Stories and Clips icons.captions.disabled null UIImage? Image used for the captions button when captions are disabled in Stories and Clips

If only one mute or captions state is provided, the missing state continues to use the bundled Storyteller icon.

Example:

var theme = StorytellerTheme()\n\ntheme.light.player.clips.showButtonBackgrounds = false\ntheme.light.player.clips.actionIconSize = 24\ntheme.light.player.clips.eyebrow = .init(\n    font: StorytellerFontProvider(),\n    textSize: 20,\n    lineHeight: 24,\n    textColor: UIColor.white\n)\ntheme.light.player.clips.title = .init(\n    font: StorytellerFontProvider(),\n    textSize: 20,\n    lineHeight: 24,\n    textColor: UIColor.white,\n    fontWeight: .regular\n)\ntheme.light.player.clips.feedSwitcher = .init(\n    selected: .init(fontWeight: .regular, textSize: 15, lineHeight: 20),\n    unselected: .init(fontWeight: .light, textSize: 15, lineHeight: 20)\n)\ntheme.light.player.clips.categoryNavigation = .init(\n    fontWeight: .regular,\n    textSize: 13,\n    lineHeight: 16\n)\ntheme.light.player.clips.topGradient = .init(\n    startColor: UIColor.systemBlue.withAlphaComponent(0.8),\n    endColor: .clear,\n    startPosition: .topLeft,\n    endPosition: .bottomRight\n)\ntheme.light.player.clips.bottomGradient = .init(\n    startColor: UIColor.systemPink.withAlphaComponent(0.8),\n    endColor: .clear,\n    startPosition: .bottomRight,\n    endPosition: .topLeft\n)\ntheme.light.player.clips.progressBar.position = .aboveAction\ntheme.light.player.clips.spacing = .init(\n    backButtonStartInset: 12,\n    contentInsetHorizontal: 16,\n    contentInsetBottom: 20,\n    actionSpacing: 20,\n    eyebrowToTitleSpacing: 6,\n    titleToActionSpacing: 16,\n    titleToCategoriesSpacing: 8,\n    categoriesToMoreSpacing: 4,\n    metadataToProgressBarSpacing: 16,\n    progressBarToActionSpacing: 16\n)\ntheme.light.player.icons = StorytellerPlayerIcons(\n    back: UIImage(named: \"icon-back-custom\"),\n    muteMuted: UIImage(named: \"icon-mute-muted-custom\"),\n    muteUnmuted: UIImage(named: \"icon-mute-unmuted-custom\"),\n    captionsEnabled: UIImage(named: \"icon-captions-enabled-custom\"),\n    captionsDisabled: UIImage(named: \"icon-captions-disabled-custom\")\n)\n

The canonical key path for this API is theme.player.clips.eyebrow.

clips.eyebrow.lineHeight intentionally defaults to nil to preserve the current UIKit eyebrow spacing.

clips.title.lineHeight intentionally defaults to nil, unlike other title theme APIs that ship a non-nil line height. Leaving it unset preserves the current Clips title spacing.

"},{"location":"Themes/#clips-player-typography","title":"Clips player typography","text":"

The feed switcher and category-navigation labels inherit theme.customFont; they do not have separate font-family properties. The clip title continues to use clips.title.font, falling back to theme.customFont. Each configured weight is requested from that provider.

When feed-switcher weights are absent, underline selection mode keeps .semibold for both tabs, while text-weight selection mode keeps .heavy selected and .medium unselected. Explicit selected or unselected weights replace only those fallback weights; theme.behavior.following.feedSwitcher.selectionStyle still controls underline visibility, animation, and the remaining selection behavior.

Configured sizes and line heights scale with Dynamic Type. Category names and the delimiter from theme.behavior.player.clips.categoryNavigation.delimiter share one attributed typography style, while the existing less control keeps its current style.

Host values and remote light/dark values resolve independently for every typography field. A feed- or collection-specific remote value overrides the tenant/global remote value, which overrides the host-supplied light or dark theme. Remote font-weight strings are case-insensitive, so values such as REGULAR, LIGHT, and BLACK resolve to the corresponding lowercase-backed public enum cases. Missing, unknown, non-finite, or non-positive remote values continue to the next fallback without changing compatibility output.

Sky configuration:

var theme = StorytellerTheme()\n\ntheme.light.player.clips.feedSwitcher.selected = .init(\n    fontWeight: .regular,\n    textSize: 15,\n    lineHeight: 20\n)\ntheme.light.player.clips.feedSwitcher.unselected = .init(\n    fontWeight: .light,\n    textSize: 15,\n    lineHeight: 20\n)\ntheme.light.player.clips.title.fontWeight = .regular\ntheme.light.player.clips.title.textSize = 15\ntheme.light.player.clips.title.lineHeight = 20\ntheme.light.player.clips.categoryNavigation = .init(\n    fontWeight: .regular,\n    textSize: 13,\n    lineHeight: 16\n)\n

Equivalent remote Settings fragment:

{\n  \"theme\": {\n    \"light\": {\n      \"player\": {\n        \"clips\": {\n          \"feedSwitcher\": {\n            \"selected\": { \"fontWeight\": \"REGULAR\", \"textSize\": 15, \"lineHeight\": 20 },\n            \"unselected\": { \"fontWeight\": \"LIGHT\", \"textSize\": 15, \"lineHeight\": 20 }\n          },\n          \"title\": { \"fontWeight\": \"REGULAR\", \"textSize\": 15, \"lineHeight\": 20 },\n          \"categoryNavigation\": { \"fontWeight\": \"REGULAR\", \"textSize\": 13, \"lineHeight\": 16 }\n        }\n      }\n    },\n    \"dark\": {\n      \"player\": {\n        \"clips\": {\n          \"feedSwitcher\": {\n            \"selected\": { \"fontWeight\": \"REGULAR\", \"textSize\": 15, \"lineHeight\": 20 },\n            \"unselected\": { \"fontWeight\": \"LIGHT\", \"textSize\": 15, \"lineHeight\": 20 }\n          },\n          \"title\": { \"fontWeight\": \"REGULAR\", \"textSize\": 15, \"lineHeight\": 20 },\n          \"categoryNavigation\": { \"fontWeight\": \"REGULAR\", \"textSize\": 13, \"lineHeight\": 16 }\n        }\n      }\n    }\n  }\n}\n
"},{"location":"Themes/#clips-player-gradients","title":"Clips player gradients","text":"

theme.player.clips.topGradient and theme.player.clips.bottomGradient use the existing two-colour Theme.Gradient type. All nine GradientPosition values are supported for either endpoint, and the start and end positions must be different.

When topGradient is absent at every layer, the Clips Player keeps its existing black-at-60%-opacity to clear gradient from .topCenter to .bottomCenter over the fixed 96-point top scrim. When bottomGradient is absent at every layer, it keeps the existing clear-at-top to black-at-60%-opacity-at-bottom appearance over the title-stack-derived bottom scrim. The bottom scrim remains hidden when the Clip title is missing or empty.

Each gradient resolves independently in this order: feed- or collection-specific remote light/dark theme, tenant/global remote light/dark theme, host-supplied light/dark theme, then its iOS default. Missing, null, incomplete, malformed, or unknown remote values continue to the next layer for that gradient only; a malformed top value does not discard a valid bottom value, and vice versa.

A clear-to-clear gradient is an explicit transparent scrim and does not fall back to the default. This can be used to remove either scrim visually while preserving its existing container and visibility behavior. Custom colours are rendered as supplied, so the integrating app is responsible for maintaining sufficient contrast between video content and Player controls or text.

Remote colours accept #RRGGBB or alpha-first #AARRGGBB values. For example:

{\n  \"theme\": {\n    \"light\": {\n      \"player\": {\n        \"clips\": {\n          \"topGradient\": {\n            \"startColor\": \"#CC0057B8\",\n            \"endColor\": \"#00000000\",\n            \"startPosition\": \"topLeft\",\n            \"endPosition\": \"bottomRight\"\n          },\n          \"bottomGradient\": {\n            \"startColor\": \"#CCEF3340\",\n            \"endColor\": \"#00000000\",\n            \"startPosition\": \"bottomRight\",\n            \"endPosition\": \"topLeft\"\n          }\n        }\n      }\n    }\n  }\n}\n
"},{"location":"Themes/#embedded-clips-spacing","title":"Embedded Clips spacing","text":"

The four optional internal spacing properties apply only to Embedded Clips. Each property resolves independently through the active feed-specific server appearance, tenant/global server appearance, and host-supplied light or dark theme. Missing, non-finite, or negative values are treated as unset and preserve the existing iOS layout for that relationship.

Configured spacing is added only when both rendered elements are present. The fixed point values do not scale with Dynamic Type, while the surrounding metadata continues to reflow. The Sky configuration uses 8, 4, 16, and 16 points for title-to-categories, categories-to-expansion, metadata-to-progress, and progress-to-action respectively.

Example:

var theme = StorytellerTheme()\n\ntheme.light.player.icons = StorytellerPlayerIcons(\n    back: UIImage(named: \"icon-back-custom\"),\n    likeInitial: UIImage(named: \"custom_like_initial\"),\n    likeLiked: UIImage(named: \"custom_like_liked\"),\n    likeAnimation: .init(\n        liked: .init(name: \"custom_like_liked_animation\"),\n        unliked: .init(name: \"custom_like_unliked_animation\")\n    )\n)\n

You can omit likeInitial and likeLiked when you want to keep the SDK's default static heart icons and only override the transition animations.

Tenant settings can also provide static Clips Player like icons through the remote theme payload. Use complete URL pairs under the light and/or dark style theme:

{\n  \"light\": {\n    \"player\": {\n      \"icons\": {\n        \"like\": {\n          \"initial\": \"https://example.com/like.png\",\n          \"liked\": \"https://example.com/liked.png\"\n        }\n      }\n    }\n  }\n}\n

Both initial and liked must be provided for the SDK to replace the default static like icons. Remote settings do not configure icons.like.animation; use the local StorytellerTheme API for bundled Lottie animations.

"},{"location":"Themes/#clips-progress-bar-position","title":"Clips progress bar position","text":"

theme.player.clips.progressBar.position controls the progress bar hierarchy for Clips. It supports the following appearance-scoped values:

Value Behavior .bottom / bottom Preserves the existing progress bar position. This is the default .aboveAction / aboveAction Places the progress bar above the visible primary action in Embedded Clips

When .aboveAction is selected, modal and full-screen Clips remain unchanged. Embedded Clips without a visible primary action also keep the stable bottom position without reserving an empty action gap. The scrub gesture area follows the rendered progress bar in both positions.

The active light or dark value resolves in this order: feed-specific remote theme, tenant/global remote theme, host-supplied theme, then .bottom. Unknown or malformed remote values are ignored so normal inheritance can continue.

Example remote Settings fragment:

{\n  \"theme\": {\n    \"light\": {\n      \"player\": {\n        \"clips\": {\n          \"progressBar\": {\n            \"position\": \"aboveAction\"\n          }\n        }\n      }\n    }\n  }\n}\n
"},{"location":"Themes/#modal-clips-content-bottom-anchor","title":"Modal Clips content bottom anchor","text":"

theme.behavior.player.clips.modalContentBottomAnchor is a remote Settings property for non-embedded modal Clips Players. It accepts the following values:

Value Behavior video Keeps the title, metadata, side actions, primary action, and progress controls anchored to the bottom of the 9:16 media frame. This is the default and preserves the existing layout screen Keeps the media top-aligned at 9:16 while anchoring the lower Player UI to the viewport safe-area bottom, using the space below the media on taller screens

Missing, null, malformed, or unknown values resolve to video. The setting does not stretch or crop video, does not affect Embedded Clips, and keeps standard Ads on the existing video-anchored layout.

Example remote Settings fragment:

{\n  \"theme\": {\n    \"behavior\": {\n      \"player\": {\n        \"clips\": {\n          \"modalContentBottomAnchor\": \"screen\"\n        }\n      }\n    }\n  }\n}\n
"},{"location":"Themes/#followable-category-profile","title":"Followable Category Profile","text":"

The default Followable Category profile screen is configured from remote Settings via the CMS. There is no SDK public Theme API for these profile fields.

Set theme.behavior.player.clips.enableProfileScreen to true to use the profile screen. When this value is false or missing, the SDK uses the legacy Followable Category screen. A custom category screen returned by StorytellerDelegate.viewController(for:) always takes priority over either SDK screen.

Profile appearance is configured independently under theme.light.profileScreen and theme.dark.profileScreen:

Property Default Value Data Type Description contentAvailability.clips true Bool Shows the Latest/Popular Clips feed contentAvailability.stories false Bool Shows the Stories row sourced from the category display title displayTitle.textSize 22 Int Category title text size displayTitle.lineHeight 28 Int Category title line height displayTitle.textCase default String default, upper, or lower displayTitle.textColor #FFFFFF String Category title color description.textSize 16 Int Category description text size description.lineHeight 20 Int Category description line height description.textCase default String default, upper, or lower description.textColor #D9FFFFFF String Category description color followButton.cornerRadius 8 Int Follow/Unfollow button corner radius followButton.title.textSize 14 Int Button title text size followButton.title.lineHeight 20 Int Button title line height followButton.title.textCase default String default, upper, or lower followButton.followed.textColor #FFFFFF String Unfollow-state title color followButton.followed.backgroundColor #33FFFFFF String Unfollow-state background color followButton.unfollowed.textColor #FFFFFF String Follow-state title color followButton.unfollowed.backgroundColor #1C62EB String Follow-state background color tabs.title.textSize 20 Int Latest/Popular title text size tabs.title.lineHeight 24 Int Latest/Popular title line height tabs.title.textCase default String default, upper, or lower tabs.selectedTextColor Light: #FF1A1A1A; Dark: #FFFFFFFF String Selected tab title color tabs.unselectedTextColor Light: #991A1A1A; Dark: #D9FFFFFF String Unselected tab title color

Colors accept six-digit RGB (#RRGGBB) or eight-digit alpha-first ARGB (#AARRGGBB). Missing, null, malformed, or out-of-range fields fall back independently, so one invalid field does not discard valid sibling values. If both content availability values resolve to false, the SDK falls back to Clips enabled and Stories disabled.

Missing Profile tab colours follow the active appearance. Automatic UI style uses the system Light or Dark appearance, while forced Light or Dark styles use their corresponding fallback values. Explicitly configured selected or unselected colours take precedence independently.

Example remote Settings fragment:

{\n  \"theme\": {\n    \"behavior\": {\n      \"player\": {\n        \"clips\": {\n          \"enableProfileScreen\": true\n        }\n      }\n    },\n    \"light\": {\n      \"profileScreen\": {\n        \"contentAvailability\": {\n          \"clips\": true,\n          \"stories\": true\n        },\n        \"displayTitle\": {\n          \"textColor\": \"#FF1A1A1A\"\n        },\n        \"tabs\": {\n          \"selectedTextColor\": \"#FF1A1A1A\",\n          \"unselectedTextColor\": \"#991A1A1A\"\n        }\n      }\n    }\n  }\n}\n

Text uses the resolved SDK theme font. The profile image comes from the CMS and its border is not themeable. theme.light.categoryScreen.followIcons and theme.dark.categoryScreen.followIcons continue to configure the legacy screen and are separate from profileScreen.

"},{"location":"Themes/#cards","title":"Cards","text":"

The cards property applies customizations to Storyteller Cards. Cards audio behavior is controlled by tenant settings, while local theme values can replace the icons used by the Cards audio control.

Property Default Value Data Type Description audio.mutedIcon nil UIImage? Complete 48x48 visual used for the Cards audio control when the active video Card is muted audio.unmutedIcon nil UIImage? Complete 48x48 visual used for the Cards audio control when the active video Card is unmuted

If a Cards audio icon is not provided, the SDK uses a default 48x48 tap target with a bundled 32x32 circular state icon centered inside it. Custom theme.cards.audio images replace that whole visual directly, without an SDK-drawn circle/background; include any desired backer in the image asset. theme.player.icons.mute customizes Stories and Clips Player mute icons; use theme.cards.audio for Cards.

Example:

var theme = StorytellerTheme()\n\ntheme.light.cards.audio = .init(\n    mutedIcon: UIImage(named: \"icon-card-audio-muted\"),\n    unmutedIcon: UIImage(named: \"icon-card-audio-unmuted\")\n)\n
"},{"location":"Themes/#buttons","title":"Buttons","text":"

The buttons property applies customizations to buttons which appear throughout the UI.

Property Default Value Data Type Description backgroundColor inherits colors.white.primary UIColor The background color of buttons throughout the UI textColor inherits colors.black.primary UIColor The text color of buttons throughout the SDK textCase default StorytellerTextCasing Sets the text case for buttons throughout the UI. Possible values are upper, lower and default cornerRadius inherits primitives.cornerRadius CGFloat The corner radius for all buttons throughout the UI"},{"location":"Themes/#instructions","title":"Instructions","text":"

Use the instructions property to customize the appearance of the instructions screen.

Property Default Value Data Type Description show true Bool Determines whether the Instructions Screen is shown the first time a user opens the Story Player. Set to false to completely disable the instructions screen. headingColor inherits colors.black.primary for light, colors.white.primary for dark UIColor The color of the heading text on the Instructions Screen headingTextCase default StorytellerTextCasing Determines the text case of the heading on the Instructions Screen. Possible values are upper, lower and default headingFont null StorytellerFontProvider Defines the font of the heading text on the Instructions Screen subHeadingColor inherits colors.black.secondary for light, colors.white.secondary for dark UIColor The color of the subheading text on the Instructions Screen backgroundColor inherits colors.white.primary for light, colors.black.primary for dark UIColor The color of the background of the Instructions Screen icons null StorytellerInstructionIcons A set of custom icons to be used for each instruction on the Instructions Screen button.backgroundColor inherits colors.black.primary for light, colors.white.primary for dark UIColor The background color of the button used on the Instructions Screen button.textColor inherits colors.white.primary for light, colors.black.primary for dark UIColor The text color of the button used on the Instructions Screen

The icons property can be used to provide a completely custom set of icons. The icons should be 48x48 PNGs. An example of using this property is shown below:

let customIcons = StorytellerInstructionIcons(\n    forward: UIImage(named: \"icon-forward-custom\"),\n    pause: UIImage(named: \"icon-pause-custom\"),\n    back: UIImage(named: \"icon-back-custom\"),\n    move: UIImage(named: \"icon-move-custom\")\n)\n\nvar theme = StorytellerTheme()\ntheme.light.instructions.icons = customIcons\n

"},{"location":"Themes/#engagement-units","title":"Engagement Units","text":"

The engagementUnits property can be used to customize properties relating to Polls and Quizzes.

Property Default Value Data Type Description poll.answerTextColor inherits colors.black.primary UIColor The text color used for Poll Answers poll.percentBarColor #CDD0DC UIColor The background color of the percentage bar in Poll Answers poll.selectedAnswerBorderColor inherits colors.primary UIColor The border color applied to the selected Poll Answer poll.answeredMessageTextColor inherits colors.white.tertiary UIColor The color of the vote count shown to users after they select a Poll Answer poll.selectedAnswerBorderImage null UIImage? A border image which can be used for the selected Poll Answer. If this is set, selectedAnswerBorderColor is used. poll.showImageAnswerGradientOverlay true Bool Shows the gradient overlay behind the text in image Poll Answers poll.showPercentBarBackground false Bool Adds a striped background under the percentage bar in Poll Answers triviaQuiz.correctColor inherits colors.success UIColor The color used to show correct answers in Trivia Quizzes triviaQuiz.incorrectColor inherits colors.alert UIColor The color used to show incorrect answers in Trivia Quizzes

"},{"location":"Themes/#search","title":"Search","text":"

The search property applies customizations to suggestions, no-results, results and filters in the Search component. Every new Search appearance property is optional. Omitted values keep the existing iOS appearance, and theme.light and theme.dark resolve independently.

Search text uses customFont with the semantic weight for each element. search.heading.font remains the font override for the Filters title, while Search result section headings continue to use lists.title. Configure the Apply Filters button through search.filters.applyButton; each remote or host-app field resolves independently before the compatibility default. Shared buttons values do not affect this Search action.

Property Default Value Data Type Description search.backgroundColor colors.white.primary in light mode; colors.black.primary in dark mode UIColor? Background color across Search states search.backIcon chevron.backward system image UIImage? Image to be used as a back icon in the Search UI search.heading.font inherits customFont StorytellerFontProvider? Font override for the Filters title search.heading.textSize 22 CGFloat Size of the Filters title search.heading.lineHeight 28 CGFloat Line height of the Filters title search.heading.textCase default StorytellerTextCasing Text case for the Filters title search.heading.textColor inherits lists.title.textColor UIColor Color of Filter View title search.input.backgroundColor existing Search field fill UIColor? Search field background color search.input.textColor current light/dark primary text color UIColor? Entered search text color search.input.placeholderTextColor system placeholder color UIColor? Search placeholder color search.input.iconColor system gray UIColor? Search and clear icon color search.input.cornerRadius existing Search field radius CGFloat? Search field corner radius search.input.textSize 16 CGFloat? Search field text size search.input.lineHeight font default CGFloat? Optional Search field line height search.filterButton.backgroundColor clear UIColor? Filter button background color search.filterButton.iconColor current light/dark primary text color UIColor? Filter icon color search.filterButton.cornerRadius 0 CGFloat? Filter button corner radius search.suggestions.textColor current light/dark primary text color UIColor? Suggestion text color search.suggestions.iconColor current light/dark primary text color UIColor? Suggestion icons color search.suggestions.iconBackgroundColor existing Search field fill UIColor? Magnifying-glass icon background color search.suggestions.textSize 16 CGFloat? Suggestion text size search.suggestions.lineHeight font default CGFloat? Optional suggestion line height search.noResults.iconColor #B0B0B4 UIColor? No-results icon color search.noResults.title.textColor current light/dark primary text color UIColor? No-results title color search.noResults.title.textSize inherits lists.title.textSize CGFloat? No-results title size search.noResults.title.lineHeight inherits lists.title.lineHeight CGFloat? No-results title line height search.noResults.title.textCase default StorytellerTextCasing? No-results title text case search.noResults.message.textColor current light/dark tertiary text color UIColor? No-results message color search.noResults.message.textSize 16 CGFloat? No-results message size search.noResults.message.lineHeight font default CGFloat? Optional no-results message line height search.noResults.message.textCase default StorytellerTextCasing? No-results message text case search.filters.backgroundColor current light/dark background color UIColor? Filter sheet background color search.filters.handleColor system secondary color UIColor? Filter sheet drag-handle color search.filters.sectionHeading.textColor current light/dark primary text color UIColor? Filter section heading color search.filters.sectionHeading.textSize 16 CGFloat? Filter section heading size search.filters.sectionHeading.lineHeight font default CGFloat? Optional filter section heading line height search.filters.sectionHeading.textCase default StorytellerTextCasing? Filter section heading text case search.filters.option.backgroundColor existing Search field fill UIColor? Unselected filter option background color search.filters.option.textColor current light/dark primary text color UIColor? Unselected filter option text color search.filters.option.borderColor clear UIColor? Unselected filter option border color search.filters.option.selectedBackgroundColor existing Search field fill UIColor? Selected filter option background color search.filters.option.selectedTextColor current light/dark primary text color UIColor? Selected filter option text color search.filters.option.selectedBorderColor current light/dark primary text color UIColor? Selected filter option border color search.filters.option.cornerRadius inherits primitives.cornerRadius CGFloat? Filter option corner radius search.filters.option.textSize 16 CGFloat? Filter option text size search.filters.option.lineHeight font default CGFloat? Optional filter option line height search.filters.applyButton.backgroundColor black in light mode; white in dark mode UIColor? Apply Filters button background color search.filters.applyButton.textColor white in light mode; black in dark mode UIColor? Apply Filters button text color search.filters.applyButton.textCase default StorytellerTextCasing Apply Filters button text case search.filters.applyButton.cornerRadius inherits primitives.cornerRadius CGFloat? Apply Filters button corner radius 
var theme = StorytellerTheme()\n\ntheme.light.search.backgroundColor = UIColor.white\ntheme.light.search.input.backgroundColor = UIColor.systemGray6\ntheme.light.search.input.iconColor = UIColor.systemBlue\ntheme.light.search.filterButton.backgroundColor = UIColor.systemBlue\ntheme.light.search.filterButton.iconColor = UIColor.white\ntheme.light.search.noResults.title.textColor = UIColor.systemBlue\ntheme.light.search.filters.option.selectedBorderColor = UIColor.systemBlue\ntheme.light.search.filters.applyButton.backgroundColor = UIColor.systemBlue\ntheme.light.search.filters.applyButton.textColor = UIColor.white\n\ntheme.dark.search.backgroundColor = UIColor.black\ntheme.dark.search.input.backgroundColor = UIColor.secondarySystemBackground\ntheme.dark.search.filters.applyButton.backgroundColor = UIColor.white\ntheme.dark.search.filters.applyButton.textColor = UIColor.black\n\nStoryteller.shared.theme = theme\n
"},{"location":"Themes/#example","title":"Example","text":"
import StorytellerSDK\nimport UIKit\n\n// Subclassing font providers\nfinal class CustomFontProvider: StorytellerFontProvider, @unchecked Sendable {\n    override func font(weight: StorytellerFontWeight, size: CGFloat) -> UIFont? {\n        switch weight {\n        case .light, .regular, .medium:\n            return UIFont(name: \"Custom Font Regular\", size: size)\n        default:\n            return UIFont(name: \"Custom Font Bold\", size: size)\n        }\n    }\n}\n\n// Setting instruction icons\nlet icons = StorytellerInstructionIcons(\n    forward: UIImage(named: \"custom-icon-forward-white\"),\n    pause: UIImage(named: \"custom-icon-pause-white\"),\n    back: UIImage(named: \"custom-icon-forward-white\"),\n    move: UIImage(named: \"custom-icon-move-white\")\n)\n\n// Creating the theme struct\nvar theme = StorytellerTheme()\n\n// Customizing theme by direct property access\ntheme.light.colors.primary = UIColor.blue\ntheme.light.instructions.headingColor = UIColor.black\ntheme.light.instructions.icons = icons\ntheme.light.customFont = CustomFontProvider()\n\n// Copying common theme properties over to the dark side\ntheme.dark = theme.light\n\n// Applying dark mode specific values\ntheme.dark.instructions.headingColor = UIColor.white\n
"},{"location":"Themes/#home","title":"Home","text":"

The home property can be used to customize properties related to the Storyteller Home component.

Property Default Value Data Type Description home.headerTitle.font nil StorytellerFontProvider The only font that can vary from theme.font, defines the font for the heading home.headerTitle.textSize 22 CGFloat Size of the title in section home.headerTitle.lineHeight 28 CGFloat The line height of the title on in section home.headerTitle.textCase default StorytellerTextCasing Sets the text case for buttons throughout the UI. Possible values are upper, lower and default home.headerTitle.textColor nil UIColor Color of heading text in Storyteller Home home.circularTitle.textSize 11 CGFloat Size of the circular title in section home.circularTitle.lineHeight 13 CGFloat The line height of the circular title on in section home.singletonTitle.textSize 22 CGFloat Size of the singleton title in section home.singletonTitle.lineHeight 28 CGFloat The line height of the singleton title in section home.gridTitle.textSize 16 CGFloat Size of the grid title in section home.gridTitle.lineHeight 22 CGFloat The line height of the grid title on in section"},{"location":"Troubleshooting/","title":"Troubleshooting Storyteller on iOS","text":"

Start with what the app can observe. An empty component, a missing analytics event, and an Ad that was not requested may look similar on screen, but they have different owners and next checks.

If you have not yet displayed your first Story row, follow the complete iOS Quickstart Guide first. For Apple TV, use the dedicated tvOS Guide.

"},{"location":"Troubleshooting/#start-with-the-observable-result","title":"Start with the Observable Result","text":"

Record the first unexpected result before changing the integration:

Observable result Check next Expected observation Likely owner Continue with StorytellerSDK cannot be imported, linked, or loaded Confirm the installation method, app target membership, and required Storyteller dependencies. The app builds and launches before Storyteller initialization begins. App dependency setup, or SDK packaging if the documented setup still fails Quickstart installation initialize(...) throws or isInitialized remains false Capture the error, then verify the API key, tenant/environment, and connectivity. A successful call returns without throwing and sets isInitialized to true. App input, tenant/environment, network, or SDK initialization Initialization fails A content load callback reports an error or success == false Inspect the returned error and capture related SDK logs through StorytellerDelegate.log(message:). The callback distinguishes a failed request from an empty successful response. App integration, network, tenant, or SDK request path Content fails to load A list load succeeds with dataCount == 0 Verify the content identifier, publication state, schedule/expiry, targeting inputs, and initialization-time personalization settings. A known available item from the same tenant and effective targeting context produces a positive count. App targeting or privacy configuration, tenant, CMS, or content state Content is missing or empty A list load succeeds with dataCount > 0, but nothing is visible Check the component's constraints or frame and any visibility-affecting configuration. Giving the component a non-zero layout reveals the loaded items. App layout or presentation Content loaded but is not visible A load is requested but no completion callback arrives Confirm initialization completed successfully, the callback recipient is retained, any deferred list identifier remained unchanged, and the request is not blocked. The load reaches a success, empty, or failure callback. App lifecycle or configuration, network, or SDK request path Loading does not complete A delegate, action, or analytics callback does not arrive Identify whether it is a data-load, interaction, or analytics callback, then check its delegate lifetime and tracking gate. Another callback in the same layer establishes whether loading, interaction, or event delivery is affected. App callback setup, privacy configuration, tenant Ads setup, or SDK event delivery Callbacks or analytics events do not arrive Appearance or configuration changes have no effect Check global versus per-component configuration, the active light/dark theme, any supported remote override, and whether the component was reconfigured or reloaded where required. A deliberately visible change appears after the active host and remote precedence layers are established. App or tenant/CMS configuration, or an unsupported SDK customization Appearance or configuration does not change Ads do not appear Establish the configured Ad source, whether an eligible placement was reached, and whether the matching extension or provider made a request. The last observed boundary identifies Storyteller setup, provider delivery, or rendering as the next owner. Tenant Ads strategy, app extension, external provider, inventory, or SDK rendering Ads do not appear

Do not use a visual symptom alone to assign the cause. Keep the callback result, error, and last successful boundary together.

"},{"location":"Troubleshooting/#installation-or-initialization-fails","title":"Installation or Initialization Fails","text":""},{"location":"Troubleshooting/#the-sdk-does-not-build-or-load","title":"The SDK Does Not Build or Load","text":"

Follow the instructions for the installation method you actually use:

The expected result is that the app imports, links, and launches with the SDK before initialize(...) runs. If a documented clean installation fails in a minimal app, capture the package resolution or linker error and get help from Storyteller. See Quickstart installation for the complete setup.

"},{"location":"Troubleshooting/#initialization-fails","title":"Initialization Fails","text":"

Storyteller.shared.initialize(...) is async throws. The clearest integration sequence is to await it and retain the original error before loading content:

  1. Confirm the API key identifies the intended tenant and environment.
  2. Confirm the current device can reach the required network services and that the app's network policy is not blocking the request.
  3. Inspect the error and Storyteller.shared.isInitialized after the call finishes.

Initialization can throw StorytellerError.networkError(Error) for an unsuccessful server response. It can also surface an underlying URL, transport, or response-decoding error, so keep a general error path. After a thrown initialization call, isInitialized remains false; after success, it is true.

If the same key initializes in the intended environment but one component fails later, initialization is no longer the failing boundary. Continue with Content Fails to Load.

"},{"location":"Troubleshooting/#content-is-blank-missing-or-still-loading","title":"Content Is Blank, Missing, or Still Loading","text":"

Observe the component's load callback before changing its layout or content identifiers:

See Storyteller Delegates, Storyteller Cards, and Embedded Clips for the callback used by each surface.

"},{"location":"Troubleshooting/#content-fails-to-load","title":"Content Fails to Load","text":"

An error or success == false means the request did not produce a successful content result. It is not the same as a successful response containing no available items.

  1. Record the returned error and whether initialization had already succeeded.
  2. Capture Storyteller SDK logs through StorytellerDelegate.log(message:) on the strongly retained object assigned to Storyteller.shared.delegate. Reproduce the failure and look for the request URL, transport error, or response-parsing error that corresponds to the callback. SDK request URLs can include a hashed user ID when enableRemoteViewingStore is enabled, even when personalization is disabled; they can also include custom-attribute values when personalization is enabled. Redact those values before forwarding logs to a third-party service or sharing them.
  3. Confirm the category or collection identifier was copied from the same Storyteller tenant as the API key. When the app has separate development and production configurations, check that the key and identifier came from the same configuration.

If initialization also fails, return to Initialization Fails. If initialization succeeds and the same request repeatedly fails with valid inputs and connectivity, retain the error and request details and get help from Storyteller.

"},{"location":"Troubleshooting/#content-is-missing-or-empty","title":"Content Is Missing or Empty","text":"

For lists, success == true, no error, and dataCount == 0 establishes that the request completed but returned no items available to this component and targeting context.

Check:

The expected control is a known, currently available item for the same targeting inputs and environment. If that appears, the original result belongs to content or targeting configuration rather than layout. See Working with Users for external IDs and targeting inputs, Privacy and Tracking for initialization-time personalization settings, and Storyteller List Views for list identifiers and configuration.

"},{"location":"Troubleshooting/#content-loaded-but-is-not-visible","title":"Content Loaded but Is Not Visible","text":"

For lists, success == true with dataCount > 0 establishes that content loaded. Diagnose presentation next:

The expected result is that the already loaded items become visible without changing the content identifier. Start from the working layouts in the iOS Quickstart Guide, then move to Storyteller List Views for advanced layouts.

"},{"location":"Troubleshooting/#loading-does-not-complete","title":"Loading Does Not Complete","text":"

Story and Clips lists and Cards can defer a load requested before initialization. This is a safeguard, not the recommended integration sequence; await initialization explicitly. A deferred Story or Clips list reload continues only when its list identifier remains unchanged while it waits. Cards wait for initialization without that identifier check.

If the app requests a load but no completion arrives:

  1. Confirm initialize(...) eventually completed successfully. If an attempt throws, the deferred load remains pending and can continue after a later successful retry.
  2. For a Story or Clips list requested before initialization, confirm its identifier did not change while waiting. If it changed, the SDK abandons that deferred reload before onDataLoadStarted() or onDataLoadComplete(...); after initialization succeeds and the deferred attempt unwinds, request a new reload with the current identifier.
  3. Do not issue another Story or Clips list reload while an earlier reload is in progress, including while it waits for initialization. The later call is ignored and does not produce its own onDataLoadStarted() or onDataLoadComplete(...); wait for the earlier attempt to finish or unwind before retrying.
  4. Assign the delegate or action before starting the load and keep any weak delegate strongly referenced by app-owned state.
  5. Confirm the device remains online and use the SDK log callback and network diagnostics to inspect whether a request starts or stalls.
  6. Reduce the integration to one known content identifier and one component.

The expected result is a terminal success, empty, or failure callback. If no request starts, focus on app lifecycle and configuration. If a request starts but never finishes under repeatable network conditions, capture the last observed request boundary and get help from Storyteller.

"},{"location":"Troubleshooting/#callbacks-or-analytics-events-do-not-arrive","title":"Callbacks or Analytics Events Do Not Arrive","text":"

First identify the callback layer:

Callback layer Primary check Expected observation List, Card, or Embedded Clips loading Assign the surface's delegate or action before loading; strongly retain weak delegates. A load-start or completion result arrives independently of analytics settings. Player interaction and app navigation Assign and strongly retain Storyteller.shared.delegate; the SDK property is weak. The implemented callback arrives when its corresponding interaction occurs. Analytics through onUserActivityOccurred Set tracking options during initialization and keep enableUserActivityTracking enabled. Supported non-Ad interactions produce user-activity events. Ad analytics through onUserActivityOccurred Also keep enableAdTracking enabled and reach an actual Ad opportunity or interaction. Ad events arrive only when an Ad lifecycle event occurs.

eventTrackingOptions can only be selected during initialization. Reinitialize the SDK to change them. enableUserActivityTracking gates onUserActivityOccurred; disabling enableAdTracking additionally suppresses Ad-related analytics and omits default KVPs and customKvps from supported Google Ad requests.

Tracking options govern analytics delivery; they do not determine whether a content request or provider Ad request is made. Use the callback belonging to the affected surface before changing privacy settings.

See Integrate Analytics, Privacy and Tracking, the Analytics Event Reference, and Storyteller Delegates for the owning contracts.

"},{"location":"Troubleshooting/#appearance-or-configuration-does-not-change","title":"Appearance or Configuration Does Not Change","text":"

Check which configuration should win:

  1. Storyteller.shared.theme is the global fallback theme. Set it early in the app lifecycle.
  2. A theme passed in a list configuration applies to that component instead of the global fallback.
  3. For properties supported by remote appearance settings, a feed- or collection-specific remote value overrides the tenant/global remote value, which overrides the host-supplied light or dark theme. Confirm the active CMS values before treating a host customization as an SDK gap.
  4. The list's uiStyle selects the light or dark theme branch. For a universal customization, configure theme.light, copy it with theme.dark = theme.light, then apply any dark-specific overrides.
  5. After changing list configuration, reconfigure and reload the UIKit view, or update and reload the SwiftUI model, as described in Storyteller List Views.
  6. Test one deliberately visible property on a basic component before combining multiple overrides.

If the change works on the basic component but not the production surface, compare per-component overrides, the active appearance branch, and configuration timing. If the documented property never affects its supported surface in a minimal integration, record the property, surface, and active theme branch as a possible SDK gap.

Use Custom Themes for supported properties and their scopes. The troubleshooting route does not imply that every visual detail is customizable.

"},{"location":"Troubleshooting/#ads-do-not-appear","title":"Ads Do Not Appear","text":"

Ads cross several ownership boundaries. Establish the configured source before debugging the provider:

Then identify the exact placement:

Follow the branch for the configured source and placement:

Configured source Supported placement and next check Storyteller First Party Ads Confirm an eligible Ad is available in the CMS for a fullscreen placement, then observe whether the SDK displays it. First Party Ads do not support Clips bottom banners. GAM or AdMob Ads Confirm the app installed and configured the matching extension, then use the extension and provider diagnostics to establish whether the placement produced a provider request. A Clips bottom banner additionally requires bottomBannerAdUnit. VAST or GAM VAST Ads Confirm the app installed and configured the matching extension, then inspect its diagnostics for a fullscreen placement. These modules do not support Clips bottom banners.

Continue from the last source-specific observation:

  1. If a provider request starts, inspect its diagnostics or error for no-fill, trafficking, creative, consent, bidder, or network failures.
  2. If the CMS or provider makes an eligible Ad available but Storyteller does not display it, capture the Ad source, returned format when applicable, and subsequent SDK events or logs.

Interpret the last successful boundary:

Last observation Next owner to check No eligible First Party Ad is available in the CMS for a fullscreen placement Tenant Ads strategy, cadence, First Party Ad configuration, or content state No Clips bottom-banner request The feed response's showBottomBannerAd value, the presentation's bottomBannerEnabled opt-in, module placement support, or bottomBannerAdUnit No provider request after an eligible extension-backed placement Tenant Ads strategy, cadence, configured source, extension setup, placement support, or SDK routing Provider request returns no-fill or an error External provider setup, inventory, trafficking, consent, bidder, or connectivity CMS or provider makes an Ad available but it cannot be mapped or rendered Returned creative/format compatibility or SDK integration/rendering

Tracking settings are not proof that an Ad was requested or rendered. They control analytics delivery and, for supported provider requests, which targeting values are sent; disabling them can therefore affect a line item's ability to match without directly enabling or disabling an Ad placement.

See Ads for provider setup, placement support, and diagnostics. Provider-specific rewrites and live trafficking checks remain in the provider's own integration workflow.

"},{"location":"Troubleshooting/#get-help-from-storyteller","title":"Get Help from Storyteller","text":"

When the documented next check does not resolve the problem, share as much of the following information as is available through your normal Storyteller support channel:

An SDK defect is more likely when the same supported configuration fails consistently with valid inputs, successful initialization, known available content or a valid provider response, and a minimal reproduction. Identifying the last successful callback or request boundary helps Storyteller distinguish that from an app, tenant, content, or provider problem.

Storyteller API keys and content identifiers can be shared with Storyteller because they identify the tenant and content. SDK request URLs can contain hashed user IDs when enableRemoteViewingStore is enabled, even when personalization is disabled; they can also contain custom-attribute values when personalization is enabled. Redact those values and any other personal data before forwarding or sharing the logs. Do not include access tokens or unredacted provider credentials.

"},{"location":"Users/","title":"Working with Users and User customization","text":"

This page describes how to customize Storyteller's behaviour on a per-user basis.

"},{"location":"Users/#working-with-users","title":"Working with Users","text":"

User IDs can be used for reporting purposes, storing the read status of Clips and Stories, followed categories, user preferences and other features. By default, the Storyteller SDK creates an externalId for users when the SDK is first initialized. externalId is stored until the user uninstalls the app or until the SDK is initialized with a different externalId.

However, if you have a user account system then you may wish to set your own user IDs within the Storyteller SDK.

The externalId should be an identifier that is unique per user and does not change. Therefore, using something like the user's email address is not a good choice for an externalId, as the user may change it at some point in the future. However, using a unique UUID/GUID would be a good choice as it is guaranteed not to change over time. The SDK hashes externalId, externalId isn't stored or sent to the server in the raw form.

"},{"location":"Users/#setting-a-user-id","title":"Setting a User ID","text":"

In order to supply the externalId to the Storyteller SDK, call the following method:

let userInput = StorytellerUserInput(externalId: \"user-id\")\n\nTask {\n    do {\n        try await Storyteller.shared.initialize(apiKey: \"[APIKEY]\", userInput: userInput)\n    } catch {\n        // handle error\n    }\n}\n

apiKey is a required parameter while userInput is optional and its default value is nil. If userInput is nil, the SDK will use a default autogenerated externalId. When calling Storyteller.shared.initialize, if the new userInput value is different from the previous one, all local data related to the previous user will be deleted.

Storyteller.shared.initialize should be called as soon as the value for the externalId is known in your app. Avoid making simultaneous Storyteller.shared.initialize calls, as it might result in unexpected behavior.

Note: StorytellerUserInput(externalId:) is a failable initializer and returns nil if externalId is missing or blank.

"},{"location":"Users/#setting-the-users-locale","title":"Setting the User's Locale","text":"

Use an ISO 639-1 two-letter language code when available, or an ISO 639-2 three-letter language code when needed:

Storyteller.shared.user.setLocale(\"fr\")\n
Storyteller.shared.user.setLocale(\"ace\")\n

The SDK lowercases the supplied value and validates it against Locale.isoLanguageCodes. An invalid code is ignored and leaves the previously stored locale unchanged. If your app needs a diagnostic instead of that silent no-op, validate before calling the SDK:

import Foundation\nimport StorytellerSDK\n\nfunc applyStorytellerLocale(_ locale: String) {\n    let normalizedLocale = locale.lowercased()\n    guard Locale.isoLanguageCodes.contains(normalizedLocale) else {\n        assertionFailure(\"Unsupported Storyteller locale: \\(locale)\")\n        return\n    }\n\n    Storyteller.shared.user.setLocale(normalizedLocale)\n}\n

To clear or reset the locale settings, simply pass nil as the parameter:

Storyteller.shared.user.setLocale(nil)\n
"},{"location":"Users/#changing-users","title":"Changing Users","text":"

If you use login in your app and wish to allow users to logout and log back in as a new user (or proceed as an anonymous user) then when a user logs out you should call initialize again specifying a new externalId. Note that this will reset the local store of user data, for example which Pages or Clips the user has viewed.

"},{"location":"Users/#user-customization","title":"User Customization","text":""},{"location":"Users/#custom-attributes","title":"Custom Attributes","text":"

One of the features of Storyteller is the ability to set custom attributes for requests. These custom attributes can be used to provide additional information about a request, such as the user's location or the device they are using. It can be also used for audience targeting and content personalization. These custom attributes are sent with every request made by the SDK.

"},{"location":"Users/#how-to-use","title":"How to Use","text":""},{"location":"Users/#set-custom-attribute","title":"Set custom attribute","text":"

To set a custom attribute, you can use the setCustomAttribute() method of the Storyteller.shared.user object. This method takes two parameters: the key of the custom attribute and its value. For example, to set a custom attribute for the user's location, you can use the following code:

Storyteller.shared.user.setCustomAttribute(key: \"location\", value: \"New York\")\n

The Showcase app demonstrates both the UI for selecting attributes and the SDK calls that apply them: see the personalization UI in AccountView and the attribute wiring in StorytellerService.addValue and StorytellerService.removeValue.

This will add a custom attribute to all requests made by the user, with the key \"location\" and the value \"New York\". You can set multiple custom attributes by calling setCustomAttribute() multiple times with different keys and values. String type values are allowed.

"},{"location":"Users/#set-custom-attributes","title":"Set custom attributes","text":"

To set multiple custom attributes at once, use the setCustomAttributes() method with a dictionary of string keys and values. Note that this replaces all previously stored custom attributes. For example:

Storyteller.shared.user.setCustomAttributes([\n    \"location\": \"New York\",\n    \"device_type\": \"mobile\"\n])\n
"},{"location":"Users/#remove-custom-attribute","title":"Remove custom attribute","text":"

To remove custom attribute, you can use the removeCustomAttribute() method of the Storyteller.shared.user object. This method takes one parameter: the key of the custom attribute to remove. For example, to remove a custom attribute for the user's location, you can use the following code

Storyteller.shared.user.removeCustomAttribute(key: \"location\")\n
"},{"location":"Users/#followed-categories","title":"Followed Categories","text":"

Storyteller provides a mechanism for managing followed categories associated with clips. Following or unfollowing a category updates the corresponding plus or tick icon in the Clips UI. The SDK supports two following models, one of which is configured in the System Admin settings for your tenant.

"},{"location":"Users/#app-managed-following","title":"App-Managed Following","text":"

Your app manages following state and handles synchronization with your systems. This gives you full control over the following logic and data storage. When interacting with Storyteller, you have the following methods at your disposal:

"},{"location":"Users/#update-followed-categories","title":"Update followed categories","text":"

To add a followed category, a list of them, or to remove a followed category, call one of the below methods by passing the respective category ID(s):

Storyteller.shared.user.addFollowedCategory(\"location\")\nStoryteller.shared.user.addFollowedCategories([\"location\", \"city\", \"country\"])\nStoryteller.shared.user.removeFollowedCategory(\"location\")\nStoryteller.shared.user.removeFollowedCategories([\"location\", \"city\"])\n

When using these methods, the SDK automatically updates the user attributes to reflect the changes in followed categories. This ensures consistency between the followed categories state and user attributes sent with requests.

Use setFollowedCategories(_:) when you have the complete list of categories that should be followed and need the SDK's current followed category state to match that list exactly. This method is asynchronous, so you can wait for the SDK to update local followed category IDs and request personalization attributes before reloading Storyteller content.

Storyteller resolves the supplied IDs before applying the replacement. IDs that are not returned by Storyteller are omitted, while the resolved subset is applied successfully. If none of the supplied IDs resolve, the followed category state is cleared. Request or response-decoding failures still throw an error and leave the previous state unchanged.

let clipsView = StorytellerClipsViewController()\n\nTask {\n    do {\n        try await Storyteller.shared.user.setFollowedCategories([\"city\", \"country\"])\n        clipsView.reloadData()\n    } catch {\n        // handle error\n    }\n}\n
"},{"location":"Users/#react-to-followed-categories-changes-within-the-sdk","title":"React to followed categories changes within the SDK","text":"

Whenever a user follows or unfollow a category from within the SDK's UI (e.g. the Clips Player), the SDK triggers the following delegate method on StorytellerDelegate.categoryFollowActionTaken method, which allows the integrating app to synchronize its state/UI.

See the Showcase handling of follow/unfollow callbacks in StorytellerInstanceDelegate.categoryFollowActionTaken.

"},{"location":"Users/#storyteller-managed-following","title":"Storyteller-Managed Following","text":"

The SDK handles following activity internally and automatically syncs with Storyteller's servers. This simplifies integration by removing the need for custom following logic in your app.

This means that all of the above methods on Storyteller.shared.user are no-ops in this mode. Also the categoryFollowActionTaken is not called.

"},{"location":"Users/#common-methods","title":"Common methods","text":"

To check if a specific category is being followed, use isCategoryFollowed(_:). To retrieve a list of all currently followed categories, read followedCategories.

let isFollowing: Bool = Storyteller.shared.user.isCategoryFollowed(\"location\")\nlet followedCategories: [String] = Storyteller.shared.user.followedCategories\n

To retrieve the backend-backed list of categories the current user can follow, use Storyteller.shared.user.getFollowableCategories(). This async method returns category metadata plus SDK-derived current followed state for each category, which is useful when building a custom followable category management UI.

Each returned category includes a non-optional id, optional name, displayTitle, externalId, type, thumbnailUrl, and placement, plus SDK-derived isFollowed.

Task {\n    do {\n        let followableCategories = try await Storyteller.shared.user.getFollowableCategories()\n\n        for category in followableCategories.categories {\n            print(\"\\(category.name ?? \"Unnamed category\"): \\(category.isFollowed)\")\n        }\n    } catch {\n        // handle error\n    }\n}\n

Use Storyteller.shared.user.followedCategories and Storyteller.shared.user.isCategoryFollowed(_:) when you only need the SDK's current local followed category IDs. Use Storyteller.shared.user.getFollowableCategories() when you need renderable category data from Storyteller's backend with isFollowed derived from the SDK's local followed category state.

"},{"location":"tvOS/","title":"tvOS Guide","text":"

This page covers tvOS integration for Storyteller. Use the iOS guide only for iOS apps.

"},{"location":"tvOS/#quickstart","title":"Quickstart","text":"

Before adding Storyteller to your tvOS app, make sure the app has:

  1. A Storyteller API key for your tenant.
  2. An Xcode installation. We test the current SDK line with Xcode 26.2; earlier Xcode versions may also work, but they are not part of our tested configuration.
  3. A tvOS deployment target of 15.0 or later.

The SDK supports Swift concurrency initialization on tvOS and is included in the same distribution channels as iOS. The iOS Showcase applications have separate build requirements that do not change the tvOS deployment floor.

"},{"location":"tvOS/#prerequisites","title":"Prerequisites","text":""},{"location":"tvOS/#installation","title":"Installation","text":""},{"location":"tvOS/#swift-package-manager","title":"Swift Package Manager","text":"

The SDK can be added as a Swift package dependency.

  1. In Xcode, open File > Add Packages\u2026.
  2. Add https://github.com/getstoryteller/storyteller-sdk-swift-package.
  3. Let the package resolve StorytellerLottie 4.6.0 transitively; do not add upstream Airbnb Lottie separately.
"},{"location":"tvOS/#cocoapods","title":"CocoaPods","text":"

The tvOS SDK can be added with the same CocoaPods source and pod setup used on iOS.

source 'https://github.com/getstoryteller/storyteller-sdk-ios-podspec.git'\nsource 'https://github.com/getstoryteller/storyteller-lottie-ios-podspec.git'\nsource 'https://cdn.cocoapods.org/'\n\nuse_frameworks!\n\ntarget 'MyTVApp' do\n   # Pods for MyTVApp\n   pod 'StorytellerSDK'\nend\n

CocoaPods resolves StorytellerLottie 4.6.0 transitively from the StorytellerLottie spec repository.

"},{"location":"tvOS/#xcframeworks","title":"XCFrameworks","text":"

XCFrameworks from Storyteller releases include tvOS and can be used by tvOS apps when needed.

  1. Download XCFrameworks from the iOS Quickstart Guide.
  2. Download and unzip StorytellerLottie 4.6.0.
  3. Add both StorytellerSDK.xcframework and StorytellerLottie.xcframework to the same tvOS target. Do not add the upstream Airbnb Lottie framework: the SDK imports the StorytellerLottie module.
  4. In the tvOS target's General > Frameworks, Libraries, and Embedded Content section, select Embed & Sign for both XCFrameworks.
"},{"location":"tvOS/#sdk-initialization","title":"SDK Initialization","text":"

Initialize Storyteller before rendering Storyteller rows or opening Player views.

import StorytellerSDK\n\nlet userInput = StorytellerUserInput(externalId: \"user-id\")\n\nTask {\n    do {\n        try await Storyteller.shared.initialize(\n            apiKey: \"[APIKEY]\",\n            userInput: userInput\n        )\n    } catch {\n        print(\"Storyteller init failed: \\(error)\")\n    }\n}\n
"},{"location":"tvOS/#rows-configuration-clips-and-stories","title":"Rows configuration (Clips and Stories)","text":"

Use separate models for Clips and Stories, then render both rows in your view hierarchy.

import StorytellerSDK\nimport SwiftUI\n\nstruct HomeView: View {\n    @State private var clipsModel: StorytellerClipsListModel\n    @State private var storiesModel: StorytellerStoriesListModel\n\n    init() {\n        let theme: StorytellerTheme = {\n            var theme = StorytellerTheme()\n            theme.light.tiles.title.textSize = 20\n            theme.dark = theme.light\n            return theme\n        }()\n\n        _clipsModel = State(\n            initialValue: StorytellerClipsListModel(\n                configuration: StorytellerClipsListConfiguration(collectionId: \"row-paging\", theme: theme)\n            )\n        )\n        _storiesModel = State(\n            initialValue: StorytellerStoriesListModel(\n                configuration: StorytellerStoriesListConfiguration(categories: [\"automation\"], theme: theme)\n            )\n        )\n    }\n\n    var body: some View {\n        ScrollView {\n            VStack(alignment: .leading, spacing: 24) {\n                Text(\"Clips\")\n                StorytellerClipsRow(model: clipsModel)\n                    .frame(height: 400)\n\n                Text(\"Stories\")\n                StorytellerStoriesRow(model: storiesModel)\n                    .frame(height: 400)\n            }\n            .padding(24)\n        }\n    }\n}\n

When the current user changes, reinitialize with the new user and call reloadData() on each model to refresh content.

"},{"location":"tvOS/#programmatic-playback","title":"Programmatic playback","text":"

To open a specific Story programmatically from your app UI:

import SwiftUI\nimport StorytellerSDK\n\nstruct PlaybackActionView: View {\n    var body: some View {\n        Button(\"Open latest Story\") {\n            Task {\n                do {\n                    try await Storyteller.shared.openStory(externalId: \"story-external-id\")\n                } catch {\n                    // handle playback launch error\n                    print(\"Unable to open Story: \\(error)\")\n                }\n            }\n        }\n    }\n}\n
"},{"location":"tvOS/#tvos-specific-behavior","title":"tvOS-Specific Behavior","text":""},{"location":"tvOS/#troubleshooting","title":"Troubleshooting","text":""},{"location":"tvOS/#caveats-and-limitations","title":"Caveats and Limitations","text":""},{"location":"tvOS/#related-pages","title":"Related Pages","text":""}]}