Push Notifications

Overview

APEX push notifications bring real-time communication between APEX applications and users on all desktop or mobile devices. These notifications enhance your end user's experience by providing instant updates and alerts, even when they are not actively engaged with the application. Notification target links redirect users back to your APEX application with a tap.

APEX provides hassle-free push notifications setup and offers declarative, no-code notification sending with a native page process. Developers who want more control can use the apex_pwa API to seamlessly integrate sending notifications into their existing workflow. There has never been an easier way to stay connected with users who've opted-in to receive notifications using the built-in settings page.

Compatibility

This table shows the supported combinations of operating systems and browsers for the push notification feature.

	Chrome	Edge	Firefox	Safari
Android	Yes	Yes	Yes	N/A
iOS	No	No	No	Yes*
macOS	Yes	Yes	Yes	Yes
Windows	Yes	Yes	Yes	N/A

* iOS 16.4 and later only on installed PWAs.

Last updated: April 2023

New Application

The fastest way to get started with APEX push notifications is enabling the push notification feature checkbox in the Create Application wizard.

Enable push notifications for a new APEX application

Instructions

In App Builder, click Create Application
Select New Application
Fill the required fields for creating a new application
Under Features, select Push Notifications checkbox
Click Create Application
Users can proceed with subscribing to push notifications
APEX can proceed to send push notification to subscribers

Existing Application

To enable push notifications in your existing APEX app, turn on the Enable Push Notifications switch in the Progressive Web App page and configure the required attributes.

Enable push notifications on an existing APEX app

Instructions

In App Builder go to Shared Components
Go to Progressive Web App
Turn on Enable Progressive Web App
Turn on Enable Push Notifications
Configure Credentials. Choose an existing key pair credential to authenticate against or click Generate Credentials to automatically generate a new key pair credentials for your application. This ensures that users can subscribe to push notifications securely.
Configure Settings Page. Create a feature page where users can subscribe to push notifications for your application. This page will allow users to manage their push notification preferences.
Configure Contact Email: Enter an email address where the push notification service provider (such as Google, Mozilla, or Apple) can contact the application owner if needed.
Users can proceed with subscribing to push notifications
APEX can proceed to send push notification to subscribers

Subscribing Devices

APEX prioritizes security above all else, ensuring that users only receive push notifications that they have consented to. Web standards require an app to request permission before sending notifications to prevent unwanted messages.

For each APEX application and on each device, end users opt-in to receive push notifications using the new, user-friendly Settings menu under the username in the navigation bar. Be sure to consult the compatibility matrix provided above to confirm that your device can fully utilize this feature.

Example of an iOS device subscribing to APEX push notifications

Instructions

Run your application
In the top navigation bar, tap your username and select Settings
A user settings drawer appears
Select Push Notifications option from the list of settings
Check the Enable push notifications on this device checkbox
Tap Allow to authorize this APEX app to send notifications to iOS device
Going back to the user settings list, Push Notifications should be set to On

Sending Notifications

APEX offers two methods for sending push notifications from an app. Each offers its own benefits and levels of control. Understanding these methods can help you choose the best approach for your specific needs.

Send using Page Process

The built-in 'Send Push Notification' page process lets you send a notification declaratively. This option is ideal for users who prefer a straightforward process without the need for extensive customization. This process sends a notification to a single user, although this user might have multiple devices expecting the same notification. To use this process, simply fill in the required fields, including the username, title, and description of the push notification. The process ensures your message is delivered to the intended recipient on any of their devices on which they've opted-in to receive notifications.

Send using API

For users seeking more control over the appearance and content of their push notifications, the apex_pwa API offers more flexibility. By using this API, you can manage additional parameters such as the icon and a different destination application. This approach is useful for looping through multiple users and sending multiple notifications at once.

Code

begin
    apex_pwa.send_push_notification (
        p_application_id => 100,
        p_user_name      => 'SMITH',
        p_title          => 'Notification Title',
        p_body           => 'Notification Body' );
end;

begin
    for l_subscription in ( 
        select distinct user_name
          from apex_appl_push_subscriptions
         where application_id = :APP_ID )
    loop
        apex_pwa.send_push_notification (
            p_application_id => :APP_ID,
            p_user_name      => l_subscription.user_name,
            p_title          => 'APEX 23.1 is here!',
            p_body           => 'Try out the new features.' );
    end loop;
end;

APEX Views

Regardless of the method you choose to send a push notification, it's important (for the APEX engine) to be able to identify the users who have subscribed to the feature in order to use the page process or the API meaningfully. APEX offers two views to help analyze this records of who is subscribed to the push notifications of your application and the notifications in the queue.

The apex_appl_push_subscriptions view lists all users who have opted in to receive your notifications, making it easy to target your messages to all your subscribers and Send a notification using the API. You could find an example in Send using API section above.

Code

select * from apex_appl_push_subscriptions

The apex_push_notifications_queue view, provides the notification records that are pending or have encountered errors during the sending process. This information useful for troubleshooting issues and ensuring the successful delivery of your push notifications.

Code

select * from apex_push_notifications_queue

Push Queue

apex_pwa.push_queue is an API designed to trigger sending pending push notifications in the queue. When sending a push notification, it is in fact simply added to a queue, with the push queue mechanism responsible for dispatching these notifications. In case of a failure, the queue entry is updated with an error message and can be located in the apex_push_notifications_queue view. Upon successful delivery, the entry is removed from the queue. Although a background job is set to process the queue every 2 minutes by default, developers can expedite the delivery using the apex_pwa.push_queue API.

Code

begin
    apex_pwa.push_queue;
end;

Receiving Notifications

Receiving push notifications from an APEX app feels special. Examples below illustrate how different devices receive notifications. Only devices that have opted in for push notifications can receive these updates. Those push notifications function even when the device is idle, or when users are not actively interacting with the app. This ensures that important information is delivered promptly, keeping users informed at all times.

When a user taps on a push notification, they can be redirected back into the APEX app. This simplifies navigation and fosters greater engagement and interaction with the app, as it helps maintain an ongoing connection with users, encourages user retention, and ultimately drives the overall success of the app. By default clicking the notification will redirect you to the home page.

Receiving an APEX notification on macOS

Receiving an APEX notification on iOS

Receiving an APEX notification on a wearable

Common Issues

First, check to make sure that your device is running iOS 16.4 or later. If not, you'll need to update your phone's operating system by going to your phone settings and selecting "Software Update.".

If your device is running iOS 16.4 or later, note that push notifications are only available on Safari browsers for installed PWAs only. Try installing the PWA and then check back on the user settings page.

Ensure that the username has been correctly entered in the native page process or in the APEX_PWA API. The username is case sensitive.

First, check to see if notifications are enabled in your browser settings. You can usually access these settings by clicking on the three-dot menu in the top-right corner of your browser window and selecting "Settings" or "Preferences." From there, look for a section called "Notifications" or "Site Settings" and make sure that notifications are turned on for the relevant website.

If notifications are enabled but you're still not receiving them, try clearing your browser's cache and cookies.

Verify if your browser engine, the browser through which the PWA is installed allows sending notifications in your operating system settings.

Finally, make sure that you're connected to the internet and that your device is not in "Do Not Disturb" mode. These settings can sometimes prevent notifications from coming through.

To ensure that your Progressive Web App is properly configured for push notifications, start by checking your credentials in the settings of your Progressive Web App.

After installing or importing an Application into your workspace, you will need to generate the credentials for your application. If you failed to perform this step, click (Regenerate Credentials) button in the Push Notifications tab. However, be aware that regenerating already-valid credentials invalidates all existing subscriptions that used the previous key pair credentials that were in effect.

Run the following script as SYS or another user with DBA privileges.


declare
    l_principal varchar2(20) := 'APEX_230100'; -- Replace with current APEX user
    l_hosts apex_t_varchar2  := apex_t_varchar2(
                                    '*.push.apple.com',
                                    '*.notify.windows.com',
                                    'updates.push.services.mozilla.com',
                                    'android.googleapis.com',
                                    'fcm.googleapis.com' );
begin
    for j in ( select column_value as hostname from table(l_hosts) ) loop
        dbms_network_acl_admin.append_host_ace (
            host       => j.hostname,
            lower_port => 443,
            upper_port => 443,
            ace        => xs$ace_type(
                              privilege_list => xs$name_list('connect'),
                              principal_name => l_principal,
                              principal_type => xs_acl.ptype_db) );

        dbms_network_acl_admin.append_host_ace (
            host       => j.hostname,
            ace        => xs$ace_type(
                              privilege_list => xs$name_list('resolve'),
                              principal_name => l_principal,
                              principal_type => xs_acl.ptype_db) );

        dbms_network_acl_admin.append_host_ace (
            host       => j.hostname,
            lower_port => 443,
            upper_port => 443,
            ace        => xs$ace_type(
                              privilege_list => xs$name_list('http'),
                              principal_name => l_principal,
                              principal_type => xs_acl.ptype_db) );
    end loop;
end;

For more information, read this documentation chapter.

Overview

Compatibility

New Application

Enable push notifications for a new APEX application

Instructions

Existing Application

Enable push notifications on an existing APEX app

Instructions

Subscribing Devices

Example of an iOS device subscribing to APEX push notifications

Instructions

Sending Notifications

Send using Page Process

Send using API

Code

APEX Views

apex_appl_push_subscriptions

Code

apex_push_notifications_queue

Code

Push Queue

Code

Receiving Notifications

Receiving an APEX notification on macOS

Receiving an APEX notification on iOS

Receiving an APEX notification on a wearable

Common Issues

On iOS, the user settings page shows "Not Supported"

Notifications are not being delivered to my device

This device failed to enable push notifications

ORA-24247: network access denied by access control list (ACL)