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:
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.
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 storypages: List<string>
- list of UUIDs which uniquely identify the pages in the storycategories: List<StoryCategory>
- list of categories which have been assigned to the storyA StoryCategory
object has the following properties:
name: String
- a human readable name for the categoryurlName: String
- a url safe name for the categoryexternalIds: List<StoryCategoryExternalId>
: a list of external Ids for the categoryEach StoryCategoryExternalId
has the following properties:
name: String
- the name of the external IDvalue: String
- the value of the external IDThese 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.
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 questionadvertiserName: String?
- the name of the advertiser - used in place of the story title on the Ad PagetrackingUrl: 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 adtrackingPixels: List<TrackingPixelClientAd>
- list of urls which should be triggered when corresponding event happens, defaults to empty list if not setThe 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
callbackplayStoreId: String
- in case of createStoreSwipeUp
the package id of the app which will be open in Play Store when user swipes upswipeUpText: 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 stringThe 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 happenseventType: 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
Any video ads passed to the Storyteller SDK should be encoded according to the following specs: