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

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: [string] - array of page IDs for the story
• categories: [Category] - array of categories which have been assigned to the story

The Category object has the following properties:

• name: string - a human readable name for the category
• urlName: string - a url safe name for the category
• externalIds: [ExternalId] - a list of external Ids for the category

Each ExternalId 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 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.

ClientAd

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.

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