BlazeSDK class

Use this reference for the Experiences Web SDK entry point: initialization, global options, widget methods, playback helpers, and types. API identifiers keep the Blaze prefix in code.

How this page is organized

## Methods groups the global static methods on BlazeSDK:

• Lifecycle: isInitialized, Initialize, and readiness (onBlazeSDKConnect).
• Widget constructors: WidgetGridView, WidgetRowView, WidgetEmbeddedStory, WidgetEmbeddedVideo, and the shared IWidgetViewOptions table.
• Theme: Theme() and the available theme presets.
• Privacy and tracking: setDoNotTrack, setDisableAnalytics, setDisableUserActivity, clearLocalUserActivity.
• Viewer identity and localization: setExternalUserId, setExternalUserToken, setPreferredLanguage, setGeoLocation.
• Personalization: isInColdStart.
• Interaction: setOnItemClick.
• Playback: playContent, playStory, playStories, appendContentToPlayer, setBeforeContentPlayCallback.
• Moments playback: setDefaultMomentsPlaybackConfiguration, updateMomentsPlaybackConfiguration, and the IBlazeMomentsPlaybackConfiguration type.
• Player control: closeCurrentPlayer, pauseCurrentPlayer, resumeCurrentPlayer.
• App context: getAppContextManager.

## Ads covers the ad handlers, and ## Complete integration example puts several widget calls together.

Content and customization types live on their own pages:

• Content selection: DataSourceBuilder, label builders, and video filters. See BlazeDataSourceType.
• Fully custom renderers: see Custom widgets.
• Theme objects, per item style overrides, and action handlers: see Theme.
• Events: see Global delegate methods for global and widget delegates.
• Widget instance API (setTheme, updateDataSource, reload, and so on): see WidgetView class.

Methods

Lifecycle

isInitialized(): boolean

The isInitialized method returns a boolean that indicates whether the SDK is already initialized. This helps prevent duplicate initialization calls and lets you run logic depending on the SDK's readiness. Call this method before initializing to confirm that the SDK hasn’t already been set up elsewhere in your application.

Initialize(apiKey: string, options: IBlazeSDKOptions): Promise<void>

The SDK injects a <blaze-sdk api-key="…" /> element into the document as part of startup. Initialize is synchronous; await it or handle its promise before you rely on widgets or playback.

Call Initialize once per page load. A second call can cause an inconsistent state. Run it as early as your app allows (for example, right after you create the root container). Pass a valid IBlazeSDKOptions object when you need global behavior (privacy, identity, geo, player styling, and so on).

To know when the SDK is ready, listen for onBlazeSDKConnect. Register the listener before you call Initialize so you don’t miss the event if it fires immediately. onBlazeSDKConnect runs once after the first successful initialization.

document.addEventListener("onBlazeSDKConnect", onBlazeSDKConnect);

if (!BlazeSDK.isInitialized()) {
    BlazeSDK.Initialize('<API-KEY>',{
     geoLocation: 'IL', // Country code by two letters
     externalUserId: 'user-123',
     doNotTrack: false,
     runInShadowDom: true, // default value is true
     shouldModifyUrlWithContentId: true, // default value is true
     playerStyleCustomization: { // only for Stories, not supported to Moments
       iconsPosition: 'VERTICAL'
     },
     prefetchingPolicy: 'default',
     shouldAllowHorizontalStories: false, // by default false
     layoutDirection: "LTR", // by default LTR
     followedEntities: ['player-123', 'team-123', { entityId: 'property-123', providerName: 'stats-perform' }],
		 disableAnalytics: false,
		 disableUserActivity: false
   })
}

Prefetch Policy

Widget constructors

WidgetGridView(containerId: string, options?: IWidgetViewOptions): IWidgetView

WidgetRowView(containerId: string, options?: IWidgetViewOptions): IWidgetView

WidgetEmbeddedStory(containerId: string, options?: IWidgetViewOptions): IWidgetView

WidgetEmbeddedVideo(containerId: string, options?: IWidgetViewOptions): IWidgetView

For guidance on when to use an embedded video widget versus a row or grid widget, plus an end-to-end example, see WidgetEmbeddedVideo.

BlazeSDK.WidgetRowView(...) and BlazeSDK.WidgetGridView(...) support options.widgetRemoteIdentifier?: string. When you provide this identifier, the widget loads its data source and layout styling from a remote widget configuration. After that, local runtime mutators, including theme and data source updates, are ignored because the widget is remote-managed.

BlazeSDK.WidgetEmbeddedStory(...) and BlazeSDK.WidgetEmbeddedVideo(...) do not accept widgetRemoteIdentifier.

Returns an IWidgetView object

const myTheme: IWidgetTheme = BlazeSDK.Theme('row-rectangle');

const myDataSource = BlazeSDK.DataSourceBuilder().labels({
   labels: 'live-stories',
   orderType: 'RecentlyUpdatedFirst',
   maxItems: 10,
	 advancedOrdering: 'LiveFirst',

})

const options: IWidgetViewOptions = {
   dataSource: myDataSource, // Use a data source instead of labels
   maxDisplayItemsCount: 1, // Display only 1 item
   theme: myTheme // Set the theme of the widget,
   shouldOrderWidgetByReadStatus: true // the default value is true   
   perItemStyleOverrides: {
        "playerId": [
            {
                name: "35450",
                theme: rowCircleThemePlayer
            },
            {
                name: "28237",
                theme: rowCircleThemePlayer
            },
            {
                name: "46046",
                theme: rowCircleThemePlayer
            }
        ],
        "teamId": [
            {
                name: "real-madrid",
                theme: rowCircleThemeRealMadrid
            }
        ]
    },
    actionHandlers: [
        {
          actionId: 'addCustomActionButton',
          options: {
            buttonName: 'go-to-fans-page',
            onClick: (e, entities) => {
              console.log(entities?.gameId, entities?.playerId, entities?.teamId);
            },
          },
        },
        {
          actionId: 'addCustomActionButton',
          options: {
            buttonName: 'go-to-social-page',
            onClick: (e, entities) => {
              console.log(entities?.gameId, entities?.playerId, entities?.teamId);
            },
          },
        },
	{
          actionId: 'addFollowButton',
          options: {
            onClick: (e, data) => {
              console.log(data.sourceId,
                          data.sourceContentType,
                          data.newFollowingState,
                          data.followEntity.entityType,
 			  data.followEntity.entityId,
			  data.followEntity.providerName); // optional, opaque data-provider name
            },
          },
        },
     ],
};

const widgetView: IWidgetView = BlazeSDK.WidgetRowView('<DOM-CONTAINER-ID>', options);

//widgetView has an interface, which allows you to interact with the widget in the DOM 
//widgetView.reload()

For perItemStyleOverrides and actionHandlers, see Per item style overrides and Action handlers.

Theme

Theme(preset?: ThemeType): IWidgetTheme

Returns an IWIdgetTheme object with default theme preset

const theme = BlazeSDK.Theme('row-rectangle','story');

const theme: IWidgetTheme = BlazeSDK.Theme('row-rectangle');

Theme Type

For the full theme object, its properties per surface, and how to apply one, see Theme.

Privacy and tracking

setDoNotTrack(value: boolean): void

BlazeSDK.setDoNotTrack(true);

WSC Sports can enforce do not track for the app. When enforcement is on, the app cannot set this value to false. See Viewer privacy considerations and privacy compliance.

setDisableAnalytics(value: boolean): void

BlazeSDK.setDisableAnalytics(true);

WSC Sports can enforce analytics off for the app. When enforcement is on, the app cannot set this value to false. See Viewer privacy considerations and privacy compliance.

setDisableUserActivity(value: boolean): void

BlazeSDK.setDisableUserActivity(true);

clearLocalUserActivity(): Promise<void>

Clears all user activity data from the device's local storage only, without affecting remote data.

BlazeSDK.clearLocalUserActivity();

Viewer identity and localization

setExternalUserId(value: string | null): void

BlazeSDK.setExternalUserId('1234');
BlazeSDK.setExternalUserId(null); // viewer signed out

setExternalUserToken(token: string | null): void

Sets or replaces the external user token used for protected or tokenized playback. Pass null to clear the current token.

BlazeSDK.setExternalUserToken('token-123');
BlazeSDK.setExternalUserToken(null);

setPreferredLanguage(value: string): void

BlazeSDK.setGeoLocation('IL')

setGeoLocation(value: string): void

BlazeSDK.setGeoLocation('IL')

Personalization

isInColdStart(contentType: ContentType): boolean | null

Returns whether the current viewer is in cold start for the given content type.

• true: the viewer's For You feed for this content type is served cold-start content instead of the personalized model.
• false: the personalized model is served.
• null: the status is unknown. For example, the viewer is anonymous (no externalUserId set), or user activity has not been fetched yet in this session.

The value refreshes with every user activity fetch (initialization, returning to the page, or a viewer switch). It does not change mid-session as the viewer interacts.

const status = BlazeSDK.isInColdStart('moment');

Interaction

setOnItemClick(callback: ItemClickCallback | undefined): void

Registers a single, SDK wide callback that runs when a viewer clicks a widget item (tile) in a row or grid widget, before the player opens. Return { shouldPreventOpen: true } from the callback to stop the default player from opening (for example, to route to your own screen); return { shouldPreventOpen: false } to allow normal behavior. Pass undefined to remove the callback.

This is separate from delegation events (the delegates option / addDelegateListener), which are CustomEvents for SDK lifecycle changes and cannot prevent the default click action.

The callback receives an ItemClickContext:

Supported Web SDK version: contentThumbnailUrl is available in @wscsports/blaze-web-sdk 0.36.1 or later.

BlazeSDK.setOnItemClick((context) => {
  console.log('Clicked:', context.item.title, context.contentThumbnailUrl);
  return { shouldPreventOpen: false };
});

// Remove the callback
BlazeSDK.setOnItemClick(undefined);

Playback

playContent(contentType: ContentType, options: PlayContentOptions): Promise<void>

The PlayContentOptions type defines the configuration options for the playContent function, allowing customization of content playback through data sources, action handlers, and styling options.

• dataSource (BlazeDataSourceType): The source of the content to be played, providing the necessary data for rendering.
• actionHandlers (ActionHandler[]?): Optional. An array of actions.
• style (StoryPlayerStyle | VideoPlayerStyle?): Optional. Specifies the player’s visual styling. To ensure action handlers display buttons, set isVisible to true on customButtonsAction in the player style.
• shouldOrderContentByReadStatus: Whether to order the content by read status, displaying unread items first. Default is true.
• playbackConfiguration (IBlazeMomentsPlaybackConfiguration?): Optional. Moments only. Sets the playback behavior for this player. When omitted, the SDK default applies. See Moments playback.

const dataSource = BlazeSDK.DataSourceBuilder().labels({
  labels: BlazeSDK.LabelBuilder().atLeastOneOf('top-stories', 'live-stories'),
  maxItems: 4,
})
const playerStyle = BlazeSDK.Theme('default').playerStyle;
theme.playerStyle.iconsButton.filter(icon => icon.value === 'CUSTOM_ACTION_BUTTON_ONE')[0].isVisible = true;
theme.playerStyle.iconsButton.filter(icon => icon.value === 'CUSTOM_ACTION_BUTTON_TWO')[0].isVisible = true;

actionHandlers: [
        {
          actionId: 'addCustomActionButton',
          options: {
            buttonName: 'go-to-fans-page',
            onClick: (e, entities) => {
              console.log(entities?.gameId, entities?.playerId, entities?.teamId);
            },
          },
        },
        {
          actionId: 'addCustomActionButton',
          options: {
            buttonName: 'go-to-social-page',
            onClick: (e, entities) => {
              console.log(entities?.gameId, entities?.playerId, entities?.teamId);
            },
          },
        },
      ],

BlazeSDK.playContent('story',{
  dataSource,
  style: playerStyle,
  actionHandlers,
  shouldOrderContentByReadStatus: true
});

playStory(storyId: string, style?: StoryPlayerStyle ): void

Deprecated: use playContent instead of playStory.

const playerStyle = BlazeSDK.Theme('default').playerStyle;

BlazeSDK.playStory('66c0d0c6607d0c10cf3dd98d',playerStyle)

playStories(dataSource: BlazeDataSourceType, style?: StoryPlayerStyle, actionHandlers?: ActionHandler[]): Promise<void>

Deprecated: use playContent instead of playStories.

const dataSource = BlazeSDK.DataSourceBuilder().labels({
  labels: BlazeSDK.LabelBuilder().atLeastOneOf('top-stories', 'live-stories'),
  maxItems: 4,
})
const playerStyle = BlazeSDK.Theme('default').playerStyle;

BlazeSDK.playStories(dataSource, playerStyle)

appendContentToPlayer(contentType: ContentType, dataSource: BlazeDataSourceType, options?): Promise<void>

This function supports only moment content type for now

This function allows you to append content to the current opened player. It receives a content type, data source and options object, and append it to the end of the current content list of the player.

function appendContentToPlayer(contentType: ContentType, dataSource: BlazeDataSourceType, options?: {
    shouldOrderContentByReadStatus?: boolean;
}): Promise<void>

Usage examples:

BlazeSDK.appendContentToPlayer('moment', 
                                BlazeSDK.DataSourceBuilder().labels({ labels: "my-label" })
                              );
BlazeSDK.appendContentToPlayer('moment', 
                               BlazeSDK.DataSourceBuilder().ids({ ids: ["6706731d200c07e22d70a2ed","663a1c0a4e167da3d5a3ddf9"] }),
                               { shouldOrderContentByReadStatus: false } 
                              );

setBeforeContentPlayCallback(callback: BeforeContentPlayCallback | undefined): void

The callback runs only when enableClientPlaybackModification is true in the app configuration. If the callback throws an error or returns an invalid result, the SDK falls back to the original URL so playback continues. Keep callback execution time short to avoid delays in video playback.

Don't expose sensitive tokens or credentials in client-side code.

BeforeContentPlayCallback interfaces

BeforeContentPlayCallback: (context: BeforeContentPlayContext) => Promise<BeforeContentPlayResult> | BeforeContentPlayResult

interface BeforeContentPlayContext {
  originalUrl: string;
}

interface BeforeContentPlayResult {
  resultUrl: string;
}

type BeforeContentPlayCallback = (
  context: BeforeContentPlayContext
) => Promise<BeforeContentPlayResult> | BeforeContentPlayResult;

Async URL tokenization

// URL tokenization example for protected content
BlazeSDK.setBeforeContentPlayCallback(async (context) => {
  const { originalUrl } = context;

  const response = await fetch(`https://example-service.com/tokenGen?url=${originalUrl}`)
  const data = await response.json()

  return {
    resultUrl: data.data.url
  };
});

Synchronous URL modification

// Synchronous URL modification example
BlazeSDK.setBeforeContentPlayCallback((context) => {
  const { originalUrl } = context;
  
  const url = new URL(originalUrl);
  url.searchParams.set('token', getUserToken());
  url.searchParams.set('timestamp', Date.now().toString());
  
  return {
    resultUrl: url.toString()
  };
});

Remove callback

// Remove callback
BlazeSDK.setBeforeContentPlayCallback(undefined);

Moments playback

Moments playback configuration controls what the moments player does when a moment finishes: replay it, or play it a set number of times and then advance to the next moment. By default, the player replays the current moment until the viewer navigates ({ loopBehavior: { type: 'infiniteLoop' } }).

IBlazeMomentsPlaybackConfiguration

BlazeMomentsLoopBehavior is one of:

Notes:

• The configuration applies to content moments only. Ad moments always advance after a single play.
• An invalid value doesn't throw. The SDK reports it on onErrorThrown and uses a working value instead: an invalid numberOfPlays becomes 1 (error code 400), and a missing or unknown loopBehavior falls back to infiniteLoop (error code 401).

You can set the configuration at several levels. A per-widget, per-call, or open-player value overrides the SDK default for that player:

setDefaultMomentsPlaybackConfiguration(configuration: IBlazeMomentsPlaybackConfiguration): void

Sets the SDK default moments playback behavior. It applies to every moments player that doesn't have a widget, call, or open-player override.

BlazeSDK.setDefaultMomentsPlaybackConfiguration({
  loopBehavior: { type: 'loopAndAdvance', numberOfPlays: 2 },
});

updateMomentsPlaybackConfiguration(configuration: IBlazeMomentsPlaybackConfiguration | null): void

Changes the playback behavior of the moments player that is currently open. It has no effect when no moments player is open. Pass null to remove the override; the open player then uses the SDK default.

BlazeSDK.updateMomentsPlaybackConfiguration({
  loopBehavior: { type: 'infiniteLoop' },
});
BlazeSDK.updateMomentsPlaybackConfiguration(null);

Player control

closeCurrentPlayer(): void

Closes the currently open player.

BlazeSDK.closeCurrentPlayer();

pauseCurrentPlayer(): void

Pause the story in the opened modal.

BlazeSDK.pauseCurrentPlayer();

resumeCurrentPlayer(): void

Resume the story in the opened modal.

BlazeSDK.resumeCurrentPlayer();

App context

getAppContextManager(): Record<string, any>

The app context manager allow you to send custom properties to your own enrichment layer. for example:

BlazeSDK.getAppContextManager().userName = "Lorem Ipsum"

Ads

setGoogleCustomNativeAdsHandler

Allows you to send optional properties for custom native ads. It is an optional method.

type CustomNativeTargeting = Record<string, string | string[]>;
type CustomNativeArgs = {
  path: string;
};

interface CustomNativeAdHandler {
  provideAdExtraParams?: (args: CustomNativeArgs, contentExtraInfo?: ContentExtraInfo) => CustomNativeTargeting;
}

provideAdExtraParams

method signature

function provideAdExtraParams(args: { path: string }, contentExtraInfo?: ContentExtraInfo): CustomNativeTargeting;

// Usage example:
BlazeSDK.setGoogleCustomNativeAdsHandler({
  provideAdExtraParams: (args, contentExtraInfo) => {
    return {
    	"gdpr": "1",
    	"age": ["1", "2"],
    	"next": JSON.stringify(contentExtraInfo?.next),
    	"prev": JSON.stringify(contentExtraInfo?.previous)     
}
}});

Optional function that will be triggered every time a custom native ad or a banner ad (in the Stories and Moments players) requests an ad. For banner ads, args.path is the banner's ad unit ID. Use this to customize how (and if) each viewer consent (or any other extra query params) behaves. If not implemented, the SDK will use the default value, which equals to {}.

setImaHandler

Allows you to send optional properties for custom native ads. It is an optional method.

type ImaExtraParams = Record<string, string>;

interface ImaAdHandler {  
  provideAdExtraParams?: (contentExtraInfo?: ContentExtraInfo) => ImaExtraParams;
}

provideAdExtraParams

method signature

function provideAdExtraParams(contentExtraInfo? : ContentExtraInfo): ImaExtraParams;

// Usage example:  
BlazeSDK.setImaHandler({  
  provideAdExtraParams: (contentExtraInfo) => {  
    return {
    	"cust_params": "gdpr=1"
    }  
}});

Optional function that will be triggered every time a ima ad request an ad. Use this to customize how (and if) each viewer consent (or any other extra query params) behaves. If not implemented, the SDK will use the default value, which equals to .

In Stories and Moments, the SDK can preload the upcoming VAST ad so it starts without a loading delay. The request, and this function, run when the ad is preloaded, which can be before the viewer reaches the ad slot, and also for preloaded ads that end up not being shown.

Ad types

ContentExtraInfo

ExtraInfo

Complete integration example

const filters = BlazeSDK.VideoFilterBuilder();

// Live games section
const liveGames = BlazeSDK.WidgetRowView('live-container', {
  dataSource: BlazeSDK.DataSourceBuilder().labels({
    labels: 'sports-games',
    advancedOrdering: 'LiveFirst',
    maxItems: 10
  }),
  contentType: 'video',
  videoFilters: filters.liveOnly()
});

// Upcoming schedule
const schedule = BlazeSDK.WidgetGridView('schedule-container', {
  dataSource: BlazeSDK.DataSourceBuilder().labels({
    labels: 'sports-games',
    orderType: 'OldestFirst',
    maxItems: 20
  }),
  contentType: 'video',
  videoFilters: filters.upcomingOnly()
});

// Replays library
const replays = BlazeSDK.WidgetRowView('replays-container', {
  dataSource: BlazeSDK.DataSourceBuilder().labels({
    labels: 'sports-games',
    orderType: 'RecentlyUpdatedFirst',
    maxItems: 20
  }),
  contentType: 'video',
  videoFilters: filters.endedOnly()
});