Skip to content

Integrate ads#

Storyteller can show ads in Stories and Clips from two sources:

  • First Party Ads, which you create in the Storyteller CMS. They need no code.
  • Google Ad Manager (GAM) ads. Implement the getAdConfig callback to tell the SDK which ad unit to request and which targeting to send.

Ad Sources#

Storyteller sets which ad source your tenant uses. To change it, contact the Storyteller Delivery Team.

Storyteller First Party Ads#

If your tenant uses Storyteller First Party Ads, you manage them in the Storyteller CMS and don't change your integration code. The SDK loads and shows these ads itself.

Google Ad Manager integration#

The SDK requests these ads from Google Ad Manager. For other ad servers, contact the Storyteller Delivery Team.

Implement the getAdConfig callback on the global delegate (IStorytellerDelegate, see StorytellerDelegate). The SDK calls it each time it needs an ad, and only when your tenant uses Google Ad Manager ads.

Assigning Storyteller.sharedInstance.delegate replaces every global callback. The samples below spread the current delegate to keep your other callbacks.

Storyteller.sharedInstance.delegate = {
  ...Storyteller.sharedInstance.delegate,
  getAdConfig: (adRequestInfo) => {
    // Only Story ad requests have `story`. Clips ad requests have `clip`.
    const customTargeting = adRequestInfo.story
      ? {
          storytellerStoryCategories: adRequestInfo.story.categories.map(({ name }) => name),
        }
      : {
          storytellerClipCategories: adRequestInfo.clip.categories.map(({ name }) => name),
          storytellerNextClipCategories:
            adRequestInfo.nextClip?.categories.map(({ name }) => name) || [],
        };

    return {
      slot: '/30497361/your_ad_unit',
      publisherProvidedId: 'your-publisher-provided-id',
      customTargeting,
    };
  },
};

import * as Storyteller from '@getstoryteller/storyteller-sdk-javascript';
import type {
  StorytellerAdRequestInfo,
  StorytellerStoriesAdRequestInfo,
} from '@getstoryteller/storyteller-sdk-javascript';

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

Storyteller.sharedInstance.delegate = {
  ...Storyteller.sharedInstance.delegate,
  getAdConfig: (adRequestInfo) => {
    const customTargeting: Record<string, string[]> = isStoryAd(adRequestInfo)
      ? {
          storytellerStoryCategories: adRequestInfo.story.categories.map(({ name }) => name),
        }
      : {
          storytellerClipCategories: adRequestInfo.clip.categories.map(({ name }) => name),
          storytellerNextClipCategories:
            adRequestInfo.nextClip?.categories.map(({ name }) => name) || [],
        };

    return {
      slot: '/30497361/your_ad_unit',
      publisherProvidedId: 'your-publisher-provided-id',
      customTargeting,
    };
  },
};

The Storyteller Web Showcase builds the getAdConfig result in buildAdConfig with the ad slot and custom targeting values.

Return value#

getAdConfig returns an object with the fields below, or null to request no ad. An object without slot also requests no ad. Return the object directly: the SDK doesn't wait for a promise. For the full type, see getAdConfig in the callback reference.

Field Description
slot Required. The ID of your GAM ad unit, in the form /[NETWORK_CODE]/[UNIT_CODE]. The ad unit must serve 1x1 ads. For details, see Google's guides to custom ad creative and programmatic ad creative.
publisherProvidedId Optional Publisher Provided ID (PPID) for Google Ad Manager. This value is sent as GAM's PPID field, not as a custom targeting KVP. The SDK trims whitespace, omits empty values, and omits this value when ad tracking is disabled.
customTargeting Optional key-value pairs (KVPs) that the SDK sends to GAM for ad targeting. The SDK adds the default targeting values, and a key you return replaces the default key with the same name. The SDK doesn't copy KVPs that the rest of your page sets.

Values such as ddid, isLoggedIn, gdpr, us_privacy, gpp, gpp_sid, and other app-owned ad/privacy KVPs should be supplied through customTargeting. PPID should be supplied through publisherProvidedId.

customTargeting values can be strings or arrays of strings. Use arrays for multi-value GAM KVPs so each value is passed as a distinct targeting value.

When ad tracking is off (enableAdTracking: false), the SDK omits the default targeting and publisherProvidedId. It still sends the customTargeting you return.

Default Targeting#

By default, the Storyteller SDK sets the following customTargeting values:

Stories#

Property Name Property Type Description Example value
stCurrentCategory string The external ID of the current Story Category. "top-stories"
stPlacement string The placement code of the current Story Category. web-top-stories
stCategories string[] External IDs of the current Story Categories. ["top-stories", "web-stories"]

Clips#

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

AdRequestInfo#

The StorytellerAdRequestInfo object passed to this callback can be one of two types, depending on whether the user is 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 details about the Story or Clip the user is viewing. Pass them to your ad server to target the ad. Only Story ad requests have story, so check for it before you read it, as the samples above do.

Stories#

Story ad requests contain:

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#

Clips ad requests contain:

Property Description
collection: string A string which uniquely identifies the Collection that the Clips are assigned to
clip: ItemInfo Metadata about the Clip after which the requested Ad will be placed
nextClip: ItemInfo Optional. Metadata about the Clip that follows the Ad, when there is one

The ItemInfo object has the following properties:

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

The ClipCategory object has the following properties:

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