Dusty Eves


Sitecore Architect with Paragon Consulting

Engaging Your Customers with WebAPI Notifications in Sitecore

The Shortcomings of Email

Email is a great tool for engaging our customers and making sure that our offerings stay top of mind.  Tools like the Sitecore’s Engagement Plan Manager make automated customer engagement campaigns easy to create, manage, and track.  While email campaigns are quite valuable, engaging through email does have downsides.  When email was new most people read every email that entered their inbox but today most people have email inboxes with literally hundreds of unread emails.  It’s difficult to create email campaigns that don’t get lost as noise.

Enter Notifications

Notifications fill a similar and overlapping niche in engaging your customer and have several advantages over email.  Broadly speaking notifications are just a more engaging way to connect with your customers.  The first advantage is notifications are often read in real time.  While desktop browsers have support for WebAPI notifications, any notifications are targeted to reach a customer on their mobile device.  This mixed with the second advantage is that notifications: They less likely to be ignored.  With the spam filled 90s and the fact that once someone has your email they need no permission to email you, most people are very adept at ignoring email.  By virtue of notifications requiring permission they’re not regarded as noise in the same way email is.

How it works

Start by downloading the  solution from Github here: https://github.com/DustyEves/Sitecore-WebAPI-Notifications.  This contains much of what you need to get started to incorporate notification messages into Sitecore via engagement plans.

The first thing we need from our visitor is permission to send notifications, which we get via the following steps:

  1. Request Notification
    • A request is made through the browser to send notifications.  The user will see a “Website ‘web.address.com’ would like to send notifications.  Allow/Deny”.
  2. Install Service Worker
    • If the user clicks “allow”, a Javascript service worker will be installed on the device and run in the background.
  3. Notification Contract Returned
    • One the service worker is installed the browser will return a Public Key, and Authorization Token, and an Endpoint to call for the notifications.  Our client side code should return this and persist it on the server.  In Sitecore, we preserve this to the visitor profile.

For more information on how notifications work, the Google developers blog does a fantastic job of explaining notifications here.

Getting Started

To use the WebAPI solution you can either add the projects in your site’s solution or configure the TDS projects within the solution to point to your web directory.  The two needed components are WebPushLib which we use to send the notifications out and Feature.PushNotifications which contains all of our Sitecore assets.  Also included is a simple EndUserSession tool, useful in testing and debugging xMarketing features.

Configuring the Keys

In order to send notifications you need to generate application server keys by which to encrypt.  The easiest way to generate these is via NodeJs and generate the keys via the web-push.

$ npm install -g web-push
$ web-push generate-vapid-keys

Once you’ve you’re unique server keys in the Feature.PushNotifications project under App_Config\Include\zz.PushNotifications.config add the values to the PublicKey and PrivateKey settings.

Getting Permission

The first thing we need to go is to get permission from the visitor to send notifications.  Once you’ve deploy the TDS items you’ll find a new rendering “Push Notifications Script”.  Add this to any page you want a notification prompt to be available on.  By adding this rendering the page has the capability to request notification permission, but only the ability.  While you can request notification permission on page load it is generally poor practice.  Giving the visitor both a clear reason as to why the permission is being requested and tying it to something initiated by the visitor will make it much more likely permission will be granted.

Start by adding the rendering to the page with either a toggle switch or a checkbox. Then add on onclick property and call the function “askPermission()”.  This will prompt the visitor to accept notifications from your site.  Upon accepting permission the service worker will be installed on the visitor’s device and we’ll persist the notification endpoint on the visitor profile.

Enrolling In Engagement Plan

In addition to persisting the notification data to the visitor profile the Push Notification Script rendering gives us the ability to trigger engagement plan enrollment as well.  If we open the rendering details of our script, we can setup the acceptance actions:


To enroll a visitor into an engagement plan on acceptance just select the plan and the state into which to enroll them.  We also can trigger a goal as part of the registration.

Sending Notifications

Now that we’ve visitors who’ve accepted notification permission how do we send them notification.  Our solution provides some new tools for our Engagement Plan.  An engagement action to send out the notification and a rule to assess whether or not we have notification permission.

To setup a notification add the “Send Notification” action to some step in your Engagement Plan and open the action editor.  This will bring up the dialog below:

Here we have all the fields that define our notification.  Of our fields here, Title and Notification Body are self-explanatory.  The Icon and Badge fields are similar but serve different purposes.  The Badge field is a black and white icon that displays in the top notification bar of most mobile phones.  The Icon field is a color icon that displays in the notification panel.  The subject field is the url to which the visitor is directed in clicking on the notification.

Designing the Engagement Plan

Also among our new Engagement Plan tools is our “Notification Permission” rule.  This rule is useful to personalize the visitor’s UI such that we’re not prompt a visitor for notification permission if they have already provided.  This also allows us to design engagement plans such that we’re communicating with our visitor with the most engaging mechanism available.  Taking the example below.  We’ve a simple engagement plan to try and get visitors to come to our event.   If the visitor has given us permission to send notifications, we can ask via notification.  If not, then we still have the option to email.

In Conclusion

If you can offer sufficient incentive to your customers to get notification permission it can provide a very engaging communication channel for you visitors.  While getting permission for notifications can be challenging the technical challenges for notifications are much easier to overcome that one might initially assume.