Ads

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. The mechanism for doing so is described below.

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:

• id: String - a UUID which uniquely identifies the Story
• pages: List<string> - list of UUIDs which uniquely identify the Pages in the Story
• categories: List<StoryCategory> - list of Categories which have been assigned to the Story

A StoryCategory object has the following properties:

• 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:

• image: String - the image to display for the ad. Only available in createImageAd
• video: String - the video to display for the ad. Only available in createVideoAd
• 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
• 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)
• clientAction: ClientAction? - ClientAction describes the action that will be triggered when user tap on the action button on ad
• trackingPixels: List<TrackingPixelClientAd> - list of URLs which should be triggered when corresponding event happens, defaults to empty list if not set

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:

• url: String - in case of createWebAction the URL which should be opened in browser or in case of createInAppAction the URL which should be passed to userNavigatedToApp callback
• playStoreId: String - in case of createStoreAction the package ID of the app which will be open in Play Store when user clicks on the action button
• text: String? - the text which should be shown for the action button, if it is null or empty or then no action UI will be shown, 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:

• url: String - URL which will be triggered when event below happens
• eventType: UserActivity.EventType - 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 - 30 fps
• Audio: AAC 128 kbps bitrate, 48k sampling