Soft push prompt

It’s often a good idea for sites to implement a “soft” push prompt where you “prime” the user and make your case for sending them push notifications before requesting push permission. This is useful because the browser throttles how often you may prompt the user directly, and if the user denies permission you can never ask them again. This article covers modifying your Web SDK integration to create a push primer campaign for your web application.

tip:

This can be done without SDK customization using our new no code push primer.

Alternatively, if you would like to include special custom handling, instead of calling requestPushPermission() directly as described in the standard Web push integration, use Braze’s triggered in-app messages:

note:

This guide uses code samples from v4 of the Braze Web SDK. If you’re not yet on v4 please follow our upgrade guide.

Step 1: Create a push primer campaign

First, you must create a “Prime for Push” in-app messaging campaign in the Braze dashboard:

Create a Modal in-app message and give it whatever text and styling you would like.
Next, set the on-click behavior to Close Message. This behavior will be customized later.
Add a key-value pair to the message where the key is msg-id, and the value is push-primer.
Assign a custom event trigger action (i.e., “prime-for-push”) to the message. You can create the custom event manually from the dashboard if needed.

Step 2: Remove calls

In your Braze SDK integration, find and remove any calls to automaticallyShowInAppMessages() from within your loading snippet.

Step 3: Update integration

Finally, replace the removed call with the following snippet:

import * as braze from "@braze/web-sdk";
// Be sure to remove any calls to braze.automaticallyShowInAppMessages()
braze.subscribeToInAppMessage(function(inAppMessage) {
  // check if message is not a control variant
  if (inAppMessage instanceof braze.inAppMessage) {
    // access the key-value pairs, defined as `extras`
    const keyValuePairs = inAppMessage.extras || {};
    // check the value of our key `msg-id` defined in the Braze dashboard
    if (keyValuePairs["msg-id"] === "push-primer") {
      // We don't want to display the soft push prompt to users on browsers
      // that don't support push, or if the user has already granted/blocked permission
      if (
        braze.isPushSupported() === false ||
        braze.isPushPermissionGranted() ||
        braze.isPushBlocked()
      ) {
        // do not call `showInAppMessage`
        return;
      }

      // user is eligible to receive the native prompt
      // register a click handler on one of the two buttons
      if (inAppMessage.buttons[0]) {
        // Prompt the user when the first button is clicked
        inAppMessage.buttons[0].subscribeToClickedEvent(function() {
          braze.requestPushPermission(
            function() {
              // success!
            },
            function() {
              // user declined
            }
          );
        });
      }
    }
  }

  // show the in-app message now
  braze.showInAppMessage(inAppMessage);
});