UI Components

The first thing you need to know is that websites need to obtain an opt-in from their visitors to send them push notifications. Choosing the right format and the right moment to ask for push notification permission is key to build a successful web push strategy.

There are several formats to choose from, each one adapted to different needs:

Alert: a customizable popup.
Banner: a simple banner.
Button: a button you can display in the bottom right or left corner of your website.
Native prompt: The native prompt, in case you don't want to use any of the above formats (fully secure mode only).

UI Components (except for popup) are automatically added to your web page once you configure them. Configuring a UI component allows you to override its behaviour, position or even translations. We'll detail what configuration options are supported for every builtin UI Component.

For example, here's how a button would work in the configuration:

batchSDK(['setup', {
  ...
  ui: {
    button: {
      corner: 'bottom left',
      backgroundColor: '#FFFFFF',
      hover: 'Subscribe to our notifications!',
    }
  }
});

When in fully secure mode, you have the possibility of asking for the browser's notification optin directly. A UI Component is required for the HTTP/Multidomain mode, as a click event is required to open a popup without it being caught by browser's builtin blockers.

Alert

Requires Batch SDK 2.0.0

The alert format is similar to popups you can get using alert(). It is not actually modal: the user is still able to interact with the content around it.

It can show up in any of the four corners, or can be centered on the top or the bottom of the page.

To enable it, add a child object of ui named alert.

Supported parameters:

Description

autoShow

Boolean - Optional Whether the component should show as soon as possible, or if it should wait for a manual 'show' API call. Default: true E.g.{"autoShow":false}

attach

String - Optional Where to attach the alert. Should be a mix of top|bottom and left|center|right. E.g.{"attach":"bottom left"}

icon

URL String - Optional Link to a square icon representing your website, which will show up on the left of the banner. The file must be a PNG or JPG image hosted on an HTTPS server. E.g.{"icon":"https://mydomain.com/icon.png"}

text

String - Optional Overrides the text that's displayed in the banner. E.g.{"text":"Never miss an update !"}

backgroundColor

Hex Color String - Optional Color of the banner's background. E.g.{"backgroundColor":"#646464"}

textColor

Hex Color String - Optional Color of the banner's text. E.g.{"textColor":"#646464"}

fontSize

Integer - Optional Font size. Unitless. E.g.{"fontSize":"12"}

fontFamily

String - Optional Overrides the font used in the banner. Works exactly like CSS' font-family attribute. E.g.{"fontFamily":"helvetica"}

btnBackgroundColor

Hex Color String - Optional Color of the button's background. E.g.{"btnBackgroundColor":"#646464"}

btnTextColor

Hex Color String - Optional Color of the button's text. E.g.{"btnTextColor":"#646464"}

btnHoverColor

Hex Color String - Optional Color of the button's hover state. E.g.{"btnHoverColor":"#646464"}

btnFontSize

Integer - Optional Font size of both buttons in px. Do not add the unit to the value. E.g.{"btnFontSize":"12"}

positiveSubBtnLabel

String - Optional Text override for when the positive button will subscribe the user. E.g.{"positiveSubBtnLabel":"Subscribe"}

positiveUnsubBtnLabel

String - Optional Text override for when the positive button will unsubscribe the user. E.g.{"positiveUnsubBtnLabel":"Unsubscribe"}

negativeBtnLabel

String - Optional Text override for when the negative button, which hides for popup temporarily, until the delay in `hideFor` has been reached. E.g.{"negativeBtnLabel":"Later"}

positiveBtnStyle

Button style configuration - Optional Style configuration for the positive ("Subscribe"/"Unsubscribe") button. See below for more info about this object. Note: When in unsubcribe mode, this button will always have a red background color. E.g.{"positiveBtnStyle":{"textColor":"red"}}

negativeBtnStyle

Button style configuration - Optional Style configuration for the negative ("Later") button. See below for more info about this object. E.g.{"negativeBtnStyle":{"textColor":"red"}}

extraBtn

'Extra' button configuration. Requires SDK v3. - Optional Both 'label' (Button text) and 'link' (link that will be opened in a new tab on click) attributes are required. A 'style' object can be provided in the same syntax as 'positive/negativeBtnStyle', CSS styling is also supported. E.g.{"extraBtn":{"label":"Privacy Policy","link":"https://batch.com/privacy-policy"}}

hideFor

Integer - Optional When closed, do not display the banner again until X seconds elapsed (default: 604800 or 7 days). Use a 0 value to hide the alert forever. E.g.{"hideFor":604800}

zIndex

Integer - Optional z-index of the component E.g.{"zIndex":999}

Alert button style configuration

Description

backgroundColor

Hex Color String - Optional Color of the button's background. E.g.{"backgroundColor":"#646464"}

hoverBackgroundColor

Hex Color String - Optional Color of the button's background when hovered. Falls back on `backgroundColor` if not specified. E.g.{"hoverBackgroundColor":"#646464"}

textColor

Hex Color String - Optional Color of the banner's text. E.g.{"textColor":"#646464"}

fontSize

Integer - Optional Font size in px. Do not specify an unit in this value. E.g.{"fontSize":"12"}

shadow

Boolean - Optional Whether this button should cast a shadow, or not. Default: true for the positive button, false for the negative one. E.g.{"shadow":false}

Example:

alert: {
    positiveBtnStyle: {
        backgroundColor: "blue",
        textColor: "white",
        fontSize: 25,
        shadow: true
    }
}

Banner

The banner shows up at the top of your webpage. It has an optional logo, a colorable button, and can be floating or fixed.

To enable it, add a child object of ui named banner.

Supported parameters:

Description

autoShow

Boolean - Optional Whether the component should show as soon as possible, or if it should wait for a manual 'show' API call. Default: true E.g.{"autoShow":false}

icon

text

String - Optional Overrides the text that's displayed in the banner. E.g.{"text":"Never miss an update !"}

fixed

Boolean - Optional Makes the banner push the webpage's content rather than float on top of it (default: False). E.g.{"fixed":true}

attachBottom

Boolean - Optional Makes the banner show on the bottom of the page, rather than on top. Forces 'fixed' to true (default: False). E.g.{"attachBottom":true}

backgroundColor

Hex Color String - Optional Color of the banner's background. E.g.{"backgroundColor":"#646464"}

textColor

Hex Color String - Optional Color of the banner's text. E.g.{"textColor":"#646464"}

fontSize

Integer - Optional Font size. Unitless. E.g.{"fontSize":"12"}

fontFamily

String - Optional Overrides the font used in the banner. Works exactly like CSS' font-family attribute. E.g.{"fontFamily":"helvetica"}

btnBackgroundColor

Hex Color String - Optional Color of the button's background. E.g.{"btnBackgroundColor":"#646464"}

btnTextColor

Hex Color String - Optional Color of the button's text. E.g.{"btnTextColor":"#646464"}

btnHoverColor

Hex Color String - Optional Color of the button's hover state. E.g.{"btnHoverColor":"#646464"}

btnFontSize

Integer - Optional Button's font size. Unitless. E.g.{"btnFontSize":"12"}

btnWidth

Integer - Optional Button width. Unitless. E.g.{"btnWidth":"200"}

btnSub

String - Optional Text override for when the button will subscribe the user. E.g.{"btnSub":"Subscribe"}

btnUnsub

String - Optional Text override for when the button will unsubscribe the user. E.g.{"btnUnsub":"Unsubscribe"}

hideFor

Integer - Optional When closed, do not display the banner again until X seconds elapsed (default: 604800 or 7 days). Use a 0 value to hide the banner forever. E.g.{"hideFor":604800}

zIndex

Integer - Optional z-index of the component E.g.{"zIndex":999}

Button

The Button UI Component shows a simple bell icon in the corner you want which, once clicked, show a pop-in with a customizable opt-in text, and a button to enable notifications.

To enable it, add a child object of ui named button.

Supported parameters:

Description

autoShow

Boolean - Optional Whether the component should show as soon as possible, or if it should wait for a manual 'show' API call. Default: true E.g.{"autoShow":false}

corner

String - Optional Corner to display the button in. Should be a mix of top

hover

String - Optional Override the text that appears when hovering the button. E.g.{"hover":"Never miss an update !"}

backgroundColor

Hex Color String - Optional Color of the button's background. E.g.{"backgroundColor":"#646464"}

foregroundColor

Hex Color String - Optional Color of the button's glyph. E.g.{"foregroundColor":"#646464"}

hoverColor

Hex Color String - Optional Color of the button's background on hover. E.g.{"hoverColor":"#646464"}

hoverForegroundColor

Hex Color String - Optional Color of the button's glyph on hover. E.g.{"hoverForegroundColor":"#646464"}

popin

Object - Optional Overrides the popin's properties.

title

String - Optional Override the pop-in's title. E.g.{"title":"Subscribe to notifications"}

btnSub

String - Optional Overrides the pop-in subscribe button text. E.g.{"btnSub":"Subscribe"}

btnUnsub

String - Optional Overrides the pop-in unsubscribe button text. E.g.{"btnUnsub":"Unsubscribe"}

example

Object - Optional Example notification to display instead of the placeholder. See 'Theming' for more info. E.g.{"example":{"body":"This is what a notification looks like"}}

title

String - Optional Override the pop-in's title. E.g.{"title":"Subscribe to notifications"}

btnSub

String - Optional Overrides the pop-in subscribe button text. E.g.{"btnSub":"Subscribe"}

btnUnsub

String - Optional Overrides the pop-in unsubscribe button text. E.g.{"btnUnsub":"Unsubscribe"}

example

Object - Optional Example notification to display instead of the placeholder. See 'Theming' for more info. E.g.{"example":{"body":"This is what a notification looks like"}}

title

String - Optional Override the pop-in's title. E.g.{"title":"Subscribe to notifications"}

btnSub

String - Optional Overrides the pop-in subscribe button text. E.g.{"btnSub":"Subscribe"}

btnUnsub

String - Optional Overrides the pop-in unsubscribe button text. E.g.{"btnUnsub":"Unsubscribe"}

example

Object - Optional Example notification to display instead of the placeholder. See 'Theming' for more info. E.g.{"example":{"body":"This is what a notification looks like"}}

zIndex

Integer - Optional z-index of the component E.g.{"zIndex":999}

Theming

The button theme supports full color customization of the button itself, but not the popin. Just like any other component attribute, just override the wanted value in the configuration object.

Here's what colors you can change on the button, with their property names:

You can also customize the placeholder notification in the popin, by specifying a example object under popin:

Description

icon

Image URL String - Optional URL of the image to display on the left of the example notification. E.g.{"icon":"https://path/to/your/image.jpg"}

title

String - Required Notification title text. E.g.{"title":"Test title"}

body

String - Required Notification body text. E.g.{"body":"Test body"}

Example:

button: {
    corner: 'bottom left',
    popin: {
        example: {
            icon: 'https://path/to/your/icon.jpg',
            title: 'Test title',
            body: 'Test body'
        }
    }
}

Native prompt

In case you don't want to use Batch's formats, you can trigger the native prompt of each browser. That permission request can be shown 3 times a week (more information here). Please note this will only work if you are using the fully secure mode.

To enable it, add a child object of ui named native.

Supported parameters:

Description

autoShow

Boolean - Optional Whether the component should show as soon as possible, or if it should wait for a manual 'show' API call. Default: true E.g.{"autoShow":false}

backoffDuration

Integer - Optional Time, in seconds. Allows you to set a delay between each display of the native prompt. Default: 86400 E.g.{"backoffDuration":86400}

Example:

native: {
    "backoffDuration": 86400
}

Toggling visibility programmatically

Starting with Batch SDK 2.0.0, you can programatically control the display of builtin UI components.

Two methods are available on the public API: ui.show, and ui.hide. They take as a parameter the name of a UI component that has been configured earlier, in the SDK setup:

batchSDK('ui.show', 'alert')
batchSDK('ui.hide', 'alert')
// or
batchSDK((api) => {
  api.ui.show('alert')
})
batchSDK((api) => {
  api.ui.hide('alert')
})

Most components will be shown as soon as possible. In order to make them wait for your show call, please refer to the configuration of the UI component you're trying to tweak: look for the autoShow key.

Note that some UI components might chose not to display even if you tell them to. Reasons can be:

The user is already subscribed to notifications
The user dismissed the UI element, and the minimum time between two dismissal (controlled by the hideFor configuration key) has not been reached.

In these cases, you can use the second "force" parameter, which allows you to force the display:

batchSDK('ui.show', 'alert', true)

PreviousMigrating from v3 NextProfile Data

Last updated 22 days ago

Was this helpful?