Types and enums

This page lists the enums, data types, theme classes, and server rendering helpers that the SDK exports. Theme properties are covered in Customize themes, and event properties in the analytics event pages.

Enums

Every enum value is a string equal to its member name. In TypeScript, pass the enum member, such as Storyteller.UiStyle.dark. In JavaScript, you can also pass the string, such as 'dark'.

UiStyle

enum UiStyle {
  auto = 'auto',
  light = 'light',
  dark = 'dark',
}

Selects the light or dark theme of a UiTheme. auto follows the system color scheme. Set it with configuration.uiStyle or the data-ui-style container attribute. See uiStyle.

CellType

enum StorytellerListViewCellType {
  round = 'round',
  square = 'square',
}

Exported as CellType. Sets the tile shape of a row. The default is square. See cellType.

ActivityType

The type argument of onUserActivityOccurred. The event pages list when each event fires and its properties:

Area	Values	Reference
SDK	sdkInitialized	SDK initialization
Stories and Clips	actionButtonTapped, shareButtonTapped, shareSuccess	Story events, Clip events
Stories	openedStory, dismissedStory, skippedStory, completedStory, openedPage, previousPage, previousStory	Story events
Story captions	enabledStoryCaptions, disabledStoryCaptions	Story caption events
Polls	votedPoll	Poll events
Quizzes	triviaQuizQuestionAnswered, triviaQuizCompleted	Quiz events
Ads	openedAd, dismissedAd, pausedAdPage, resumedAdPage, finishedAd, skippedAd, adActionButtonTapped, viewedAdPageFirstQuartile, viewedAdPageMidpoint, viewedAdPageThirdQuartile, viewedAdPageComplete	Ad events
Clips	openedClip, dismissedClip, finishedClip, nextClip, previousClip, completedLoop, pausedClip, resumedClip, likedClip, unlikedClip, openedCategory, dismissedCategory	Clip events
Clip captions	enabledClipCaptions, disabledClipCaptions	Clip caption events

The source groups these values as no longer used or deprecated:

• completedPage and skippedPage. The Story player still records these two events, and the event pages do not document them
• swipedUp, viewedPage, completedAd, swipedUpOnAd, previousAd, impression, readyToPlay, mediaStarted, bufferingStarted, bufferingEnded. The SDK does not record these events

OpenedReason

The openedReason property of open events:

Area	Values
Stories	storyListTap, deepLink, swipe, automaticPlayback, tap
Clips	clipListTap, categoryListTap, categoryBackTap, deepLink

See OpenedReason for each value. openCollection accepts OpenedReason.deepLink as its third argument.

DismissedReason

The dismissedReason property of dismiss events:

Area	Values
Stories and Clips	backgroundTapped, instanceMethod, windowUnload
Stories	closeButtonTapped, swipedDown, swipedFirstStory, swipedFinalStory, skippedFinalPage, completedFinalPage, backTapped, escapeKeyPressed
Clips	backButtonTapped

See DismissedReason for each value. dismissPlayer reports instanceMethod.

StorytellerTrackedFunctionalFeature

enum StorytellerTrackedFunctionalFeature {
  all = 'all',
  clipLikes = 'clipLikes',
  clipShares = 'clipShares',
  clipViewedStatus = 'clipViewedStatus',
  pageReadStatus = 'pageReadStatus',
  pollVotes = 'pollVotes',
  triviaQuizAnswers = 'triviaQuizAnswers',
}

The items of eventTrackingOptions.disabledFunctionalFeatures. all disables every item. See Disabled functional features.

Note

The npm package exports this enum at runtime. The CDN script does not, so Storyteller.StorytellerTrackedFunctionalFeature is undefined there. Pass the string values instead, such as ['pageReadStatus'].

Theme enums

Three enums set theme properties. See Customize themes for each property:

Enum	Values	Theme properties
Alignment	start, center, end	storyTiles.title.alignment, storyTiles.rectangularTile.chip.alignment
ButtonAlignment	left, center, right	player.actionButton.alignment
TextCase	default, upper, lower	buttons.textCase

Privacy options

The type of Storyteller.sharedInstance.eventTrackingOptions.

StorytellerEventTrackingOptions

type StorytellerEventTrackingOptions = {
  disabledFunctionalFeatures: StorytellerTrackedFunctionalFeature[];
  enableAdTracking: boolean;
  enableFullVideoAnalytics: boolean;
  enableFunctionalCookies: boolean;
  enablePersonalization: boolean;
  enableRemoteViewingStore: boolean;
  enableStorytellerTracking: boolean;
  enableUserActivityTracking: boolean;
};

Field	Default	Effect when changed from the default
disabledFunctionalFeatures	[]	Stops tracking the listed features
enableAdTracking	true	false stops ad events and removes Story and Clip details from ad requests
enableFullVideoAnalytics	true	false sets Story, Page, and Clip IDs and titles to null in callback data
enableFunctionalCookies	true	false stops non-essential local storage, and turns off personalization and Storyteller tracking
enablePersonalization	true	false stops sending user IDs and user attributes for personalization
enableRemoteViewingStore	true	false keeps user IDs off backend services and keeps viewing activity on the device
enableStorytellerTracking	true	false stops storing analytics events on Storyteller servers
enableUserActivityTracking	true	false stops onUserActivityOccurred calls

Event data

The data types of analytics events.

UserActivityData

The data argument of onUserActivityOccurred. Every field is optional, and each event sets a subset. The event pages list the fields of each event.

Area	Fields and types
Context	context (unknown): the view's configuration.context
Stories and Pages	storyId, storyTitle, storyDisplayTitle, pageId, pageTitle (string, or null when enableFullVideoAnalytics is false); storyIndex, storyPageCount, pageIndex, durationViewed, pagesViewed, contentLength (number); storyReadStatus (string); storyPlaybackMode ('list' or 'singleStory'); pageType ('image', 'video', 'poll', or 'triviaQuiz'); pageHasAction (boolean); pageActionText, pageActionUrl (string or null)
Navigation	openedReason (OpenedReason); dismissedReason (DismissedReason); shareMethod ('share', 'shareMedia', 'shareLink', or '')
Categories	categories (string[]); categoryDetails (CategoryDetail[]); currentCategory (CurrentCategory); categoryId, categoryName (string)
Ads	adId, adStrategy (string); advertiserName (string or null); adType ('stories' or 'clips'); adPlacement ('betweenClips', 'betweenStories', 'betweenStoriesAndPages', or 'betweenPages')
Polls	pollAnswerId (string)
Quizzes	triviaQuizId, triviaQuizQuestionId, triviaQuizAnswerId, triviaQuizTitle (string); triviaQuizScore (number)
Clips	clipId, clipTitle (string, or null when enableFullVideoAnalytics is false); collection (string); clipActionText, clipActionUrl (string or null); clipIndex, clipsViewed, loopsViewed (number); clipHasAction (boolean)
Captions	captionsEnabled (boolean)
SDK initialization	initializationSucceeded, enableAdTracking, enableFullVideoAnalytics, enablePersonalization, enableRemoteViewingStore, enableStorytellerTracking, enableUserActivityTracking (boolean); appId, screenResolution (string or null); deviceBrand, deviceModel, operatingSystem, osVersion (string); deviceType ('Phone', 'Tablet', 'TV', or 'Desktop')

The category types have these fields:

class CategoryDetail {
  name: string;
  id?: string;
  type: string;
  placement?: string;
  externalId?: string;
}

class CurrentCategory {
  title: string;
  id?: string;
  placement?: string;
}

The SDK exports UserActivityData as a class. The callback receives a plain object with these fields.

ActivityEventDetail

class ActivityEventDetail {
  type: ActivityType;
  data: UserActivityData;
  constructor(type: ActivityType, data: UserActivityData);
}

A pair of event type and event data. The SDK exports the class, but no SDK callback receives it in 11.0.0.

Ad request data

The adRequestInfo argument of getAdConfig. See AdRequestInfo.

StorytellerAdRequestInfo

type StorytellerAdRequestInfo =
  | StorytellerStoriesAdRequestInfo
  | StorytellerClipsAdRequestInfo;

Check for the story field to tell the variants apart:

const isStoryAd = (
  info: Storyteller.StorytellerAdRequestInfo
): info is Storyteller.StorytellerStoriesAdRequestInfo => 'story' in info;

StorytellerStoriesAdRequestInfo

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

Field	Description
placement	Placement code of the Story category that matches the first category ID of the view. '' when none matches
categories	Category IDs of the view that shows the Story
story.categories	Categories of the Story, as CategoryDetail objects
story.id	Always ''. Deprecated

See Stories AdRequestInfo.

StorytellerClipsAdRequestInfo

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

Field	Description
collection	Collection ID
clip.categories	Categories of the current Clip
nextClip.categories	Categories of the next Clip. nextClip is absent when no next Clip exists
clip.id	Always ''. Deprecated

ClipCategory has these fields:

interface ClipCategory {
  id: string;
  name: string;
  externalId: string;
  placement: string | null;
  type: string;
  displayTitle: string;
  availableForNavigation: boolean;
}

See Clips AdRequestInfo.

Theme classes

The classes and types that build a theme. Customize themes lists every theme property and default.

UiTheme

class UiTheme implements IUiTheme {
  light: StorytellerTheme;
  dark: StorytellerTheme;
  constructor(baseTheme?: Subset<IUiTheme> | null);
}

Holds a light and a dark Theme. The constructor builds both from baseTheme, and unset properties keep their defaults. The view's UiStyle decides which theme applies. See Customize themes.

const theme = new Storyteller.UiTheme({
  light: { colors: { primary: '#1C62EB' } },
  dark: { colors: { primary: '#6699FF' } },
});

Theme

class StorytellerTheme implements IStorytellerTheme {
  colors: StorytellerColorsTheme;
  font: string;
  primitives: StorytellerPrimitivesTheme;
  lists: StorytellerListsTheme;
  storyTiles: StorytellerTilesTheme;
  player: StorytellerPlayerTheme;
  clipPlayer: StorytellerClipPlayerTheme;
  buttons: StorytellerButtonsTheme;
  instructions: StorytellerInstructionsTheme;
  engagementUnits: StorytellerEngagementUnitsTheme;
  isDark: boolean;
  constructor(theme?: Subset<IStorytellerTheme>);
  toPlainObject(): this;
}

Exported as Theme. One color scheme of a theme. The constructor copies the properties of theme over the defaults. The SDK sets isDark when it builds the dark theme. toPlainObject returns the instance.

Property	Theme section
colors	Colors
font	Font
primitives	Primitives
lists	Lists
storyTiles	Story Tiles
player	Player
clipPlayer	Clips player
buttons	Buttons
instructions	Instructions
engagementUnits	Polls and Quizzes theme

Subset

type Subset<K> = {
  [attr in keyof K]?: K[attr] extends object
    ? Subset<K[attr]>
    : K[attr] extends object | null
    ? Subset<K[attr]> | null
    : K[attr] extends object | null | undefined
    ? Subset<K[attr]> | null | undefined
    : K[attr];
};

A recursive Partial. Theme inputs use it, so you set only the properties that you change, at any depth.

const rowTheme: Storyteller.Subset<Storyteller.UiTheme> = {
  light: { lists: { row: { startInset: 0 } } },
};

Server rendering

These exports build Story markup for server-side rendering. They do not use window or document.

ServerRenderer

ServerRenderer.getStories(categories?: string[]): Promise<ServerRenderedStory[]>
ServerRenderer.render(stories: ServerRenderedStory[]): React.JSX.Element

A singleton instance. getStories loads the Stories of the given categories with the API key from initialize, and keeps the Stories that have a Google Web Story URL. render returns a hidden <amp-story-player> element with a link, poster image, and title for each Story. No task guide covers these methods.

Parameter	Type	Required	Default	Description
categories	string[]	No	[]	Story category IDs
stories	ServerRenderedStory[]	Yes	None	Stories from getStories

ServerRenderedStory

type ServerRenderedStory = {
  id: string;
  href: string;
  title: string;
  thumbnailUrl: string;
};

href is the Story's Google Web Story URL.

Other exports

The SDK also exports these names. No guide covers them, and integrations do not need them:

Export	Kind	Notes
Story	Class	Story data model from the Stories API. No public SDK method or callback returns it in 11.0.0
QuizRenderer	Instance	Renders Quiz questions and results inside a Story page document. The SDK's Story page script uses its own copy
QuizApiService	Instance	Loads Quiz data for Story pages. The SDK's Story page script uses its own copy