Key Concepts

Before you learn about the architecture of Catalyst push notifications, you should get familiar with some fundamental concepts.

Web Push Notifications

Catalyst push notifications for web applications is a fully managed service which you can use to easily enable and activate push notifications for your web app.

A Catalyst web app’s push notifications are displayed to users when the web app is open in their active browser. However, the browser must support web push and service workers for the notifications to be delivered to the user. You can learn more about these concepts in the Architecture section of the documentation.

You can write your own action to design the logic for push notifications in the code snippet that Catalyst provides and implement it in your application.

Depending on the guidelines of the web browsers, you can enable a provision for the users of your web app to opt in to receive push notifications. This can be done by including a prompt requesting permission to allow push notifications. Once the user grants permission, they will be subscribed to receive push notifications from your web app. A unique user subscription ID is created when they provide permission, which allows the web app to send push notifications to them. You can store this ID in your database to identify the subscribers.

As discussed earlier, after you enable and configure push notifications in your web app, you can send test push notifications to specific users from the Catalyst console. You will be able to send plain text notifications to the test clients to check for bugs in the implementation. The users that you send them to must have active sessions of your web app open in their browsers to receive the notifications.

iOS Push Notifications

The key concepts of iOS push notifications are explained below:

1. APNS:
   
   The iOS push notifications are handled by Apple Push Notifications service, or APNs. Your app is connected to the APNs server when it is installed on a user’s device, and this enables the user to receive the notifications that your server forwards to APNs. Catalyst takes the role of the server: it obtains the push messages from you and forwards them to APNs on your behalf, which in turn routes them to the client devices. You can learn more about this in the Architecture section.
   
   Before you can enroll for Catalyst push notification services, you must obtain an APNs certificate issued by Apple and upload it to Catalyst. The APNs certificate permits the developer to send push notification data to the applications installed on Apple devices. Uploading this certificate to Catalyst establishes a secure connection between Catalyst servers and APNs.

   Note: You must create separate APNs certificates and manage separate APNs connections for each iOS app hosted in different Catalyst projects. You will also need to regenerate your APNs certificate before its validity expires.

2. Development and Production modes: As discussed previously, you can test notifications in both the development and production modes of Catalyst, which are also known as sandboxed and live modes. Apple supports and provides different servers for both these modes.

   Note: The development and production modes of an iOS app are not to be confused with the development and production environments in Catalyst.

   If you select the development mode in the Catalyst console to send test notifications, this will inform Catalyst to forward your notifications to Apple’s test servers. Likewise, if you select the production mode to send test notifications, this will inform Catalyst to forward your notifications to Apple’s live servers.

   If your test notifications are delivered to the devices successfully, the APNs connection has been configured properly with your app. When the notifications are sent from your app, you can determine the status of their delivery from the API response you receive.

3. Registering a user device:
   
   For iOS apps, the devices that you need to send push notifications to must be registered with APNs. The users must also provide explicit permission for the app to send them push notifications. This can be handled in the app’s logic by sending the users a permission prompt, where they can allow or deny permission. Once the permission is provided, you can send test notifications to the device.
   
   The steps to be followed to configure and enroll for Catalyst push notification services and test push notifications from the Catalyst console are discussed in detail in the Implementation section.

Elements of a Push Notification

The elements of a push notification vary depending on whether it is for a web or an iOS application, mainly because of the differences in standards and restrictions imposed by various web browsers and Apple. Let’s elaborate on this for each of the platforms individually.

1. Web

   Most web browsers do not contain heavy restrictions on HTML customizations or actionable elements that are incorporated in web push notifications. However, unlike native mobile app push notifications, web push notifications do not offer support for a wide variety of media types and interactive elements like GIFs or audio. Additionally, mobile app push notifications can access the mobile phone’s camera, accelerometer, and more, which cannot be done by a web app.
   
   Different web browsers implement different standards in terms of feature support for push notifications. You must therefore design their appearance and logic accordingly.
   
   Broadly, a web push notification can contain elements like:

   • Title and Description
   • App Icon
   • Call-to-action button
   • Website URL

2. iOS

   Apple supports a variety of rich media and elements that can be included in its push notifications. Since an iOS app is installed on a mobile device, it can also take advantage of the device’s camera, GPS, accelerometer, and other hardware.
   
   Catalyst supports iOS notifications which contain text content. Other elements like audio and video attachments, images, hyperlinks, and call-to-action buttons can also be included as a JSON package. Catalyst also supports notification badge counts in your iOS push notifications. This displays the number of notifications that are waiting to be read in the notification badge.

   You can also perform a variety of actions with iOS push notifications such as:

   • Modifying the notification content before it is displayed to the user
   • Performing a background task
   • Grouping notifications into threads
   • Providing interactive UI in the notification such as a Like button

   However, you must be aware of the standards defined by Apple and you must adhere to their guidelines before defining actions for iOS push notifications. You can find more information regarding this in their official documentation about generating a remote notification.