Storyteller • Documentation • Ads

Supplying Ads to the Storyteller SDK
Client Story Parameters
Ad Response
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

Example:

    ...
    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(ads)
    }

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.

Parameters

ClientStory

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.

AdResponse

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

Additional Methods Forward Arrow

Ads

Table of Contents

Supplying Ads to the Storyteller SDK

Parameters

ClientStory

AdResponse

Ad Encoding