Ads#

Table of Contents#

Introduction
Storyteller First Party Ads
Storyteller GAM SDK
Bottom Banner Ads
- StorytellerAdRequestInfo

Introduction#

The Storyteller SDK supports displaying ads that can be created in the Storyteller CMS (First Party Ads), as well as Ads from Google Ad Manager via an SDK extension developed by Storyteller and Ads from other sources via custom implementation provided by the integrator.

Which source of ads is used can be configured on your behalf by a member of the Storyteller Delivery Team.

Storyteller First Party Ads#

If your tenant is configured to use Storyteller First Party Ads, which can be managed in the Storyteller CMS, then no changes to the Storyteller integration code are necessary. The Ads code is managed entirely within the Storyteller SDK.

Storyteller GAM SDK#

To use Ads from Google Ad Manager in Storyteller, first reach out to your Storyteller contact and they will assist you with setting up Google Ad Manager to traffic ads to Storyteller.

You will then need to use the Storyteller Google Ad Manager SDK extension to fetch the ads from Google Ad Manager.

To use this extension, first install it using Gradle. Ensure you have the following Maven repository added to your settings.gradle:

maven {
  url = uri("https://storyteller.mycloudrepo.io/public/repositories/storyteller-sdk")
}

Then add the following reference to your version catalog file:

storyteller-ads = { module = "Storyteller:ads", version.ref = "storyteller" }

And finally reference this in your build.gradle:

implementation(libs.storyteller.ads)

Basic Setup#

Now initialize the extension as follows:

import com.storyteller.modules.ads.StorytellerGamModule
import com.storyteller.domain.ads.entities.CustomNativeTemplateIds

val storytellerGamModule = StorytellerGamModule.getInstance(applicationContext).apply {
  init(
    adUnit = { storytellerAdRequestInfo: StorytellerAdRequestInfo -> "/33813572/storyteller" },
  )
}
fun initializeStoryteller() {
  Storyteller.modules = listOf(storytellerGamModule)
  //initialize code
}

You will need to supply the following parameters:

Parameter Name	Description
`{ storytellerAdRequestInfo -> adUnitId` }	The lambda which returns desired `adUnitId`. This can be used for dynamic `adUnitId` changes depending on `storytellerAdRequestInfo` content. If you do not need dynamic adUnit changes simply put the static ad unit as a return value.
`bottomBannerAdUnit`	Optional lambda that returns the Ad Unit ID used specifically for the Clips bottom banner placement. Leave this `null` if you don't plan to serve Clips bottom banner ads.

Then pass the newly created instance of the extension to the modules property on the Storyteller instance:

Storyteller.modules = listOf(storytellerGamModule)

Showcase examples#

Setup with the dynamic Ad Unit changes#

Example for dynamic Ad Unit changes when we want to use different adUnit for Stories and Clips:

import com.storyteller.modules.ads.StorytellerGamModule
import com.storyteller.domain.ads.entities.CustomNativeTemplateIds

val storytellerGamModule = StorytellerGamModule.getInstance(applicationContext).apply {
  init(
    adUnit = { storytellerAdRequestInfo: StorytellerAdRequestInfo ->
      when (storytellerAdRequestInfo) {
        is StorytellerAdRequestInfo.StoriesAdRequestInfo -> "/33813572/storyteller/stories"
        else -> "/33813572/storyteller/clips"
      }
    },
  )
}

fun initializeStoryteller() {
  Storyteller.modules = listOf(storytellerGamModule)
  //initialize code
}

Setup with the additional parameters#

You can also supply optional parameters templateIds and keyValuePairs if needed:

import com.storyteller.modules.ads.StorytellerGamModule
import com.storyteller.domain.ads.entities.StorytellerCustomNativeTemplateIds

val storytellerGamModule = StorytellerGamModule.getInstance(applicationContext).apply {
  init(
    adUnit = { storytellerAdRequestInfo: StorytellerAdRequestInfo ->
      when (storytellerAdRequestInfo) {
        is StorytellerAdRequestInfo.StoriesAdRequestInfo -> "/33813572/storyteller/stories"
        else -> "/33813572/storyteller/clips"
      }
    },
    templateIds = StorytellerCustomNativeTemplateIds("12102683", "12269089"),
    keyValuePairs = { emptyMap() },
  )
}

fun initializeStoryteller() {
  Storyteller.modules = listOf(storytellerGamModule)
  //initialize code
}

Parameter Name Description

templateIds If you have worked with the Storyteller Delivery team to setup Custom Native Ads, you will need to supply their IDs here. If you are only using Stories (but not Clips) it is only necessary to supply one property of this struct.

keyValuePairs A function that is called each time we request a new ad. The Storyteller GAM SDK passes a default set of KVPs to GAM to allow targeting based on the content of the Stories/Clips the user is viewing. If you have any additional parameters that you need to be able to target by, these should be passed here. By default, Storytelles always includes the following KVPs: stApiKey(current API key), stCollection(the identifier of the clips collection where the ad will be displayed), stClipCategories(list of categories for the current clip associated with the item for ad targeting), stNextClipCategories(list of categories for the next clip associated with the item for ad targeting), stAdIndex(count of the Ad position from the start of the stCollection).

The Clips Player supports bottom banner ads rendered as standard banner views displayed below the video content. When using the GAM module, supply bottomBannerAdUnit in the init() method to fetch inline adaptive banners for the Clips bottom banner placement. Only 300x50 and 320x50 ad sizes are supported.

Example setup with bottom banner ads:

val storytellerGamModule = StorytellerGamModule.getInstance(applicationContext).apply {
  init(
    adUnit = { storytellerAdRequestInfo: StorytellerAdRequestInfo -> "/your/ad_unit_id" },
    bottomBannerAdUnit = { storytellerAdRequestInfo: StorytellerAdRequestInfo -> "/your/bottom_banner_ad_unit_id" },
  )
}

StorytellerAdRequestInfo#

The StorytellerAdRequestInfo sealed class has two subclasses:

ClipsAdRequestInfo

Used when an Ad is requested for display in a Clips Player. The properties include:

collection - The identifier of the clips collection where the ad will be displayed
nextClipCategories - List of categories for the next clip associated with the item for ad targeting
adIndex - Count of the Ad position from the start of the Collection
itemInfo - Metadata about the item context for ad targeting

StoriesAdRequestInfo

Used when an Ad is requested for display in a Stories Player. The properties include:

placement - The identifier of the stories placement where the ad will be displayed
categories - List of category identifiers for ad targeting and filtering
adIndex - Count of the Ad position from the start of the Collection
itemInfo - Metadata about the item context for ad targeting

ItemInfo#

Each request class includes an ItemInfo object that contains:

categories - List of categories associated with the item for ad targeting

Non Skippable Ads#

Our Player can enforce a period of time during which ads can't be skipped. When enabled, user interactions that would skip a Story or Clip Ad won't be allowed for that duration. This feature can be configured in the CMS.