Subscribing a User

Getting the Vapid Public Key

PRIM_CAP.PrivateKey.VapidPublicKey

The Vapid Public key can be retrieved by loading a prime256v1 EC Private Key PEM file using PRIM_CAP.PrivateKey. After loading, you can retrieve the VapidPublicKey, which returns an encoded string that can be passed to the web application.

    Mthroutine Name(GetVapidKey)
    Define_Map For(*RESULT) Class(#Prim_dc.UnicodeString) Name(#result)
    #xPushManagerPrivateKeyPath := *TEMP_DIR + 'PrivateKeys' + *PATHDELIM + 'ECPrivatekey.pem'

    If (#PrivateKey.LoadPemFile( #xPushManagerPrivateKeyPath ))

    #result := #PrivateKey.VapidPublicKey

    Endif

    Endroutine

Push Manager

The Push Manager is defined inside of a web component and gives access to properties, methods, and events for maintaining a user’s push notifications.

    Define_Com Class(#PRIM_WEB.PushManager) Name(#PushManager)

Methods

Query

The Query asks the service worker to find the permission status of the push notifications for the user, the feature status of push notifications, the subscription reference to the user's subscription, and the notification history, a list of messages previously received by the user in the browser. This process will trigger the changes event which will be used to gather the appropriate properties.

    Mthroutine Name(CheckSubscription)
       #PushManager.Query
    Endroutine

Subscribes a user to receive push notifications. Once the subscription is completed in the service worker, the push manager changed event will be triggered.

    Evtroutine Handling(#ButtonSubscribe.Click)

      #Subscribing := True
      #PushManager.Subscribe( #xPushManagerVapidPublicKey )

    Endroutine

Unsubscribe

Stops the user from receiving push notifications. Once the unsubscription is completed in the service worker, the push manager changed event will be triggered.

    Evtroutine Handling(#ButtonUnsubscribe.Click)

       #UnSubscribing := True
       #PushManager.Unsubscribe

    Endroutine

Events

Changed

The change event is triggered to show a change in the push notification status or that all subscription details have been received. This means that the derived properties from the service worker will be up to date.

    Evtroutine Handling(#PushManager.Changed)

       #xPushManagerFeatureStatus := #PushManager.FeatureStatus
       #xPushManagerPermissionsStatus := #PushManager.PermissionStatus
       #xPushSubscriptionObject #xPushSubscriptionEndpoint := ""

       If ((#xPushManagerFeatureStatus = 'Subscribed') *And (#xPushManagerPermissionsStatus = 'Granted'))

          #xPushSubscriptionObject := #PushManager.Subscription.SubscriptionObject
          #xPushSubscriptionEndpoint := #PushManager.Subscription.Endpoint
 
          #ButtonSubscribe.Enabled := False
          #ButtonUnsubscribe.Enabled := true
     
          If (#Subscribing)
     
             #com_self.SendSusbscription
             #Subscribing := False
    
          Endif
   
       Else
  
          If (#UnSubscribing)

             #com_self.UnsubscribeUser
             #UnSubscribing := False

          Endif

          #ButtonSubscribe.Enabled := (#PushManager.FeatureStatus <> Unsupported) *And (#PushManager.FeatureStatus <> Failed) *And (#PushManager.PermissionStatus <> Denied)
          #ButtonUnsubscribe.Enabled := False
  
       Endif

    Endroutine

Properties

PermissionStatus

Returns an enumeration based on the permission to receive push notifications for that web app. Values and meanings are:

Unknown – Details of notification permissions have not or could not be retrieved.

Granted – The user has granted permission to receive push notifications.

Denied - The user has denied the request to receive push notifications from this application.

Prompt - The user needs to grant permission.

Failed - The retrieval of the notifications status has failed.

#PushNotificationFeatureStatus := #PushManager.FeatureStatus
#PushNotificationPermissionsStatus := #PushManager.PermissionStatus

Feature Status

The feature status returns an enumeration based on the web applications service worker and its status for receiving push notifications, the values, and their meanings are:

Unsupported - The browser the user is using does not support push notifications and/or the web application is not a PWA.

NotSubscribed – The application supports notifications but the user has yet to subscribe.

Subscribed - The user is subscribed to receive push notifications.

Pending - The service worker is still processing a subscription.

Failed - An error occurred in creating push notification subscription.

#PushNotificationFeatureStatus := #PushManager.FeatureStatus
#PushNotificationPermissionsStatus := #PushManager.PermissionStatus

Subscription

Returns a reference to a user’s subscription. See the PushManager Subscription for more details.

NotificationHistiory

Returns an iterator containing previously received push notifications and values for their content. These values are badge, body, icon, image, tag, timestamp, title, and URL.

PushManager Subscription

The push manager subscription holds the details of a user subscription in two properties: SubscriptionObject and Endpoint.

Properties

SubscriptionObject

The SubscriptionObject is an encoded string that returns a user's subscription detail. The subscription object should not be altered when setting it for sending the push notification.

SubscriptionEndpoint

The SubscriptionEndpoint is a unique URL that points to a user agent that then forwards the notification to the service worker.

Sending Push Notification

PRIM_SRVM.HttpPushMessage

Manages the building, encrypting, and sending of push notifications.

Define_Com Class(#Prim_srvm.HttpPushMessage) Name(#Push)

Properties

ClaimsSubject

Specifies the email address of the application administrator for use in the JWT Claim. Group emails are preferred over individual email accounts.

ClaimsTokenTimespan

Specifies how long the JWT Claim will be valid in seconds. Values must be between 1 and 86,400.

HttpResponse

Returns the HTTP Response from the PushSend method.

PushMessageBadgeUrl

Specifies the image to be used as the badge of a push notification, the badge is displayed when there is not enough space to show the content of a notification, such as in smartphone notification centres.

PushMessageBody

Specifies the content of the message body to be displayed.

PushMessageDirection

Specifies the direction of the enumeration values and meanings are:
Auto – Text direction be determined from the iso language used.
RightToLeft – Text will be displayed from right to left
LeftToRight – Text will be displayed from left to right.

PushMessageIconUrl

Specifies the image to be used as the icon of a push notification.

PushMessageImageUrl

PushMessageImageUrl specifies the image to be used as the image of a push notification. It is not supported by all browsers.

PushMessageLang

Specifies the ISO language of the push notification content in ISO format.

PushMessageRenotify

Specifies the whether a user should be renotified.

PushMessageRequireAction

Specifies if the message is persistent on the screen until a user interacts with it or will only be displayed for several seconds.

PushMessageTag

Specifies an identifier for a message.

PushMessageTimestamp

Specifies the timestamp to set for the push message.

PushMessageTitle

Specifies the title to display on the notifications.

PushMessageUrl

Specifies a URL that will be navigated to upon clicking the notification. This can be either a relative path or an explicit path but must exist within the web application. By default, if no URL is set it will navigate to the application root URL.

SubscriptionObject

Specifies the encoded subscription string returned from the user subscribing to the push notifications.

TimeToLive

Specifies the delay between the push message being sent and the push notification being displayed to the end user in seconds.

Urgency

Specifies the priority of the message. When an inactive user comes online notifications are displayed in order of priority and then time sent.

ValidationMessage

Returns a value if the push notification fails any validations with details of the failure.

Methods

SendPush

Uses the properties to construct a push notification, encrypt it, and send it via HTTP. This requires the Private Key used to create the Vapid Public key as an input parameter.

There are also mandatory properties to be set before sending the notification. These are: SubscriptionObject, ClaimsSubject, ClaimsExpiry, and PushMessageTitle.

    Mthroutine Name(Send)
       Define_Map For(*INPUT) Class(#xPushManagerSubscriptionStatus) Name(#iStatus) Mandatory(*SQLNULL)
 
       Define_Com Class(#prim_Capi.PrivateKey) Name(#PushPrivateKey)

       If (#PushPrivateKey.LoadPemFile( #COM_SELF.GetPrivateKeyPath ))

          #Push.PushMessageBadgeUrl := #xPushMessageBadge
          #Push.PushMessageBody := #xPushMessageBody
          #Push.PushMessageDirection := #xPushMessageDirection
          #Push.PushMessageIconUrl := #xPushMessageIcon
          #Push.PushMessageImageUrl := #xPushMessageImage
          #Push.PushMessageLang := #xPushMessageLanguage
          #Push.PushMessageRenotify := #xPushMessageRenotify
          #Push.PushMessageRequireAction := #xPushMessageRequireAction
          #Push.PushMessageTag := #xPushMessageTag
          #Push.PushMessageTimestamp := #xPushMessageTimestamp
          #Push.PushMessageTitle := #xPushMessageTitle
          #Push.PushMessageUrl := #xPushMessageData
          #Push.ClaimsTokenTimespan := #xPushMessageClaimsExpiry
          #Push.ClaimsSubject := #xPushMessageClaimsSubject.LowerCase
          #Push.SubscriptionObject := #xPushSubscriptionObject
          #Push.Urgency := #xPushMessageUrgency
          #Push.TimeToLive := #xPushMessageTimeToLive


      Select Fields(#xPushSubscriptionObject) From_File(xPushSubscriptions)

             #Push.SubscriptionObject := #xPushSubscriptionObject     

             If (#Push.SendPush( #PushPrivateKey ))

                #PushNotificationHttpIsSuccessfulRequest := #Push.HttpResponse.IsSuccessfulRequest
                #PushNotificationHttpResponseCode := #Push.HttpResponse.HttpStatusCode
     
                If (#PushNotificationHttpIsSuccessfulRequest.not)
                   #PushNotificationHttpErrorCode := #Push.HttpResponse.ErrorCode
                   #PushNotificationHttpErrorMessage := #Push.HttpResponse.ErrorMessage
                Endif

             Else

              #PushNotificationHttpErrorMessage := #Push.ValidationMessage

             Endif

          Endselect
       Endif

    Endroutine

The result of applying the features in your PWA is the following:

Content

Space Tools

23.3 Developing Push Notifications

Subscribing a User

Getting the Vapid Public Key

PRIM_CAP.PrivateKey.VapidPublicKey

Push Manager

Methods

Query

Subscribe

Unsubscribe

Events

Changed

Properties

PermissionStatus

Feature Status

Subscription

NotificationHistiory

PushManager Subscription

Properties

SubscriptionObject

SubscriptionEndpoint

Sending Push Notification

PRIM_SRVM.HttpPushMessage

Properties

ClaimsSubject

ClaimsTokenTimespan

HttpResponse

PushMessageBadgeUrl

PushMessageBody

PushMessageDirection

PushMessageIconUrl

PushMessageImageUrl

PushMessageLang

PushMessageRenotify

PushMessageRequireAction

PushMessageTag

PushMessageTimestamp

PushMessageTitle

PushMessageUrl

SubscriptionObject

TimeToLive

Urgency

ValidationMessage

Methods

SendPush