Skip to content

Handle global callbacks#

Set Storyteller.sharedInstance.delegate to handle events from every Storyteller view and player: analytics events, share taps, ad requests, and in-app action links. The delegate is an object typed IStorytellerDelegate. For loading and dismissal events from one row, grid, or Clips player, see Handle view callbacks.

Set the delegate#

Assign an object with the callbacks you need to Storyteller.sharedInstance.delegate. Set it before you call initialize, so that it receives the sdkInitialized event.

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

Warning

Assigning delegate replaces all four global callbacks. A callback you leave out of the new object stops being called, even if an earlier assignment set it. Define every callback in one object, or spread the current delegate into the new one.

const getAdConfig = (adRequestInfo) => {
  // Return { slot, customTargeting, publisherProvidedId }, or null for no ad.
  // See Integrate ads.
  return null;
};

Storyteller.sharedInstance.delegate = {
  ...Storyteller.sharedInstance.delegate,
  getAdConfig,
};

Callbacks#

All callbacks are optional.

onUserActivityOccurred#

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

Called when an analytics event occurs in a Story or Clips player. A view with a context returns that value in data.context. See Analytics context for the supported views, inheritance rules, and data boundary. The SDK calls this callback only while enableUserActivityTracking is on, and sends ad events only while enableAdTracking is also on. See Integrate analytics for the event types.

The Storyteller Web Showcase has an onUserActivityOccurred handler.

onShareButtonTapped#

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

Called when the user taps the share button in a Story or a Clip. Use it to replace the default share behavior. The SDK passes the text, title, and URL it would otherwise share, and pauses the Story or Clip. When your promise resolves, the SDK records a shareSuccess event. When the promise resolves or rejects, the Story or Clip plays again.

If you don't implement this callback, the SDK opens the browser's share sheet with navigator.share. The share button appears only in browsers that support navigator.share, even when you implement this callback. Story Pages that share their media file download it instead and don't call this callback.

The Storyteller Web Showcase shows an onShareButtonTapped override.

getAdConfig#

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

Called when a Story or Clips player needs an ad and your tenant uses Google Ad Manager ads. Return an object with these fields, or null for no ad:

  • slot: the ad unit path to request
  • customTargeting (optional): key-value pairs for ad targeting
  • publisherProvidedId (optional): your publisher provided ID

Story ad requests include story. Clips ad requests include clip, nextClip, and collection, and have no story field. The SDK doesn't export the AdConfig type. See Integrate ads for the full request and response details.

The Storyteller Web Showcase's buildAdConfig shows how to return slots and custom targeting values.

userNavigatedToApp#

userNavigatedToApp?: (url: string) => void;

Called when a user taps an action button in a Story or Clip that links into your app (an inApp action). Route the user to url in your app. If you don't implement this callback, inApp actions open like regular URLs.

Delegate interface#

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;
}

For a full implementation that wires every callback, see the Storyteller Web Showcase's attachStorytellerDelegate.