Web Push Draft (New)

A step-by-step guide to configuring Web Push opt-in

Web Push Notifications are clickable media messages that are sent to a user's desktop, mobile, or tablet through a website or web app, even when they're inactive your the site. This makes Browser Push Notifications highly visible and easy to respond to for a user.

Web Push is supported by all major browsers like Chrome, Firefox, Safari (only on Mac OS X Maverick & higher versions), Microsoft Edge, Opera, UC Browser. However, media messages or notifications containing images are currently supported only by Chrome.

We recommend that you leverage the channel to communicate time-bound messages, reactivate dormant users, and re-engage users who dropped off from your site mid-way in their lifecycle. However, users need to explicitly opt-in to receive messages from your domain. Thus, setting up and collecting user opt-ins is the first step to start using the channel.

Once you've set up Web Push opt-in, you can start engaging subscribed users with contextually personalized notifications!

Here's how you can go about it:

🚧

Please Ensure That Your Website is Integrated with WebEngage Before Proceeding

Getting Started with Web SDK Integration

Step 1: Enable Web Push

As shown above, head over to Integrations > Channels > Web Push in your dashboard and click the toggle button to enable Web Push Notifications for your domain.

Step 2: Select Opt-in Type

Depending on whether or not you have an HTTPS domain, Web Push opt-ins can be collected in two ways:

  • Directly through Browser-based opt-in prompts. (1-Step Opt-in)*
  • In-directly through an On-site Notification (shown by WebEngage) that initiates the opt-in process. Users are then led to the Native Browser opt-in prompt to complete the subscription. (2-Step Opt-in)

Let's quickly walk you through how these opt-in models work:

How 1-Step Opt-in Works

(works for only HTTPS websites/ sites that have SSL Certificate)

Here's what a 1-step opt-in native browser prompt looks like

The opt-in model enables users to subscribe by simply clicking the Allow button on the native prompt shown by their browser.

πŸ‘

Highly recommended if you have an HTTPS domain as users can receive notifications from your custom sub-domain! Opt-in prompts can be customized too. (Step-by-step guide to configuring)

How 2-Step Opt-in Works

(works for both HTTP & HTTPS domains)

Since Web Push Notifications are not supported for HTTP sites, we created the 2-step opt-in model to enable messaging for such domains. For the same reason, users will be subscribed to a WebEngage domain like mywebsite.webengagepush.com, and not your domain.

Here's what the on-site notification and native browser prompts look like for 2-step opt-in

This model requires users to subscribe to your channel in 2 steps:

Step 1: User is prompted by an intermediary On-site Notification (triggered by WebEngage) that conveys why they should subscribe to your Web Push Notifications.

  • Once they click the Allow button on the On-site Notification, the user is prompted by the browser-based native prompt.

Step 2:*** The user will need to click the Allow button* on the second prompt to confirm their subscription.

πŸ‘

Highly recommended if you have an HTTP domain. (Step-by-step guide to configuring)

(HTTPS websites can choose to set it up if they prefer having users subscribed to a WebEngage domain instead of their own.)

Configuring 1-Step Opt-in

As shown above, here are a few mandatory steps to enable 1-step opt-in for your users:

Step 1: Add FCM Server Key

The FCM Server Key is a secret code of sorts that enables your WebEngage dashboard to communicate with your Firebase Project.

  • It can be found under the Firebase Project > Project Settings > Cloud Messaging section in your Firebase Developers Console.
  • Copy + paste it in your WebEngage dashboard.

Step 2: Upload Icon & Badge

(Badge is applicable only to Chrome v56+ x Android v6+)

As highlighted in the above visual:

Step 2.1: Upload your site icon. It'll be shown in all your Web Push Notifications by default.

  • You can always choose to add a dynamically personalized icon while creating the campaign. (Step-by-step guide)

Step 2.2: You can also choose to show your custom site badge (instead of Chrome's logo) in Web Push Notifications that are delivered to Chrome x Android users by uploading it here. (Or you could add it while creating the Web Push campaign.)

  • A few guidelines for uploading the custom badge:
    • The badge must be monochrome as RGB colors are not supported by the OS-browser.
    • We recommend a width:height ratio of 1:1 with the ideal image size being 72px by 72px.
    • Please upload the image in .png, .gif, .webp, .ico, .cur, .bmp formats only, in a file size not exceeding 1MB.

Step 3: Add Code in service.worker.js File

importScripts('https://ssl.widgets.webengage.com/js/service-worker.js');

Add the above code snippet in the service-worker.js file under the root directory of your website.

  • Please create a service worker file if it doesn't exist.
  • Please ensure that the service-worker.js file is publicly accessible to ensure that you can send Web Push campaigns through your WebEngage dashboard.
  • If you’re already registering your own service worker, then please set webpush.registerServiceWorker to false so that WebEngage can stop registering the same service worker. (How to implement configuration flags)

🚧

Congratulations!

Web Push Opt-in has been set up for your account! You can now start creating Web Push campaigns for all your subscribers.

OR

Continue setting up optional configurations

Step 4 (Optional): Select Opt-in Prompt Type

By default, all 1-Step Opt-In prompts are shown as native browser prompts. However, you can choose to customize the way it appears by selecting and customizing a prompt style from the section, Opt-in Prompt: Type of Prompt to Show.

As shown above:

Step 1: Click the Edit icon placed next to the field, Opt-in Prompt Type.

Step 2: Select a style - Native/ Box/ Bell/ Custom.

Let's quickly walk you through all the prompt styles:

Native

As shown above, the native browser prompt will appear on the top left under the search bar of the browser. Users will need to click on the Allow button to subscribe to your Web Push Notifications.

Customizing Native Prompt

Enable Show Overlay With Hint to block the screen background and draw attention to the prompt with a message. In doing so, users will experience the Box Prompt as shown below.

🚧

Skip to Step 5: Define When & Where to Show

Box

As shown above, users will first see a Box Prompt on the top-center of their screen, nudging them to subscribe to your channel.

  • If the user clicks the Allow button on the prompt, they will be shown the Native Browser Prompt.
  • The user will need to confirm their subscription by clicking the Allow button on the native prompt.
  • If a user clicks Allow on the Box Prompt and Don't Allow on Native Browser Prompt, then they will remain unsubscribed.

Customizing Box Prompt

Let's quickly walk you through how you can customize the Box Prompt's appearance, text, and functionality as per your needs.

As shown above:

Step 1: Customize the bell icon's position by selecting an option from the field, Position.

Step 2: Add a custom message for the prompt in the field, Message.

Step 3: Change the Allow Button Text to something more warm and friendly.

Step 4: Change the Don't Allow Button Text to something less dismissive.

Step 5: Customize the Box Prompt's background and text as per your brand guidelines through the fields, Background Color, and Text Color, respectively.

Step 6 (Important): Determine what happens when a user clicks the Don't Allow Button on the Box Prompt. (By default, we will continue to them the opt-in prompt each time they visit your website or specified webpage/s.)

πŸ“˜

The following options can be selected here:

  • Never show opt-in prompt again

  • Show opt-in prompt in a new session

  • Show opt-in prompt after a time delay of

  • Continue to show opt-in prompt

Step 5: Enable Show Overlay to block the screen background and draw attention to the Box Prompt. In doing so, users will experience the Box Prompt as shown below.

🚧

Skip to Step 5: Define When & Where to Show

Bell

As shown above, users will first see a Bell Prompt nudging them to subscribe to your channel.

  • If they click the Allow button on the prompt, they will be shown the Native Browser Prompt.
  • Users will need to confirm their subscription by clicking the Allow button on the native prompt.

Customizing Bell Prompt

As shown above:

Step 1: Define Bell icon's position by selecting an option from the field, Position.

Step 2: Customize Bell icon's color by selecting a shade from the Bell Background Color palette.

🚧

Skip to Step 5: Define When & Where to Show

Custom

You can control how and when the Native Browser Prompt is shown to your users by selecting this option.

However, in this case, WebEngage will not show the prompt to your users, we will only register the service worker. You will need to use our JavaScript API to customize, trigger, and show the prompt to nudge users to subscribe.

Step 5 (Optional): Define When & Where To Show

This section enables you to specify the context in which a user must be shown the opt-in prompt and the page(s) on which it must be displayed. Here's how you can configure it:

Step 5.1: Define Whom To 'Show To'

By default, the Web Push opt-in prompt is shown to all your users. However, you can choose to narrow down the target audience by specifying a segment that you'd like to target with the prompts.

  • As shown above, you can select a segment from the dropdown.
  • This setting can be changed anytime you like and will not affect the existing list of subscribers.

🚧

Haven't Created a Segment Yet?

Let's get you started!

Step 5.2: Define Where To 'Show On'

  • Select All Pages to show the opt-in prompt as soon as a user lands on a webpage

  • Select Specific Page to selectively curate only those users as subscribers who visit certain pages of your website (How to define)

  • Select Occurrence of Event to selectively curate only those users as subscribers who perform certain actions on your website (How to define)

Show on Specific Page

You can choose the web pages (specifically the URLs) where you’d like to show the prompt - either all your web pages or only some specific page eg. the product review pages where the user is likely to subscribe to your notifications given that a user reading reviews is a highly engaged user who is interested in your product/service.

Step 1: Add Page URL

Step 2: Combine Multiple URLs with AND/OR Logic

As shown above, you can choose to specify multiple pages on which the opt-in prompt must be shown by clicking the Add Rule Button. In doing so, you will be able to combine the URLs by AND/OR Logic.

🚧

How It Works: Combining Page URLs by AND/OR Logic

AND: Implies that only those users will be shown the Web Push opt-in prompt who have visited all the defined URLs (helping you narrow down the target audience).

OR: Implies that all users who visit either of the defined URLs will be shown the Web Push opt-in prompt (helping you widen the target audience).

Show on Occurrence of Event

🚧

Must Read

Please ensure that you have a robust understanding of Events and Event Attributes before proceeding. Doing so will help you understand this section, better.

Selecting this option enables you to show the opt-in prompt whenever an event happens eg. whenever the user purchases something when he is likely to subscribe to your notifications given that a successful transaction has taken place.

Step 1: Select Event

As shown above, click the dropdown to select from a list of all the Custom Events and System Events being tracked for your dashboard.

Step 2: Define Scope of Occurrence by Adding Event Attribute Filters

You can further define the scope of occurrence of the Event by adding Event Attribute filters to it.

  • As shown above, multiple Event Attributes can be combined by the AND/OR Logic.

🚧

How It Works: Combining Event Attribute Filters by AND/OR Logic

AND: Implies that the Web Push opt-in prompt will be shown only to those users who perform the Event in the context of all the Event Attributes. (Helps you narrow down the target audience)

OR: Implies that the Web Push opt-in prompt will be shown to all users who perform the Event in the context of any one of the Event Attributes. (Helps you widen the target audience)

For example, in the above visual we have chosen to show the opt-in prompt to only those users who perform the Event, where

Step 3: Combine Multiple Events with AND/OR Logic

You can choose to specify multiple Events, on the occurrence of which the opt-in prompt must be shown to the user.

  • As shown above, click on the Add Event Button to select more Events.
  • In doing so, you will be able to combine the Events by the AND/OR Logic.

🚧

How It Works: Combining Events by AND/OR Logic

AND: Implies that the Web Push opt-in prompt will be shown only to those users who perform all the specified Events, in the context of the Event Attributes added to each one (if any). (Helps you narrow down the target audience)

OR: Implies that the Web Push opt-in prompt will be shown to all users who perform any one of the specified Events, in the context of the Event Attributes added to it (if any). (Helps you widen the target audience)

  • For example, in the above visual, we have chosen to show the opt-in prompt to only those who perform both the Events,

Step 5.3: Add Time Delay

(Not applicable if Event Occurrence is selected at Step 5.2: Where to 'Shown On')

You can choose to delay the appearance of the opt-in prompt by a few seconds after a user lands on a webpage. As highlighted below, specify the duration and you're good to go!

Step 5.4: Define Scroll %

(Not applicable if Event Occurrence is selected at Step 5.2: Where to 'Shown On')

You can choose to contextually show the Web Push opt-in prompt to users only once they've scrolled through a certain percentage of your webpage. This is a great way to capitalize on user intent and show the opt-in prompt to only high-intent users (as they've expressed interest by scrolling down to a specific section of the webpage).

As highlighted in the above visual, specify the percentage and you're good to go!

Step 5.5: Define 'Maximum Times' Message Can Be Shown

(Not applicable if Event Occurrence is selected at Step 5.2: Where to 'Shown On')

It's not always a good idea to keep nudging a user to opt-in until they half-heartedly give in, or abandon your website completely. This is why we've made it possible for you to set an upper cap on the number of times a user can be nudged to opt-in to your Web Push Notifications.

  • As highlighted in the above visual, specify the upper cap and you're all set!

  • Once the upper cap is met, the user will not be nudged to opt-in ever again on a device. However, if they visit your website (or a specific webpage) through a new device, then they'll be prompted to opt-in again.

Step 6 (Optional): Configure Opt-in Acknowledgement

By default, no subscription acknowledgment is sent to users once they've opted-in to your channel. Using this section, you can set up a custom notification to welcome users to your subscribers' community.

Here's how you can go about it:

Step 1: Click the toggle switch to enable the acknowledgment notification.

Step 2: Customize the Title and Message as per your engagement strategy.

Step 3: Upload a custom icon (warm, friendly and welcoming image recommended!)

Step 7 (Optional): Add Service Worker Path

We assume that your service worker file is located in the root directory of your website with the filename service-worker.js. If this is not the case, then you can change the directory path and filename settings by adding it under the section, Advanced: Service Worker Path (as highlighted below).

Configuring 2-Step Opt-in

As shown above, here are a few mandatory steps to enable 2-step opt-in for your users:

Step 1: Add Sub-Domain Name

When you switch the Web Push toggle on, you will notice that 2-step opt-in is selected by default with a pre-filled Sub-Domain, based on your project's name in WebEngage. It can be changed to any sub-domain name you like.

Step 2: Upload Icon & Badge

(Badge is applicable only to Chrome v56+ x Android v6+)

As highlighted in the above visual:

Step 2.1: Upload your site icon. It'll be shown in all your Web Push Notifications by default.

  • You can always choose to add a dynamically personalized icon while creating the campaign. (Step-by-step guide)

Step 2.2: You can also choose to show your custom site badge (instead of Chrome's logo) in Web Push Notifications that are delivered to Chrome x Android users by uploading it here. (Or you could add it while creating the Web Push campaign.)

  • A few guidelines for uploading the custom badge:
    • The badge must be monochrome as RGB colors are not supported by the OS-browser.
    • We recommend a width:height ratio of 1:1 with the ideal image size being 72px by 72px.
    • Please upload the image in .png, .gif, .webp, .ico, .cur, .bmp formats only, in a file size not exceeding 1MB.

🚧

Congratulations!

Web Push Opt-in has been set up for your account! You can now start creating Web Push campaigns for all your subscribers.

OR

Continue setting up optional configurations for 2-Step Opt-in Model

Step 3 (Optional): Configure WebEngage On-site Notification

By default, the WebEngage On-site Notification that initiates Web Push opt-in for a user is shown on the bottom left of their screen as a bell prompt. You can choose to configure its message, position, and look and feel through this section.

Here's how you can go about it:

Step 1: Customize the notification position by selecting an option from the field, Position.

Step 2: Add a custom message for the prompt in the field, Message.

Step 3: Change the Allow Button Text to something more warm and friendly.

Step 4: Change the Don't Allow Button Text to something less dismissive.

Step 5: Customize the prompt's background and text as per your brand guidelines through the fields, Background Color, and Text Color, respectively.

Step 6 (Important): Determine what happens if a user clicks the Don't Allow Button. (By default, we will continue to them the opt-in prompt each time they visit your website or specified webpage/s.)

πŸ“˜

The following options can be selected here:

  • Never show opt-in prompt again

  • Show opt-in prompt in a new session

  • Show opt-in prompt after a time delay of

  • Continue to show opt-in prompt

Step 4 (Optional): Define When & Where to Show

By default, the Onsite Notification prompt is shown to all users as soon as they start their session on any webpage. It's shown each time an unsubscribed user re-visits your site.

Using this section, you can modify the default settings by specifying:

  • The type of users that must be engaged with the prompt. (How it works)
  • The context (When) in which a user must be shown the opt-in prompt. (How it works)
  • The page(s) on which it must be displayed (Where), (How it works)

Here's how you can configure it:

Step 4.1: Define Whom To 'Show To'

By default, the Web Push opt-in prompt is shown to all your users. However, you can choose to narrow down the target audience by specifying a segment that you'd like to target with the prompts.

  • As shown above, you can select a segment from the dropdown.
  • This setting can be changed anytime you like and will not affect the existing list of subscribers.

🚧

Haven't Created a Segment Yet?

Let's get you started!

Step 4.2: Define Where To 'Show On'

  • Select All Pages to show the opt-in prompt as soon as a user lands on a webpage

  • Select Specific Page to selectively curate only those users as subscribers who visit certain pages of your website (How to define)

Show on Specific Page

You can choose the web pages (specifically the URLs) where you’d like to show the prompt - either all your web pages or only some specific page eg. the product review pages where the user is likely to subscribe to your notifications given that a user reading reviews is a highly engaged user who is interested in your product/service.

Step 1: Add Page URL

Step 2: Combine Multiple URLs with AND/OR Logic

As shown above, you can choose to specify multiple pages on which the opt-in prompt must be shown by clicking the Add Rule Button. In doing so, you will be able to combine the URLs by AND/OR Logic.

🚧

How It Works: Combining Page URLs by AND/OR Logic

AND: Implies that only those users will be shown the Web Push opt-in prompt who have visited all the defined URLs (helping you narrow down the target audience).

OR: Implies that all users who visit either of the defined URLs will be shown the Web Push opt-in prompt (helping you widen the target audience).

Show on Occurrence of Event

🚧

Must Read

Please ensure that you have a robust understanding of Events and Event Attributes before proceeding. Doing so will help you understand this section, better.

Selecting this option enables you to show the opt-in prompt whenever an event happens eg. whenever the user purchases something when he is likely to subscribe to your notifications given that a successful transaction has taken place.

Step 1: Select Event

As shown above, click the dropdown to select from a list of all the Custom Events and System Events being tracked for your dashboard.

Step 2: Define Scope of Occurrence by Adding Event Attribute Filters

You can further define the scope of occurrence of the Event by adding Event Attribute filters to it.

  • As shown above, multiple Event Attributes can be combined by the AND/OR Logic.

🚧

How It Works: Combining Event Attribute Filters by AND/OR Logic

AND: Implies that the Web Push opt-in prompt will be shown only to those users who perform the Event in the context of all the Event Attributes. (Helps you narrow down the target audience)

OR: Implies that the Web Push opt-in prompt will be shown to all users who perform the Event in the context of any one of the Event Attributes. (Helps you widen the target audience)

For example, in the above visual we have chosen to show the opt-in prompt to only those users who perform the Event, where

Step 3: Combine Multiple Events with AND/OR Logic

You can choose to specify multiple Events, on the occurrence of which the opt-in prompt must be shown to the user.

  • As shown above, click on the Add Event Button to select more Events.
  • In doing so, you will be able to combine the Events by the AND/OR Logic.

🚧

How It Works: Combining Events by AND/OR Logic

AND: Implies that the Web Push opt-in prompt will be shown only to those users who perform all the specified Events, in the context of the Event Attributes added to each one (if any). (Helps you narrow down the target audience)

OR: Implies that the Web Push opt-in prompt will be shown to all users who perform any one of the specified Events, in the context of the Event Attributes added to it (if any). (Helps you widen the target audience)

  • For example, in the above visual, we have chosen to show the opt-in prompt to only those who perform both the Events,

Step 4.3: Add Time Delay

(Not applicable if Event Occurrence is selected at Step 5.2: Where to 'Shown On')

You can choose to delay the appearance of the opt-in prompt by a few seconds after a user lands on a webpage. As highlighted below, specify the duration and you're good to go!

Step 4.4: Define Scroll %

(Not applicable if Event Occurrence is selected at Step 5.2: Where to 'Shown On')

You can choose to contextually show the Web Push opt-in prompt to users only once they've scrolled through a certain percentage of your webpage. This is a great way to capitalize on user intent and show the opt-in prompt to only high-intent users (as they've expressed interest by scrolling down to a specific section of the webpage).

As highlighted in the above visual, specify the percentage and you're good to go!

Step 4.5: Define 'Maximum Times' Message Can Be Shown

(Not applicable if Event Occurrence is selected at Step 5.2: Where to 'Shown On')

It's not always a good idea to keep nudging a user to opt-in until they half-heartedly give in, or abandon your website completely. This is why we've made it possible for you to set an upper cap on the number of times a user can be nudged to opt-in to your Web Push Notifications.

  • As highlighted in the above visual, specify the upper cap and you're all set!

  • Once the upper cap is met, the user will not be nudged to opt-in ever again on a device. However, if they visit your website (or a specific webpage) through a new device, then they'll be prompted to opt-in again.

Step 5 (Optional): Configure New Window with Native Browser Prompt for Opt-in

Once a user clicks the Allow Button on the WebEngage On-site Notification, they are asked to confirm their subscription through a Native Browser Prompt that's shown in a new window.

As shown above, you can choose to copy the message that is shown in the WebEngage On-site Notification prompt, here. Or you could craft a brand new one. Here's how you can customize it:

Step 1: Add your Message.

Step 2: Upload an Icon (warm, friendly and welcoming image recommended!)

Step 3: Customize the background and text color as per your brand guidelines through the fields, Background Color, and Text Color, respectively.

Step 6 (Optional): Configure Acknowledgement

By default, no subscription acknowledgment is sent to users once they've opted-in to your channel. Using this section, you can set up a custom notification to welcome users to your subscribers' community. Here's how you can go about it:

Step 1: Click the toggle switch to enable the acknowledgment notification.

Step 2: Customize the Title and Message as per your engagement strategy.

Step 3: Upload a custom icon (warm, friendly and welcoming image recommended!)

Changing Opt-in Type

You can always choose to change the way users opt-in to your Web Push Notifications from 2-Step Opt-in to 1-Step Opt-in and vice-versa. However, do keep in mind that doing so causes the loss of your existing subscriber database. Subscribers will be prompted to resubscribe to your channel if the opt-in model is changed. Hence, we recommend that you do so only when deemed necessary.

Here's how you can go about it:

Click to enlarge

As shown above:

Step 1: Click the Reset button placed on the bottom right of the Configuration section.

  • In doing so, you will be prompted to confirm your decision.

Step 2: Click Reset on the pop-up to change the existing opt-in model.

Step 3: Select your preferred Opt-in Type and configure it.

🚧

Continue Setting up New Opt-in Model

Configuring 1-Step Opt-in

Configuring 2-Step Opt-in

We hope this has enabled you to configure Web Push Opt-ins for your account. Please feel free to drop in a few lines at [email protected] in case you have any queries or feedback. We're always just an email away!

Updated 8 months ago


Web Push Draft (New)


A step-by-step guide to configuring Web Push opt-in

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.