Skip to content

Callbacks#

The SDK reports events and asks for ad settings through delegate objects. You set one global delegate on Storyteller.sharedInstance, and you can set a delegate on each view. Every callback is optional. For setup steps, see Handle delegates and callbacks.

Delegate interfaces#

The SDK defines three delegate interfaces:

Interface Set it on Callbacks
IStorytellerDelegate Storyteller.sharedInstance.delegate onUserActivityOccurred, onShareButtonTapped, getAdConfig, userNavigatedToApp
IListViewDelegate The delegate of a Stories or Clips row or grid onDataLoadStarted, onDataLoadComplete, onPlayerDismissed
IStorytellerClipsPlayerDelegate The delegate of a StorytellerClipsPlayerView or StorytellerEmbeddedClipsPlayerView The IListViewDelegate callbacks, plus onTopLevelBackTapped

Assigning a delegate object replaces the previous one, so include every callback that you need in each assignment.

IStorytellerDelegate#

interface IStorytellerDelegate {
  onUserActivityOccurred?: (
    type: ActivityType,
    data: UserActivityData
  ) => void;
  onShareButtonTapped?: (
    text: string,
    title: string,
    url: string
  ) => Promise<void>;
  getAdConfig?: (
    adRequestInfo: StorytellerAdRequestInfo
  ) => AdConfig | null;
  userNavigatedToApp?: (url: string) => void;
}

The global delegate handles events from every Story and Clip player on the page.

Storyteller.sharedInstance.delegate = {
  onUserActivityOccurred: (type, data) => {
    console.log(type, data.context);
  },
};

onUserActivityOccurred#

onUserActivityOccurred?: (type: ActivityType, data: UserActivityData) => void

Called for each analytics event. The SDK ignores the return value.

Parameter Type Description
type ActivityType The event name, such as openedStory
data UserActivityData The event properties. Each event page lists the properties that it sets

The privacy options control the callback:

  • The callback runs only when enableUserActivityTracking is true
  • Ad events reach the callback only when enableAdTracking is true
  • When enableFullVideoAnalytics is false, the SDK sets storyId, storyTitle, storyDisplayTitle, pageId, pageTitle, clipId, and clipTitle to null

data.context holds the view's configuration.context, unless that value is undefined. Assign the delegate before initialize to receive the sdkInitialized event.

onShareButtonTapped#

onShareButtonTapped?: (
  text: string,
  title: string,
  url: string
) => Promise<void>

Called when a user taps the link share button in the Story player or the Clips player. Implement it to replace the browser share sheet.

Parameter Type Description
text string Share text. For a Clip, the Clip description
title string Share title. For a Story, the Story title. For a Clip, the Clip description
url string The link to share

The returned promise controls what happens next:

  • Resolves: the SDK records the shareSuccess event and resumes playback
  • Rejects: the SDK resumes playback without a shareSuccess event
  • Missing or throws: the SDK calls navigator.share instead

The player pauses while the share runs.

getAdConfig#

getAdConfig?: (adRequestInfo: StorytellerAdRequestInfo) => AdConfig | null

Called before an ad request when your tenant uses a third-party ad server, such as Google Ad Manager. With Storyteller first-party ads, the SDK does not call it.

Parameter Type Description
adRequestInfo StorytellerAdRequestInfo The Story or Clip context of the ad slot

Return an ad configuration, or null to send no ad request. The SDK uses this shape of the declared AdConfig union:

interface IntegratingAppAdConfig {
  type?: 'doubleclick';
  slot: string;
  customTargeting?: AdTargeting;
  publisherProvidedId?: string | null;
}

interface AdTargeting {
  [index: string]: string | string[];
}
Field Type Required Description
slot string Yes Google Ad Manager ad unit, in the form /[NETWORK_CODE]/[UNIT_CODE]. A configuration without slot is not valid
customTargeting AdTargeting No Key-value pairs for the ad request. Values are strings or arrays of strings
publisherProvidedId string or null No Publisher Provided ID (PPID). The SDK trims whitespace and omits an empty value
type 'doubleclick' No Ad server type

The SDK adds its default targeting keys and lets your customTargeting values override them. When enableAdTracking is false, the SDK omits its default keys and publisherProvidedId, and still sends your customTargeting.

AdConfig and AdTargeting are not exported by name. The declared AdConfig union also includes { type: 'custom'; remoteUrl: string }, which the SDK uses for Storyteller first-party ads. The SDK ignores that shape when your delegate returns it.

userNavigatedToApp#

userNavigatedToApp?: (url: string) => void

Called when a user taps an in-app action on a Story Page or a Clip. Implement it to route the URL inside your application. Without this callback, in-app actions open like regular URLs.

Parameter Type Description
url string The action URL set in the Storyteller CMS

IListViewDelegate#

interface IListViewDelegate {
  onDataLoadStarted?: () => void;
  onDataLoadComplete?: (
    success: boolean,
    error: Error | null,
    dataCount: number
  ) => void;
  onPlayerDismissed?: () => void;
}

A view delegate handles events from one view. The SDK fills callbacks that you leave out with no-op functions.

const storyRow = new Storyteller.StorytellerStoriesRowView('stories-row-id');

storyRow.delegate = {
  onDataLoadStarted: () => console.log('Loading Stories'),
  onDataLoadComplete: (success, error, dataCount) => {
    console.log(success, error, dataCount);
  },
};

onDataLoadStarted#

onDataLoadStarted?: () => void

Called each time the view starts loading its content. This happens after the constructor, after a source change (categories, collection, clipId, or externalId), on reloadData, and when a Clips view refreshes after its player closes.

onDataLoadComplete#

onDataLoadComplete?: (
  success: boolean,
  error: Error | null,
  dataCount: number
) => void

Called when the content request finishes.

Parameter Type Description
success boolean true when the request succeeded
error Error or null null on success. On failure, the request error. When the failure is not an Error, the SDK passes an Error with the message Network Error
dataCount number Stories views: the number of Stories loaded. Clips views: the number of Clips in the first page. Single-Clip players: 1. 0 on failure

Later Clips pages load as users reach the end of the content, and they do not call this callback. See Clips paging.

onPlayerDismissed#

onPlayerDismissed?: () => void

Called when the Story or Clip player that the view opened is dismissed. A tap on the Clips player top-level back button calls onTopLevelBackTapped instead.

IStorytellerClipsPlayerDelegate#

interface IStorytellerClipsPlayerDelegate extends IListViewDelegate {
  onTopLevelBackTapped?: () => void;
}

The delegate of StorytellerClipsPlayerView and StorytellerEmbeddedClipsPlayerView. It supports the IListViewDelegate callbacks.

onTopLevelBackTapped#

onTopLevelBackTapped?: () => void

Called when a user taps the top-level back button. The button shows only when topLevelBackButtonEnabled is true. Without this callback, the SDK calls window.history.back().

clipPlayer.topLevelBackButtonEnabled = true;
clipPlayer.delegate = {
  onTopLevelBackTapped: () => {
    window.history.back();
  },
};