Using the Push Notification Framework
Last updated
Last updated
Contact Us
Get Help© Copyright TomorrowX 2024 Composable Architecture Platform and Connected Agile are trademarks and servicemarks of TomorrowX.
Push notifications is rapidly emerging as one of the most efficient ways of sending information to users without going through email, SMS or other channels (such as Messenger or Slack).
Push notifications have a very high click-through rate and is supported by all modern browsers and platforms except Apple’s.
The push notification framework provides a simple way to add push notifications to your application with the ability to fall back to alternatives if the user is on an unsupported platform.
A push notification appears as a message in the user’s notification section. For example, in Windows a message could look like this:
It consists of an Icon, A headline and a text body (where supported).
If the user clicks on the message, an event is generated that will open a web page specific to the message and will also send a notification back to the server that the user clicked the message.
There are some restrictions to using push messages:
The web site sending the message MUST be using a secure protocol (https), even during development
The user must be on a supported platform
A set of cryptographic keys must be created to sign messages
The push notification framework helps you manage the last 2 of those 3 items above. To install certificates within your application, please refer to the product reference.
Please note: This manual will reference the Push Notification Demo repository, which can be obtained from the update server.
The push notification framework consists of 3 rules and a precisely structure HTML page. In the following section we will cover these rules in detail.
This rule does two things:
It either obtains, reads, or creates credential keys to use with the notifications
It initializes a data set used to store notification user information
The condition for creating keys is that no keys are present in the credentials vault or in the file system, so they must be created. This is done directly on the target server as two new files the first time the rule is executed:
You can choose to simply leave these files on the server (in which case you should also place them in the Data Files section of the repository you are working with and ensure they are deployed using the Register Data Files rule).
The preferred way however is to store the keys in the credential vault. This is a simple exercise of opening the key files with a text editor and copying the text from them to the appropriate keys in the vault:
Once the keys are in the vault, the files can be removed from the target server.
The data set created by the rule is named “WebPushSubscribers” and is entirely managed by the framework. You can however query and work with the data set in rules as well if you wish. To do so, you will need to know the field names which are: subscriber, target, endpoint and group.
Subscriber refers to the user id within your application for a logged in user
Target is the type of communication. For example: Push, Email, SMS etc
Endpoint is the key to sending, it can be a Push key, email address, phone number (or whatever else is a valid definition of where the message should end up depending on the target)
Group is the target group. It can be the same as the subscriber (for direct communication) or it can be a subscribed group (such as offers, recalls, alerts etc).
The Push Notification Controller rule manages everything related to interacting with the browser to ensure push notifications can be subscribed to and delivered. It automatically generates correct and tested JavaScript pages and a default icon for the rest of the framework to use.
Even though the controller manages all these interactions, you always have the option of doing your own additional processing (For example when a user subscribes or unsubscribes or performs a click through on a notification).
The controller only needs a few properties:
The Database is the database where subscriber information should be store.
The Subscriber is the user ID of the user involved in the interaction. Note that generally speaking it is best to have a user logged in so that you can target specific users, rather than just a generic group of people.
The Default URL to open is a fallback mechanism for browsers that do not yet support a target URL to open for each message. In that case, clicking on the notification should send them to a sensible page (such as a login page).
The Is default URL also welcome page is important only to ensure that if the user already keyed in the welcome URL and already has that open (without a page, such as https://example.com/ and not https://example.com/index.html) the browser should not open index.html but rather just focus the original welcome page).
The Push Notification Controller is designed to be the last rule in our normal application flows. In the sample repository that looks like this:
It is important to note that the sample repository is cut down to an absolute minimum for maximum clarity. Your production repository should follow the guidelines set out in the Best Practices manual.
To help you experience push notifications we have created a simple entry page called index.html. It presents as follows:
Returning to this page logs out any user. To log in as one of the two users just click the relevant button.
No passwords required.
To go along with the Push Notification Controller, you will need a subscription page served up as content. There is a very minimum sample page in the Push Notification Demo repository named subscribe.html. It presents as follows (after checking that notifications are possible):
Should your browser NOT support push notifications, you will receive the following page instead:
And finally if you are trying with something like Internet Explorer you will receive this message:
All of the above sections are simply DIVs in the sample HTML file:
The important thing to understand is that the various IDs of each DIV must remain in place.
You can change the DIVs to <section> or <span> tags (or whatever you like), but the IDs must be present so the Push Notification Controller rule can take charge of the page in the background.
Mandatory IDs
There are several critical IDs that must remain in place. They are as follows:
ID
Function
webpushSupportedNotSubscribed
This ID is used to identify a section that is displayed when push notifications are supported, but the browser is not yet subscribed.
webpushNotSupportedNotSubscribed
This ID is used to identify a section that is displayed when push notifications are not supported, but the browser is not yet subscribed.
webpushSupportedButBlocked
This ID is used to identify a section that is displayed when push notifications are supported, but the user has previously declined permission to send notifications
webpushSupportedButError
This ID is used to identify a section that is displayed when push notifications are supported, but an unexpected error was encountered when try to register
webpushSubscribed
This ID is used to identify a section that is displayed when the user is already subscribed to notifications
webpushGroups
This ID is used to identify a section that displays a list of groups that the user can choose to subscribe to alongside the individual subscription
webpushChecking
This ID is used to identify a section that is displayed while the browser is checking the availability of push notifications
webpushTooOld
This ID is used to identify a section that is displayed if the browser is too old to support the push notification syntax.
webpushStyleDisplayBlock
This hidden ID is used to identify a value that will be used to turn items with display=”none” to visible. The default is “block”, but should you need other values (such as “inline-block”) you can change this value to achieve that effect.
webpushSubscriber[target]
These hidden IDs are used to identify a value that will be used as the target value for any alternative notification methods. For example, if both Email and SMS are available, the IDs:
webpushSubscriberEmail
webpushSubscriberSMS
Must exist with appropriate values (email address and phone number).
webpushSubscribeButton
This ID is used to identify the subscribe button. The button can in theory be something other than a button, but it must support the disabled property.
webpushUnsubscribeButton
This ID is used to identify the unsubscribe button. The button can in theory be something other than a button, but it must support the disabled property.
Radio and Checkbox Groups
In addition to the IDs, there are 2 named radio button groups:
and:
Notice the slight difference in the name that separates the two groups. It’s a common mistake to copy from one group to the other and forget to correct the name.
Alongside each radio button that is NOT a Push notification, you will need to specify a hidden value for each:
This provides the framework with information on how to define the destination of the non-Push notifications.
The next section is the checkboxes to enable additional groups the user can subscribe to.
You can have an unlimited number of these groups. Each selection by the user will automatically subscribe them to that group and notifications can be sent to all subscribers.
Buttons
The framework requires two buttons on the page:
Both these buttons should be disabled in the HTML by default. The framework will enable the right button at the right time.
Connecting to the framework
The final step is to connect the HTML to the framework. This is done by importing a javascript file that is dynamically generated by the framework. You do not need to have this file anywhere in your repository, it is fully generated along with all dependencies.
And with this, you now have a fully functioning push notification page, so it is time to look at how to send them.
Sending push notifications involves either sending an individual message or sending notifications to an entire group of people. In the demonstration repository there is a sample sending page name send.html:
This page enables you to send individual push notifications to the two users or you can send a recall notification to all users that has subscribed to recalls.
The page shown after the message is the page that will be opened when the user clicks the notification.
All notifications (regardless of the method of sending) can be managed with the Send Push Notification rule:
There are several options to define how the push notification looks and acts:
The Database relates to the location where subscriber data is stored.
The Audience should be either the internal user ID that the application can use to identify a user or a notification group name.
The Sender Email should be the email of someone who can assist with technical queries from the external push notification servers used to send the notifications. Those servers are managed by organizations such as Google and Microsoft and the email is used for relaying complaints or warnings.
The Expiry is provided in minutes with a maximum of 24 hours allowed.
The Title is the key short description of the notification
The Icon is an icon to show to the user when the notification is displayed. If no icon is provided a default will be displayed.
The URL to open is the URL that will open when the user clicks on the notification. Not all browsers support this and should they not, the default URL to open from the Push Notification Controller will be used instead.
The Message allows for a longer notification message to be displayed. Not all browsers support this.
The Tag is a value that can be used to avoid sending the same notification to the user over and over. Messages with the same tag name will only be available once in the user’s notification system. The following Re-notify is related to this. It determines if the user should get another notification as a result of an unopened tag group or not.
Vibrate can be used to control the vibrations of the user’s device. It is specified as a series of on/off pairs in milliseconds. For example: “100,200,100,200” would mean vibrate for 100ms, pause for 200ms, vibrate for 100ms, pause for 200ms.
This rule notably includes the ability to personalize the message being sent and permits the sending through alternative channels.
For every message, the following variables are available: NOTIFICATION_TARGET, NOTIFICATION_USER, NOTIFICATION_ENDPOINT, NOTIFICATION_MESSAGE, NOTIFICATION_URL and NOTIFICATION_TITLE
The rule writer can use the first 3 to determine where to send a message and identify the relevant user being notified – and can use the last 3 to customize the message.
In our demonstration repository we do this by inserting the user name into the message for group messages:
The Personalize title rule has the following properties:
This is based on the title being sent to the recall group looking like this:
So for each message being sent, the Personalization chain point will insert the actual user name into the title.
If the user that signed up for notifications did not have a supported browser, we can offer alternatives (such as email, SMS or other targets).
To support the sender managing those alternative channels for us, the Alternative chain point is called whenever a target is different to “Push”. In our demonstration repository we showcase this with a simple output to the console:
However, the rule writer has access to all the 6 variables listed previously at this point in the flow and can use it to send the notification to the right target using the rules most relevant for that:
