Package com.iizix.server.push

Class PushNotificationHandler

java.lang.Object
com.iizix.server.push.PushNotificationHandler
All Implemented Interfaces:
ICommonServletInterface
public class PushNotificationHandler extends Object implements ICommonServletInterface
Push notification handler class used for the web server.

It handles the following "GET" request: WWW-Authenticate: Basic realm="User Visible Realm", charset="UTF-8"

Apple Push

Original information at https://developer.apple.com/library/archive/documentation/NetworkingInternet/Conceptual/NotificationProgrammingGuideForWebsites/PushNotifications/PushNotifications.html.

Downloading Your Website Package

When a user allows permission to receive push notifications, a POST request is sent to the following URL:

     webServiceURL/version/pushPackages/websitePushID

This POST request contains the following information:

  • In the HTTP body. The same user info JSON object that is passed as the third argument of the requestPermission() call. Use the user info dictionary to identify the user.

When serving the push package, return application/zip for the Content-type header.

Registering or Updating Device Permission Policy

When users first grant permission, or later change their permission levels for your website, a POST request is sent to the following URL:

     webServiceURL/version/devices/deviceToken/registrations/websitePushID

This POST request contains the following information:

  • In the HTTP header. An Authorization header. Its value is the word ApplePushNotifications and the authentication token, separated by a single space. The authentication token is the same token that’s specified in your package’s website.json file. Your web service can use this token to determine which user is registering or updating their permission policy.

Respond to this request by saving the device token in a database that you can later reference when you send push notifications. Also, change the user’s settings in your database to the values indicated by the parameterized dictionary for the device.

Forgetting Device Permission Policy

If a user removes permission of a website in Safari preferences, a DELETE request is sent to the following URL:

     webServiceURL/version/devices/deviceToken/registrations/websitePushID

This DELETE request contains the following information:

  • In the HTTP header. An Authorization header. Its value is the word ApplePushNotifications and the authentication token, separated by a single space. The authentication token is the same token that’s specified in your package’s website.json file. Your web service can use this authentication token to determine which user is removing their permission policy.

Use this authentication token to remove the device token from your database, as if the device had never registered to your service.

Logging Errors

If an error occurs, a POST request is sent to the following URL:

     webServiceURL/version/log

This POST request contains the following information:

  • In the HTTP body. A JSON dictionary containing a single key, named logs, which holds an array of strings describing the errors that occurred.

Use this endpoint to help you debug your web service implementation. The logs contain a description of the error in a human-readable format. See section Troubleshooting for a list of possible errors.

Author:
Christopher Mindus

  • Field Details

    • BASE_REQUEST_URI

      public static final String BASE_REQUEST_URI
      Base URI for IIZI Push API: "/iizi-push/".
      See Also:

    • AUTH_REALM

      public static final String AUTH_REALM
      Authentication Realm for Push Notifications. When authentication is required, the requesting party should send an "Authorization" header as "Basic <i>authentication</i>" where <i>authentication</i> is the Base64 encoded value of the UTF-8 String userName + ':' + password. The password can be the user's password in clear text or the undecipherable "hashed password" (based on PBKDF2 with Keyed-Hash Message Authentication Code [HMAC] with a SHA-256 hash).
      See Also:

    • KEYS

      public static final String KEYS
      Get server keys for App ID.

      URI /iizi-push/keys

      Requires authentication: Yes.

      The request JSON is an Object with the following members:

      • app_id:
        {String} The App ID or "*" for all apps of the server, i.e. the server's configuration for push messaging.

      The response is a JSON Object with the following members:

      • v
        {String} VAPID The ECDSA P-256 public key encoded in Base64.
         
      • a
        {String} Firebase Cloud Messaging ID in Cordova for Android.
         
      • i
        {String} Firebase Cloud Messaging ID in Cordova for iOS.
         
      • w
        {String} Firebase Cloud Messaging ID for the Web.
         
      • s
        {String} Apple Push ID in Safari (macOS and iOS without Cordova).
      See Also:

    • SUBSCRIPTION_COUNT

      public static final String SUBSCRIPTION_COUNT
      Gets the count of all subscriptions.

      URI /iizi-push/count

      The count can be retrieved for either:

      • User + AppID + Topic, or
      • Device UUID.

      Authentication required:

      • User + AppID + Topic: Yes.
      • Device UUID: No.

      The request JSON is an Object with the following members:

      • User + AppID + Topic:
         
        • app_id:
          {String} The App ID or "*" for all apps of the server, i.e. the server's configuration for push messaging.
           
        • topic:
          {String} The App ID or "*" for all apps of the server, i.e. the server's configuration for push messaging.

        The response is a JSON Object with the following members:

        • v
          {String} VAPID The ECDSA P-256 public key encoded in Base64.
           
        • a
          {String} Firebase Cloud Messaging ID in Cordova for Android.
           
        • i
          {String} Firebase Cloud Messaging ID in Cordova for iOS.
           
        • w
          {String} Firebase Cloud Messaging ID for the Web.
           
        • s
          {String} Apple Push ID in Safari (macOS and iOS without Cordova).
      See Also:

    • GET_SUBSCRIPTIONS

      public static final String GET_SUBSCRIPTIONS
      Get subscriptions for AppID and Topic of the User's all devices or

      Request URI /iizi-push/get_subs

      Requires authentication: Yes.

      See Also:

    • RESET

      public static final String RESET
      Resets all subscriptions for a specific device UUID regardless of User/AppID/Topic, or for specified user for all its subscriptions [all AppID's, all Topic's] (requires authentication).

      Request URI /iizi-push/reset

      Requires authentication: Yes.

      If the flag 'device' is 'true', all subscriptions for the device UUID will be used, 'false' means all subscriptions of the user.

      See Also:

    • SUBSCRIPTIONS_LIST

      public static final String SUBSCRIPTIONS_LIST
      Get the subscriptions list.

      Request URI /iizi-push/list.

      The request JSON Object have the following members:

      • 'app_id' = {String} App ID
      • 'topic' = {String} Topic

          The reply is a JSON Object as:

          • 'count' = {Number} Count of subscriptions: zero or more in the 'subs' array below
          • 'app_id' = {String} App ID
          • 'topic' = {String} Topic
          • 'subs' = {Array} Array of subscriptions as below

          where each 'subscription' in the 'subs' {Array} is:

          • 'uuid' = {String} device UUID,
          • 'created' = {Number} Time of subscription creation, epoch milliseconds
          • 'vapid' = {Object} A {PushSubscription}.toJSON() object for VAPID-based provider using Service Worker
          • 'android' = {String} Firebase Cloud Messaging ID in Cordova for Android
          • 'ios' = {String} Firebase Cloud Messaging ID in Cordova for iOS
          • 'web' = {String} Firebase Cloud Messaging ID for the Web
          • 'safari' = {String} Apple Push ID in Safari (macOS and iOS without Cordova)
      See Also:

    • SUBSCRIBE

      public static final String SUBSCRIBE
      Subscription to AppID and Topic (requires authentication): request URI "/iizi-push/subscribe".
      See Also:

    • UNSUBSCRIBE

      public static final String UNSUBSCRIBE
      Unsubscribes a User from AppID and Topic request (requires authentication): URI "/iizi-push/unsubscribe".

      If the flag 'all' is 'true', all subscriptions from all devices of the user will be unsubscribed.

      See Also:

    • PUSH

      public static final String PUSH
      Send push notification to User for AppID and Topic URI (requires authentication): URI "/iizi-push/push".
      See Also:

    • APP_ID_NOT_FOUND

      public static final String APP_ID_NOT_FOUND
      Error message when 'app_id' is not found in the server.
      See Also:

    • SERVER_NO_KEYS

      public static final String SERVER_NO_KEYS
      Error message 410 when server "app_id='*'" is not configured with any Push Messaging keys.
      See Also:

    • APP_ERR_NO_KEYS

      public static final String APP_ERR_NO_KEYS
      Error message 410 when the 'app_id' is not configured with any Push Messaging keys.
      See Also:

    • NO_SUBSCRIPTIONS_ERR

      public static final String NO_SUBSCRIPTIONS_ERR
      Error message when subscriptions are not found.
      See Also:

    • INVALID_SUBSCRIPTION_ERR

      public static final String INVALID_SUBSCRIPTION_ERR
      Error message when an invalid subscription is found.
      See Also:

  • Method Details

    • handle

      public boolean handle(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException
      Checks if the servlet is handling the request or not.
      Specified by:
      handle in interface ICommonServletInterface
      Parameters:
      request - The request.
      response - The response.
      Returns:
      true if handled, false otherwise.
      Throws:
      ServletException - For Servlet exceptions.
      IOException - For I/O errors.

    • reset

      public int reset(String uuid) throws SQLException
      Performs the reset for a UUID device. All subscriptions will be removed.
      Parameters:
      uuid - The device UUID.
      Returns:
      The count of removed subscriptions.
      Throws:
      SQLException - For SQL errors.

    • getSubscriptionCount

      public int getSubscriptionCount(String deviceUUID) throws SQLException
      Gets the count of push notification subscriptions for a Device UUID.
      Parameters:
      deviceUUID - The device UUID.
      Returns:
      The count of subscriptions matching this Device UUID.
      Throws:
      NullPointerException - If deviceUUID is null.
      IllegalArgumentException - If the deviceUUID does not conform the UUID string representation UUID.toString().
      SQLException - For SQL errors.

    • getSubscriptionCount

      public int getSubscriptionCount(String userID, String password, String appID, String topic) throws SQLException
      Gets the count of push notification subscriptions for a User, app ID and topic.
      Parameters:
      userID - The user ID, cannot be null.
      password - The password in clear text or a hashed password, cannot be null.
      appID - The application ID, cannot be null, "*" for all applications.
      topic - The topic, cannot be null but empty string for none.
      Returns:
      The count of subscriptions.
      Throws:
      SQLException - For SQL errors.
      NotFoundException - If the userID is not found, or if the password doesn't match.
      NullPointerException - If any parameter is null.