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
prop on the StorytellerListComponent.
For example:
private ref?: Storyteller;
_onGetAdsForList = (stories: [ClientStory]) => {
console.log(`GetAdsForRow\n` + `stories: ${stories}`);
Storyteller.setAdsResult([adExample], null); }
};
...
<StorytellerRowView
ref={(ref) => {
if (ref) this.ref = ref;
}}
onGetAdsForList={this._onGetAdsForList}
...
/>
setAdsResult
should be called as soon as ads are available. The error
parameter should be given if it was not possible to fetch ads and will result in no ads being displayed until the callback is called again.
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.
Ads will be rendered in the order in which they are passed to this list. If a null value is passed for a slot in this array, no ad will be shown in that position.
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: [string]
- array of page IDs for the storycategories: [Category]
- array of categories which have been assigned to the storyThe Category
object has the following properties:
name: string
- a human readable name for the categoryurlName: string
- a url safe name for the categoryexternalIds: [ExternalId]
- a list of external Ids for the categoryEach ExternalId
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 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 ClientAd
object which the SDK expects to be returned contains the following properties:
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.image?: string
- the image to display for the ad.video?: string
- the video to display for the ad. Note that if both an image and a video are supplied, then the video
is preferred.playcardUrl?: string
- the image to display as a placeholder if a video asset is still loading. It could be set, for example, as the first frame of the video. This property is unused for image ads.duration?: number
- how long the ad should be displayed for. Note that for videos, this parameter will be ignored and the ad will be displayed for the length of the video. If this parameter is null
for an image
page, it will default to 5s.trackingPixels: [ClientTrackingPixel]
- an array of 1x1 ad tracking pixels which will be triggered when an ad is loaded and throughout its playback - properties detailed below.swipeUp?: ClientAdSwipeUp
- optional property which describes what should happen when a user swipes up on the ad. If no swipe up action is required, pass null
for this property.The ClientTrackingPixel
object contains the following properties:
eventType: string
- string describing the type of the tracking pixel - possible values are "impression", "videoStart", "firstQuartile", "midpoint", "thirdQuartile", "videoComplete", "videoPause", "videoResume".url: string
- the tracking pixel url.The ClientAdSwipeUp
object contains the following properties:
type: string
- enumeration describing the destination of the swipe up - possible values are: web
(will direct the user to an in-app browser); inApp
(will direct the user to a location within the integrating app); store
(will direct the user to the App Store)urlOrStoreId: string
- string describing the destination. For web
types, this should be a valid HTTPS URL. For inApp
types, this should be a valid deeplink into the integrating app - when a user swipes up on an ad we will call onUserSwipedUpToApp
on the component and pass this URL for your app to direct the user to the correct destination. For store
types, this should be the URL of the App you wish to link to on the App Store (e.g. https://apps.apple.com/us/app/testflight/id899247664)text?: string
- string describing text on bottom of the Story that suggests available swipe up. Default value is Learn More
.Any video ads passed to the Storyteller SDK should be encoded according to the following specs: