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

For example:

    ...
    override fun getAdsForList(stories: List<ClientStory>, onComplete: (AdResponse) -> 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.

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 used the 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 List<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)
• swipeUp: ClientSwipeUp? - ClientSwipeUp describes the action that will be triggered when user swipes up on ad
• trackingPixels: List<TrackingPixelClientAd> - list of urls which should be triggered when corresponding event happens, defaults to empty list if not set

The ClientSwipeUp object defines which type of action should be triggered when user swipes up on ClientAd. It can be created using following static methods createWebSwipeUp (opens a web browser with url), createInAppSwipeUp (triggers userSwipedUpToApp callback with url) and createStoreSwipeUp (opens Play Store for playStoreId). It has the following properties:

• url: String - in case of createWebSwipeUp the url which should be opened in browser or in case of createInAppSwipeUp the url which should be passed to userSwipedUpToApp callback
• playStoreId: String - in case of createStoreSwipeUp the package id of the app which will be open in Play Store when user swipes up
• swipeUpText: String? - the text which should be shown for the swipe up UI, if it is null then no swipe up 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: 640
• Height: 1138
• Bitrate: 1500 kbps
• MaxBitrate - 1500 kbps
• FrameRate - 30 fps
• Audio: AAC 128 kbps bitrate, 48k sampling