blaze sdk

Methods


ParameterTypeRequiredDescription
apiKeystringYesthe API key
options.doNotTrack?booleannoIt will set do not track feature
options.externalUserId?stringnoit will set the external user ID feature
options.geoLocation?stringnoit will set the geolocation feature globally
options.runInShadowDom?booleannoTODO
options.shouldModifyUrlWithStoryId?booleannoit will prevent the SDK from modifying the page URL
options.playerStyleCustomization?Partial TODOnoSet global style on the player
options.prefetchingPolicy?TODOnodefault is the value if not defined
options.shouldAllowHorizontalStoriesbooleannoTODO

Initialize(apiKey: string, options: IBlazeSDKOptions): Promise

In the background it initiate the SDK by injecting <blaze-sdk api-key="your-api-key" /> tag into html body. this is async method

ParameterTypeRequiredDescription
apiKeystringYesthe API key
options.doNotTrack?booleannoIt will set do not track feature
options.externalUserId?stringnoit will set the external user ID feature
options.geoLocation?stringnoit will set the geolocation feature globally
options.runInShadowDom?booleannoIt will run the SDK inside a shadow dom. default = true
options.shouldModifyUrlWithStoryId?booleannoit will prevent the SDK from modifying the page URL
options.playerStyleCustomization?PartialnoSet global style on the player
options.prefetchingPolicy?string - 'low' | 'default'nodefault is the value if not defined
options.shouldAllowHorizontalStoriesbooleannoIf not defined, will show vertical content on Desktop.
Please content AM/DM for more info
 BlazeSDK.Initialize('<API-KEY>',{
   geoLocation: 'IL', // Country code by two letters
   externalUserId: 'user-123',
   doNotTrack: false,
   runInShadowDom: true, // default value is true
   shouldModifyUrlWithStoryId: true, // default value is true
   playerStyleCustomization: { // only for Stories, not supported to Moments
     iconsPosition: 'VERTICAL'
   },
   prefetchingPolicy: 'default',
   shouldAllowHorizontalStories: false // by default false
 })

Prefetch Policy

LevelDescription
LowInitially, no pre-fetch
While playing, the next page of the currently playing story, and the first unread page of the next story
DefaultInitially, pre-fetches the first story page in line.
While playing, the next two pages of the currently playing story, the first unread page of the next story, and the first unread page of the prev story.

LevelDescription
LowInitially, no pre-fetch TODO
DefaultInitially, pre-fetches the first story page in line. TODO


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

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

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

Returns an IWidgetView object

ParameterTypeRequiredDescription
containerIdstringYesthe widget will be appended into the HTML element with the given container ID
options?IWidgetViewOptionsNooptional parameter. Here you can determine the labels and theme for the created view
options.dataSourceBlazeDataSourceTypeif not labels or storyIds provided
options.labelsstring~~string[]~~\BlazeWidgetLabelIf storyIds was not specifiedarray of strings is depreacted but still supported,
string as value or
create your labels with LabelBuilder ( see below)
options.storyIdsstring[]If labels was not specifieddepreacted - use contentIds instead
Fetching and displaying the specific stories indicated with ['storyId1', 'storyId2'].

Please note: In case you specify both "labels" and "storyIds" properties, only the "labels" property will be applied.
options.contentIdsstring[]if labels was not specified Fetching and displaying the specific stories/moments indicated with ['1234', '5678'].

Please note: In case you specify both "labels" and "storyIds" properties, only the "labels" property will be applied.
options.contentType?'story' | 'moment'if not provided, will be storyIn order to use specific content, it is recommended to set it
options.labelsPriority?stringNoThe order is which the string will order the label's result. A string with an opening of '[' and close by ']'.
Example: '[teama, teamb]'
options.theme?stringNoyou can pass your own theme object to this specific view
options.maxItemsCount?numberNoSpecify the max items to fetch from server
options.maxDisplayItemsCount?numberNoSpecify the max items to display. You can display 3 items while having 10 items returned from server.
options.orderType?stringNoSpecify the items order type. Unread items will show first by selected order type, following by read items also ordered by selected order type.

Possible order types: Manual, AtoZ, ZtoA, RecentlyUpdatedFirst, RecentlyUpdatedLast, RecentlyCreatedFirst, RecentlyCreatedLast
options.perItemStyleOverrides?PerItemStyleOverridesnoThe perItemStyleOverrides property in IWidgetViewOptions facilitates custom styling for individual items within a widget based on specific entity identifiers.

This feature enhances flexibility by allowing unique visual representations for each item within the widget.
options.shouldOrderWidgetByReadStatus?booleannoIf set to false, the items in the widget will not be ordered by read/unread status anymore. It will be sorted by the returns order from the server
ParameterTypeRequiredDescription
containerIdstringYesthe widget will be appended into the HTML element with the given container ID
options?IWidgetViewOptionsNooptional parameter. Here you can determine the labels and theme for the created view
options.dataSourceBlazeDataSourceTypeif not labels or storyIds provided
options.labelsstring~~string[]~~\BlazeWidgetLabelIf storyIds was not specifiedarray of strings is depreacted but still supported,
string as value or
create your labels with LabelBuilder ( see below)
options.storyIdsstring[]If labels was not specifieddepreacted - use contentIds instead
Fetching and displaying the specific stories indicated with ['storyId1', 'storyId2'].

Please note: In case you specify both "labels" and "storyIds" properties, only the "labels" property will be applied.
options.contentIdsstring[]if labels was not specified Fetching and displaying the specific stories/moments indicated with ['1234', '5678'].

Please note: In case you specify both "labels" and "storyIds" properties, only the "labels" property will be applied.
options.contentType?'story' | 'moment'if not provided, will be storyIn order to use specific content, it is recommended to set it
options.labelsPriority?stringNoThe order is which the string will order the label's result. A string with an opening of '[' and close by ']'.
Example: '[teama, teamb]'
options.theme?stringNoyou can pass your own theme object to this specific view
options.maxItemsCount?numberNoSpecify the max items to fetch from server
options.maxDisplayItemsCount?numberNoSpecify the max items to display. You can display 3 items while having 10 items returned from server.
options.orderType?stringNoSpecify the items order type. Unread items will show first by selected order type, following by read items also ordered by selected order type.

Possible order types: Manual, AtoZ, ZtoA, RecentlyUpdatedFirst, RecentlyUpdatedLast, RecentlyCreatedFirst, RecentlyCreatedLast
options.perItemStyleOverrides?PerItemStyleOverridesnoThe perItemStyleOverrides property in IWidgetViewOptions facilitates custom styling for individual items within a widget based on specific entity identifiers.

This feature enhances flexibility by allowing unique visual representations for each item within the widget.
options.shouldOrderWidgetByReadStatus?booleannoIf set to false, the items in the widget will not be ordered by read/unread status anymore. It will be sorted by the returns order from the server
 const widgetView = BlazeSDK.WidgetRowView('<DOM-CONTAINER-ID>', {
   labels: 'top-stories', // Can be string, string[], BlazeWidgetLabel
   orderType: 'ZtoA',// Order of the label, will override the config order of the label
   labelsPriority: '[teama,teamb]' // Order the label exp by labels order
   storyIds: ['64a2d76b9503bc65ac531633','64a2d76b9503bc65ac531634'], // Stories ids
   maxItemsCount: 10, // fetch only 10 items from the backend
   maxDisplayItemsCount: 1, // display only 1 
   theme: 'row-circle', // 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
            }
        ]
    }                                        
 })
 
 //widgetView has an interface, which allows you to interact with the widget in the DOM 
 //widgetView.reload()
const myTheme:IWidgetTheme = BlazeSDK.Theme('row-rectangle');

const options: IWidgetViewOptions = {
	 labels: BlazeSDK.LabelBuilder().atLeastOneOf("read-madrid", "vini"), // Can be string, string[], BlazeWidgetLabel
   orderType: 'ZtoA',// Order of the label, will override the config order of the label
   labelsPriority: '[teama,teamb]' // How the order the labels 
   storyIds: ['64a2d76b9503bc65ac531633','64a2d76b9503bc65ac531634'], // instead of using labels, u can also use stories Ids
   maxItemsCount: 10, // fetch only 10 items from the backend
   maxDisplayItemsCount: 1, // display only 1 
   theme: myTheme, // set the theme of the widget
}

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

perItemStyleOverrides : PerItemStyleOverrides

type EntitiesType = 'playerId' | 'teamId' | 'gameId';
type PerItemStyleOverrides = Record<EntitiesType, Array<{ name: string; theme: IWidgetTheme }>>;

The perItemStyleOverrides property in IWidgetViewOptions facilitates custom styling for individual items within a widget based on specific entity identifiers.

This feature enhances flexibility by allowing unique visual representations for each item within the widget.

Structure

The perItemStyleOverrides structure comprises an object with keys that identify entities within the widget, such as playerId, teamId, or gameId.

Each key corresponds to an array of objects, where each object defines custom styling for a specific entity.

Entity Identifier

An entity identifier, such as playerId, teamId, or gameId, specifies the particular entity to be styled individually within the widget.

Within the array, each object contains the following properties:

name: This property serves as a unique identifier or key associated with the entity. It distinguishes one entity from another within the widget.

theme: This property refers to an instance of IWidgetTheme, which defines customized styling for the specified entity. It encapsulates visual attributes like colors, fonts, and layout configurations tailored to the entity's representation.

perItemStyleOverrides: {
   "playerId": [
     {
       name: "35450",
       theme: rowCircleThemePlayer
     },
     {
       name: "28237",
       theme: rowCircleThemePlayer
     },
     {
       name: "46046",
       theme: rowCircleThemePlayer
     }
   ],
     "teamId": [
       {
         name: "real-madrid",
         theme: rowCircleThemeRealMadrid
       }
     ]
 }  

Theme(preset?: ThemeType): IWidgetTheme

Returns an IWIdgetTheme object with default theme preset

ParameterTypeRequiredDescription
presetThemeTypeNothe preset theme name like "grid-3-columns" / "row-circle"
contentType'story' | 'moment'NoIf not provided it will return a playerStyle of story.
const theme = BlazeSDK.Theme('row-rectangle','story');
const theme: IWidgetTheme = BlazeSDK.Theme('row-rectangle');

Theme Type

ValueDescription
row-circleA row layout with circular items.
row-rectangleA row layout with rectangular items.
grid-2-columnsA grid layout with 2 columns.
grid-3-columnsA grid layout with 3 columns.
row-rectangle-horizontalA horizontal row layout with rectangular items.
grid-2-columns-horizontalA horizontal grid layout with 2 columns.
grid-3-columns-horizontalA horizontal grid layout with 3 columns.
defaultThe default theme style - row-circle

setDoNotTrack(value: boolean): void

ParameterTypeRequiredDescription
valuebooleanYesThe value will set the "Do Not Track" feature to either false or true after the client has already created the widget(s) or initialized the SDK.
BlazeSDK.setDoNotTrack(true);

setExternalUserId(value: string): void

ParameterTypeRequiredDescription
valuestringYesThe value will set the "External User ID" feature, and send the id in all analytics events
BlazeSDK.setExternalUserId('1234');

setGeoLocation(value: string): void

ParameterTypeRequiredDescription
valuestringYesThe value will set the "GEO Location' feature - use country code like 'US' in order to see the geo send in the API request
BlazeSDK.setGeoLocation('IL')

pauseCurrentPlayer(): void

Pause the story in the opened modal.

 BlazeSDK.pauseCurrentPlayer();

resumeCurrentPlayer(): void

Resume the story in the opened modal.

 BlazeSDK.resumeCurrentPlayer();

LabelBuilder()

LabelBuilder provides a factory for creating label expressions for your Blaze widgets.

The label expressions can be single labels or combinations of labels with logical AND or OR conditions. You can simply use the static methods provided by LabelBuilder to create your expressions.

Usage:

  1. Creating a single label expression: singleLabel

    const singleLabel = BlazeSDK.LabelBuilder().singleLabel("Blue")
    

    This creates a label expression representing a single label "Blue".

  2. Creating an AND expression: mustInclude

    const andExpression = BlazeSDK.LabelBuilder().mustInclude("Blue", "Green")
    

    This creates a label expression representing the logical AND of the labels "Blue" and "Green". In other words, the expression is true if and only if both "Blue" and "Green" are present.

  3. Creating an OR expression: atLeastOneOf

    const orExpression = BlazeSDK.LabelBuilder().atLeastOneOf("Blue", "Green")
    

    This creates a label expression representing the logical OR of the labels "Blue" and "Green". In other words, the expression is true if either "Blue" or "Green" (or both) are present.

  4. Combining expressions:
    You can also combine the expressions using AND and OR operations. For example, you can create an expression that is true if "Red" and either "Blue" or "Green" are present:

    const blueOrGreen = BlazeSDK.LabelBuilder().atLeastOneOf("Blue", "Green")
    const combinedExpression = BlazeSDK.LabelBuilder().mustInclude(blueOrGreen, BlazeSDK.LabelBuilder().singleLabel("Red"))
    

    The BlazeSDK.LabelBuilder().singleLabel(a), BlazeSDK.LabelBuilder().mustInclude(a,b), and BlazeSDK.LabelBuilder().atLeastOneOf(a,b) methods return instances of BlazeWidgetLabel, which represents the label expressions.

addDelegateListener(sdkDelegation: Delegation, callbackFunc: Function) :void

ParameterTypeRequiredDescription
sdkDelegationDelegationYesSupport only 4 sdk delegations: onEventTriggered, onStoryPlayerDidAppear, onStoryPlayerDismissed, onErrorThrown
callbackFuncFunctionYesCallback function to handle the event
BlazeSDK.addDelegateListener(BlazeSDK.Delegations.onEventTriggered , (e) => { console.log("document onEventTriggered", e.detail) })
BlazeSDK.addDelegateListener(BlazeSDK.Delegations.onStoryPlayerDidAppear , (e) => { console.log("document onStoryPlayerDidAppear", e.detail) })
BlazeSDK.addDelegateListener(BlazeSDK.Delegations.onStoryPlayerDismissed , (e) => { console.log("document onStoryPlayerDismissed", e.detail) })
BlazeSDK.addDelegateListener(BlazeSDK.Delegations.onErrorThrown , (e) => { console.log("document onErrorThrown", e.detail) })

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) => CustomNativeTargeting;
}

provideAdExtraParams

method signature

function provideAdExtraParams(args: { path: string }): Record<string, string | string[]>;

// Usage example:
BlazeSDK.setGoogleCustomNativeAdsHandler({
  provideAdExtraParams: (args) => {
    return {
       "gdpr": "1",
       "age": ["1", "2"]
    }
}});

Description

Optional function that will be triggered every time a custom native ad request an ad.
Use this to customize how (and if) each user 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 CustomNativeAdHandler {  
  provideAdExtraParams?: () => ImaExtraParams;  
}

provideAdExtraParams

method signature

function provideAdExtraParams(): Record<string, string>;

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

Description

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


DataSourceBuilder

labels(params: LabelsDataSourceParams): BlazeDataSourceType

ParameterTypeRequiredDescription
params.labelsstring | string[] | BlazeWidgetLabelYesA string, array of strings, or BlazeWidgetLabel representing the labels.
params.labelsPriority?string | string[] | BlazeWidgetLabel[]NoA string, array of strings, or array of BlazeWidgetLabel for priority.
params.orderType?OrderTypeNoThe order type
params.maxItems?numberNoThe maximum number of items
 const dataSource = BlazeSDK.DataSourceBuilder().labels({
   labels: BlazeSDK.LabelBuilder().atLeastOneOf('top-stories', 'live-stories'),
   labelsPriority: `[${BlazeSDK.LabelBuilder().singleLabel('live-stories')}]`,
   orderType: 'RecentlyUpdatedFirst',
   maxItems: 4,
 });

ids(params: IdsDataSourceParams): BlazeDataSourceType

ParameterTypeRequiredDescription
params.idsstring[]YesAn array of strings representing the IDs.
params.orderType?OrderTypeNoThe order type,
const dataSource = BlazeSDK.DataSourceBuilder().ids({
   ids: ['1234','5678'],
   orderType: 'RecentlyUpdatedFirst',
 });
BlazeDataSourceType
PropertyTypeRequiredDescription
type'labels' | 'ids'YesThe type of data source, either 'labels' or 'ids'.
labelsstring string[]BlazeWidgetLabel ```NoA string, array of strings, or BlazeWidgetLabel representing the labels.
labelsPrioritystring | string[] | BlazeWidgetLabel[]NoA string, array of strings, or array of BlazeWidgetLabel for priority.
idsstring[]NoAn array of strings representing the IDs.
orderTypeOrderTypeNoThe order type
maxItemsnumberNoThe maximum number of items.

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

ParameterTypeRequiredDescription
storyIdstringYesthe ID of the story you would like to play
styleStoryPlayerStylenoif not provided, will use the default player style
const playerStyle = BlazeSDK.Theme('default').playerStyle;

BlazeSDK.playStory('66c0d0c6607d0c10cf3dd98d',playerStyle)

playStories(dataSource: BlazeDataSourceType, style?: StoryPlayerStyle ): void

ParameterTypeRequiredDescription
dataSourceBlazeDataSourceTypeYes
styleStoryPlayerStylenoif not provided, will use the default player style
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)