Table of Contents

  1. Supplying Ads to the Storyteller SDK
  2. Client Story Parameters
  3. Ad Response
  4. Ad Encoding

The Storyteller SDK makes it possible to render ads between the Stories in your app. The behavior of the SDK regarding ads can be configured in the CMS for your tenant.

There are 3 possible sources of ads:

  • No Ads - The SDK will not request or render ads between Stories
  • Storyteller - The SDK will request Ads from the Storyteller API. These ads can be configured in the Storyteller CMS for your tenant and support tracking pixels for 3rd party verification.
  • Integrating App - The app into which you are integrating the Storyteller SDK is responsible for requesting ads and providing information about them to the Storyteller SDK.

This section describes how to render ads between Stories if the integrating app is responsible for providing ads to the Storyteller SDK.

Supplying Ads to the Storyteller SDK

To supply ads to the Storyteller SDK, implement the getAdsForList callback on the StorytellerDelegate.

The stories parameter specifies which Stories the SDK is currently preparing ads for. The SDK will request ads on demand for the current, previous and next Story. This can be done in batches of Stories up 3. If a Story has been requested once, then it will not be requested again.

Expected behavior:

  • There are 5 Stories (1, 2, 3, 4, 5)
  • Open Story 2
  • SDK will request ads for Stories (1, 2, 3)
  • Navigate to Story 3
  • SDK will request ad for Story 4
  • Navigate to Story 4
  • SDK will request ad for Story 5
  • Navigate to Story 3
  • SDK will not make any request


    override fun getAdsForList(stories: List<ClientStory>, onComplete: (AdResponse) -> Unit, onError: () -> Unit) {
        // Action to get some ads
        val ads = getMyAds()
        // Provide the ads to the SDK

onComplete should be called as soon as ads are available. The SDK expects a map of Story IDs and ad associated with them. Each ad will be inserted after a Story specified by the ID.

Note that if you implement this method but your tenant is configured to supply ads via another method (or set to "No Ads"), then the results of this callback will be ignored.



The ClientStory object passed to this callback contains the following properties which you may wish to include in the request to your ads provider:

Property Description
id: String A UUID which uniquely identifies the Story.
pages: List<string> A list of UUIDs which uniquely identify the Pages in the Story
categories: List<StoryCategory> A list of Categories which have been assigned to the Story

A StoryCategory object has the following properties:

Property Description
name: String A human readable name for the Category
urlName: String A URL safe name for the Category
externalIds: List<StoryCategoryExternalId> A list of external IDs for the Category

Each StoryCategoryExternalId has the following properties:

  • name: String - the name of the external ID
  • value: String - the value of the external ID

These external IDs can be identified by name and are used to pass the Category information to elsewhere in your app. For example, you may wish to include a categoryId on a request to your ad server and a personalizationId on a request to your personalization endpoints.


The AdResponse object which the SDK expects to be returned is a typealias for Map<String, ClientAd?>.

Ads will be rendered in the order in which they are passed to this list. If a null value is passed for a slot, no ad will be shown in that position.

ClientAd objects can be created using two static methods depending on if it is a video or image ad: ClientAd.createVideoAd(...) or ClientAd.createImageAd(..).

These functions accept following arguments:

Property Description
image: String The image to display for the ad. Only available in createImageAd.
id: String A unique ID for the Ad in question.
advertiserName: String? The name of the advertiser - used in place of the Story Title on the Ad Page.
video: String The video to display for the ad. Only available in createVideoAd.
trackingPixels: List<TrackingPixelClientAd> A list of URLs which should be triggered when the corresponding event happens. Defaults to empty list if not set.
clientAction: Client Action? This describes the action that will be triggered when a user taps on the action button on an ad.
trackingUrl: String? A 1x1 tracking pixel which will be triggered when an is loaded (that is, at the same time as the Opened Ad analytics event).

The ClientAction object defines which type of action should be triggered when user clicks on the action button on ClientAd. It can be created using following static methods createWebAction (opens a web browser with url), createInAppAction (triggers userNavigatedToApp callback with url) and createStoreAction (opens Play Store for playStoreId). It has the following properties:

Property Description
playStoreId: String In the case of createStoreAction, the package ID of the app which will be open in the Play Store when a user clicks on the action button.
url: String In the case of createWebAction, the URL which should be opened in browser. In the case of createInAppAction, the URL which should be passed to the userNavigatedToApp callback.
text: String? The text which should be shown for the action button. If it is null or empty, then no action UI will be shown and it defaults to an empty string.

The TrackingPixelClientAd object which represents tracking pixel for an ad. It contains information about the URL which should be triggered when corresponding event happens. It has the following properties:

Property Description
url: String The URL which will be triggered when the event below happens
eventType: UserActivity.EventType A user activity event which triggers tracking pixel URL: OPENED_AD, AD_PAGE_START, AD_PAGE_FIRST_QUARTER, AD_PAGE_MID, AD_PAGE_THIRD, AD_PAGE_COMPLETE, PAUSED_AD_PAGE, RESUMED_AD_PAGE

Ad Encoding

Any video ads passed to the Storyteller SDK should be encoded according to the following specs:

  • Width: 540
  • Height: 960
  • Bitrate: 1500 kbps
  • MaxBitrate - 1500 kbps
  • FrameRate - 60 fps
  • Audio: AAC 128 kbps bitrate, 48k sampling
Forward Arrow