Ads#

Table of Contents#

Ad Sources
Storyteller First Party Ads
Storyteller Ad Manager Integration
1. Default Targeting
  1. Stories
  2. Clips
2. Customizing the Ad Request
  1. Stories
  2. Clips

Ad Sources#

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.

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 Ad Manager Integration#

Multiple 3rd party ad servers are supported, with Google Ad Manager being the default. Reach out to the Storyteller Delivery Team for more information about configuration for other ad servers

To supply ad configuration to the Storyteller SDK, implement the getAdConfig callback on the StorytellerDelegate.

For example:

JavaScriptTypeScript

Storyteller.delegate = {
  getAdConfig: (adRequestInfo) => {
    return {
      slot: '/30497361/your_ad_unit',
      customTargeting: {
        storytellerStoryCategories: adRequestInfo.story.categories.map(({ name }) => name).join(','),
      },
    };
  },
};

Storyteller.delegate = {
  getAdConfig: (adRequestInfo) => {
    const customTargeting = isStoryAd(adRequestInfo)
      ? { storytellerStoryCategories: adRequestInfo.story.categories.map(({ name }) => name).join(',') }
      : { storytellerClipCategories: adRequestInfo.clip.categories.map(({ name }) => name).join(','), storytellerNextClipCategories: adRequestInfo.nextClip?.categories.map(({ name }) => name).join(',') || '' };

    return {
      slot: '/30497361/your_ad_unit',
      customTargeting,
    };
  },
};

function isStoryAd(adRequestInfo: StorytellerAdRequestInfo): adRequestInfo is StorytellerStoriesAdRequestInfo {
  return 'story' in adRequestInfo;
}

You will need to supply the following parameters:

Parameter Name	Description
`slot`	This is the ID of your GAM ad unit in the form `/[NETWORK_CODE]/[UNIT_CODE]`. This Ad Unit must be set to serve 1x1 ads. There is more information available here from Google regarding custom ad creative and programmatic ad creative
`customTargeting`	The Storyteller SDK enables the ability to pass KVPs to GAM to allow targeting of Ads. If you have parameters which you need to target by, these should be passed here. Note that the SDK will not, by default, inherit any KVPs being set in the rest of your app.

Default Targeting#

By default, the Storyteller SDK will set the following customTargeting values:

Stories#

Property Name	Property Type	Description	Example value
`stCurrentCategory`	`string`	The name of the current Story Category.	"Top Stories"
`stPlacement`	`string`	The placement `code` of the current Story Category.	`web-top-stories`
`stCategories`	`string`	Comma-separated external IDs of the current Story Categories.	"top-stories,web-stories,live-stories"

Clips#

Property Name	Property Type	Description	Example value
`stCollection`	`string`	The ID of the current Clip Collection.	`live-clips`
`stClipCategories`	`string`	Comma-separated external IDs of the current Clip Categories.	"top-clips,web-clips,live-clips"
`stNextClipCategories`	`string`	Comma-separated external IDs of the next Clip Categories.	"top-clips,web-clips,live-clips"

AdRequestInfo#

The StorytellerAdRequestInfo object passed to this callback can be one of two types, depending on whether the user is currently viewing Stories or Clips:

export type StorytellerStoriesAdRequestInfo = {
  placement: string;
  categories: string[];
  story: {
    categories: CategoryDetail[];
  };
};

export type StorytellerClipsAdRequestInfo = {
  collection: string;
  clip: {
    categories: ClipCategory[];
  };
  nextClip?: {
    categories: ClipCategory[];
  };
};

This object contains metadata about the Story or Clip the user is currently viewing. This can be passed to the Ad Server you are requesting the Ad from in order to allow custom targeting.

Stories#

For Stories, the following information is available

Property	Description
`placement: String`	A string which uniquely identifies the placement in which the Story is being shown
`categories: [String]`	A list of Category String IDs which have been assigned to the stories list. Note that every category in this list will appear on every story in the list. This list can be useful to know in which context the user is currently viewing Stories.
`story: ItemInfo`	Metadata about the Story after which the requested Ad will be placed

The ItemInfo object has the following properties:

Property	Description
`categories: [CategoryDetail]`	An array of Categories which have been assigned to the Story

The CategoryDetail object has the following properties:

Property	Description
`name: String`	A human readable name for the Category
`externalId: String`	The external ID of the Category, set in the Storyteller CMS

Clips#

For Clips, the following information is available:

Property	Description
`collection: String`	A string which uniquely identifies the collection that the clips are assigned to
`clips: ItemInfo`	Metadata about the Clip after which the requested Ad will be placed

The ItemInfo object has the following properties:

Property	Description
`categories: [ClipCategory]`	An array of Categories which have been assigned to the Clip.

The Category object has the following properties:

Property	Description
`name: String`	A human readable name for the Category
`externalId: String`	The string ID for the Category