blaze sdk
Methods
| Parameter | Type | Required | Description |
|---|---|---|---|
| apiKey | string | Yes | the API key |
| options.doNotTrack? | boolean | no | It will set do not track feature |
| options.externalUserId? | string | no | it will set the external user ID feature |
| options.geoLocation? | string | no | it will set the geolocation feature globally |
| options.runInShadowDom? | boolean | no | TODO |
| options.shouldModifyUrlWithStoryId? | boolean | no | it will prevent the SDK from modifying the page URL |
| options.playerStyleCustomization? | Partial TODO | no | Set global style on the player |
| options.prefetchingPolicy? | TODO | no | default is the value if not defined |
| options.shouldAllowHorizontalStories | boolean | no | TODO |
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
| Parameter | Type | Required | Description |
|---|---|---|---|
| apiKey | string | Yes | the API key |
| options.doNotTrack? | boolean | no | It will set do not track feature |
| options.externalUserId? | string | no | it will set the external user ID feature |
| options.geoLocation? | string | no | it will set the geolocation feature globally |
| options.runInShadowDom? | boolean | no | It will run the SDK inside a shadow dom. default = true |
| options.shouldModifyUrlWithStoryId? | boolean | no | it will prevent the SDK from modifying the page URL |
| options.playerStyleCustomization? | Partial | no | Set global style on the player |
| options.prefetchingPolicy? | string - 'low' | 'default' | no | default is the value if not defined |
| options.shouldAllowHorizontalStories | boolean | no | If 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
| Level | Description |
|---|---|
| Low | Initially, no pre-fetch While playing, the next page of the currently playing story, and the first unread page of the next story |
| Default | Initially, 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. |
| Level | Description |
|---|---|
| Low | Initially, no pre-fetch TODO |
| Default | Initially, 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
| Parameter | Type | Required | Description |
|---|---|---|---|
| containerId | string | Yes | the widget will be appended into the HTML element with the given container ID |
| options? | IWidgetViewOptions | No | optional parameter. Here you can determine the labels and theme for the created view |
| options.dataSource | BlazeDataSourceType | if not labels or storyIds provided | |
| options.labels | string~~string[]~~\BlazeWidgetLabel | If storyIds was not specified | array of strings is depreacted but still supported, string as value or create your labels with LabelBuilder ( see below) |
| options.storyIds | string[] | If labels was not specified | depreacted - 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.contentIds | string[] | 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 story | In order to use specific content, it is recommended to set it |
| options.labelsPriority? | string | No | The 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? | string | No | you can pass your own theme object to this specific view |
| options.maxItemsCount? | number | No | Specify the max items to fetch from server |
| options.maxDisplayItemsCount? | number | No | Specify the max items to display. You can display 3 items while having 10 items returned from server. |
| options.orderType? | string | No | Specify 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? | PerItemStyleOverrides | no | 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. |
| options.shouldOrderWidgetByReadStatus? | boolean | no | If 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 |
| Parameter | Type | Required | Description |
|---|---|---|---|
| containerId | string | Yes | the widget will be appended into the HTML element with the given container ID |
| options? | IWidgetViewOptions | No | optional parameter. Here you can determine the labels and theme for the created view |
| options.dataSource | BlazeDataSourceType | if not labels or storyIds provided | |
| options.labels | string~~string[]~~\BlazeWidgetLabel | If storyIds was not specified | array of strings is depreacted but still supported, string as value or create your labels with LabelBuilder ( see below) |
| options.storyIds | string[] | If labels was not specified | depreacted - 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.contentIds | string[] | 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 story | In order to use specific content, it is recommended to set it |
| options.labelsPriority? | string | No | The 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? | string | No | you can pass your own theme object to this specific view |
| options.maxItemsCount? | number | No | Specify the max items to fetch from server |
| options.maxDisplayItemsCount? | number | No | Specify the max items to display. You can display 3 items while having 10 items returned from server. |
| options.orderType? | string | No | Specify 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? | PerItemStyleOverrides | no | 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. |
| options.shouldOrderWidgetByReadStatus? | boolean | no | If 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
| Parameter | Type | Required | Description |
|---|---|---|---|
| preset | ThemeType | No | the preset theme name like "grid-3-columns" / "row-circle" |
| contentType | 'story' | 'moment' | No | If 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
| Value | Description |
|---|---|
| row-circle | A row layout with circular items. |
| row-rectangle | A row layout with rectangular items. |
| grid-2-columns | A grid layout with 2 columns. |
| grid-3-columns | A grid layout with 3 columns. |
| row-rectangle-horizontal | A horizontal row layout with rectangular items. |
| grid-2-columns-horizontal | A horizontal grid layout with 2 columns. |
| grid-3-columns-horizontal | A horizontal grid layout with 3 columns. |
| default | The default theme style - row-circle |
setDoNotTrack(value: boolean): void
| Parameter | Type | Required | Description |
|---|---|---|---|
| value | boolean | Yes | The 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
| Parameter | Type | Required | Description |
|---|---|---|---|
| value | string | Yes | The value will set the "External User ID" feature, and send the id in all analytics events |
BlazeSDK.setExternalUserId('1234');
setGeoLocation(value: string): void
| Parameter | Type | Required | Description |
|---|---|---|---|
| value | string | Yes | The 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:
-
Creating a single label expression: singleLabel
const singleLabel = BlazeSDK.LabelBuilder().singleLabel("Blue")This creates a label expression representing a single label "Blue".
-
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.
-
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.
-
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), andBlazeSDK.LabelBuilder().atLeastOneOf(a,b)methods return instances ofBlazeWidgetLabel, which represents the label expressions.
addDelegateListener(sdkDelegation: Delegation, callbackFunc: Function) :void
| Parameter | Type | Required | Description |
|---|---|---|---|
| sdkDelegation | Delegation | Yes | Support only 4 sdk delegations: onEventTriggered, onStoryPlayerDidAppear, onStoryPlayerDismissed, onErrorThrown |
| callbackFunc | Function | Yes | Callback 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
| Parameter | Type | Required | Description |
|---|---|---|---|
| params.labels | string | string[] | BlazeWidgetLabel | Yes | A string, array of strings, or BlazeWidgetLabel representing the labels. |
| params.labelsPriority? | string | string[] | BlazeWidgetLabel[] | No | A string, array of strings, or array of BlazeWidgetLabel for priority. |
| params.orderType? | OrderType | No | The order type |
| params.maxItems? | number | No | The 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
| Parameter | Type | Required | Description |
|---|---|---|---|
| params.ids | string[] | Yes | An array of strings representing the IDs. |
| params.orderType? | OrderType | No | The order type, |
const dataSource = BlazeSDK.DataSourceBuilder().ids({
ids: ['1234','5678'],
orderType: 'RecentlyUpdatedFirst',
});
BlazeDataSourceType
| Property | Type | Required | Description | ||
|---|---|---|---|---|---|
| type | 'labels' | 'ids' | Yes | The type of data source, either 'labels' or 'ids'. | ||
| labels | string | string[] | BlazeWidgetLabel ``` | No | A string, array of strings, or BlazeWidgetLabel representing the labels. |
| labelsPriority | string | string[] | BlazeWidgetLabel[] | No | A string, array of strings, or array of BlazeWidgetLabel for priority. | ||
| ids | string[] | No | An array of strings representing the IDs. | ||
| orderType | OrderType | No | The order type | ||
| maxItems | number | No | The maximum number of items. |
playStory(storyId: string, style?: StoryPlayerStyle ): void
| Parameter | Type | Required | Description |
|---|---|---|---|
| storyId | string | Yes | the ID of the story you would like to play |
| style | StoryPlayerStyle | no | if not provided, will use the default player style |
const playerStyle = BlazeSDK.Theme('default').playerStyle;
BlazeSDK.playStory('66c0d0c6607d0c10cf3dd98d',playerStyle)
playStories(dataSource: BlazeDataSourceType, style?: StoryPlayerStyle ): void
| Parameter | Type | Required | Description |
|---|---|---|---|
| dataSource | BlazeDataSourceType | Yes | |
| style | StoryPlayerStyle | no | if 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)
Updated about 1 year ago
