Email Notifications

The Sudo Platform Email Service sends push notifications on receipt of each email message to registered devices. These notifications contain metadata about the received email message encrypted using the public key registered with the email address that received the message.

There are three aspects to adding Sudo Platform Email Service push notification support to your application:

  1. Notification registration This aspect records your application's interest in Sudo Platform Email Service notifications with the Sudo Platform Notification Service.

  2. Notification configuration This aspect allows you to configure filtering of specific notifications. In particular, Sudo Platform Email SDK allows you to enable and disable transmission of message received notifications for particular email addresses.

  3. Notification reception This aspect allows you to decrypt the push notification payload and decide how to render the information in a notification displayed to the user.

Notification Registration

Registering for notifications is performed using the Sudo Platform Notification SDK. Each platform has a slightly different way of doing this. See the platform specific descriptions below for the specific way required to integrate notifications for a particular language environment.

The Sudo Notification Platform SDK for iOS takes as input aNotificationFilterClient provided by each Sudo Platform service that an application will receive notifications for. Each service's SDK provides a service specific filter client for this purpose.

The Sudo Platform Email Service SDK for iOS provides the DefaultSudoEmailNotificationFilterClient . The following sample code shows how this is registered with the Sudo Platform Notification Client SDK for iOS.

import SudoNotification
import SudoEmail

let emailNotificationFilterClient = DefaultSudoEmailNotificationFilterClient()

let notificationClient = try DefaultSudoNotificationClient(
  userClient: userClient,
  notifiableServices: [emailNotificationFilterClient]
)

Notification Configuration

Before your application will receive Sudo Platform Email Service notifications, you must enable them for the device's notification configuration. In addition to that you may choose to allow suppression sending of notifications for particular email addresses. Both of these tasks are accomplished with extensions to the Sudo Platform Notification SDK NotificationConfiguration class.

Enabling Sudo Platform Email Notifications

The .initEmailNotifications extension is used to ensure a NotificationConfiguration object includes registering interest in all the notification types sent by the Sudo Platform Email Service.

This operation is non-destructive if other services' notification configuration is also present. It is also non-destructive to any email address specific configuration that may already be present in the notification configuration object.

import SudoNotification
import SudoEmail

var configuration = NotificationConfiguration(configs: [])
do {
    configuration = try await sudoNotificationClient
        .getNotificationConfiguration(device: device)
} catch let error as SudoNotificationError {
    // Tolerate .notFound error
    guard case .notFound = error else {
        // Handle error
    }
}

// Ensure Sudo Platform Email Service notifications are enabled
configuration = configuration.initEmailNotifications()

let services = sudoNotificationClient.notifiableServices.map { $0.getSchema() }

do {
    configuration = try await sudoNotificationClient.setNotificationConfiguration(
        config: NotificationSettingsInput(
            bundleId: "<bundle-identifier>",
            deviceId: "<device-identitifier>",
            filter: configuration.configs,
            services: services
        )
    )
} catch {
   // Handle error
}

Managing notification configuration for specific Sudos

Whether or not notifications for email addresses associated with a particular Sudo are sent by the Sudo Platform Email Service can be controlled by adjusting the notification configuration for the device.

Whether or not notifications are currently enabled for a particular Sudo can be determined as follows for each platform:

import SudoNotification
import SudoEmail

let configuration: NotificationConfiguration

if configuration.areNotificationsEnabled(
       forSudoWithId: sudoId
   ) {
   // Notifications are enabled
} else {
   // Notifications are not enabled
}

Notifications can be enabled or disabled for a particular Sudo by modifying and updating the NotificationConfiguration for the device:


import SudoNotification
import SudoEmail

let configuration: NotificationConfiguration

let newConfiguration = configuration.setEmailNotificationsForSudoId(
    sudoId: sudoId,
    enabled: true or false
)

try await notificationClient.setNotificationConfiguration(
    config: NotificationSettingsInput(
        bundleId: "<bundle-id>",
        deviceId: "<device-id>",
        filter: newConfiguration.configs,
        services: [sudoEmailNotificationFilterClient.getSchema()]
    )
)

Managing notification configuration for specific email addresses

Whether or not notifications that pertain to a particular email address are sent by the Sudo Platform Email Service can be controlled by adjusting the notification configuration for the device.

Whether or not notifications are currently enabled for a particular email address can be determined as follows for each platform:

import SudoNotification
import SudoEmail

let configuration: NotificationConfiguration

if configuration.areNotificationsEnabled(
       forEmailAddressWithId: emailAddressId
   ) {
   // Notifications are enabled
} else {
   // Notifications are not enabled
}

Notifications can be enabled or disabled for a particular email address by modifying and updating the NotificationConfiguration for the device:


import SudoNotification
import SudoEmail

let configuration: NotificationConfiguration

let newConfiguration = configuration.setEmailNotificationsForAddressId(
    emailAddressId: emailAddressId,
    enabled: true or false
)

try await notificationClient.setNotificationConfiguration(
    config: NotificationSettingsInput(
        bundleId: "<bundle-id>",
        deviceId: "<device-id>",
        filter: newConfiguration.configs,
        services: [sudoEmailNotificationFilterClient.getSchema()]
    )
)

Notification Reception

Sudo Platform notification messages contain encrypted content that needs to be decoded. The specific ways that notifications are received and decoded is platform specific. See the platform specific sections below for information on receiving and decoding Sudo Platform Email Service notifications.

On iOS, in order to decode the notification you must implement a notification service app extension as described in Modifying content in newly delivered notifications in the iOS developer documentation. This allows you to use information in the encrypted payload of the notification to modify the notification for display to the user.

If you receive notifications from other sources, you must first determine the source of the notification.

The Sudo Platform Notification SDK for iOS provides a DefaultSudoNotifiableClient class that decodes all Sudo Platform notifications. It is initializes with a service SDK specific implementation of SudoNotifiableClient. The Sudo Platform Email SDK provides DefaultSudoEmailNotifiableClient for this purpose.

To initialize the DefaultSudoNotifiableClient to decode email service notifications, do the following within your UNNotificationServiceExtension implementation's didReceive method.

Separate SudoNotificationExtension and SudoEmailNotificationExtension PODs are provided containing the minimal code needed to implement the notification service app extension with minimal overhead.

import SudoNotificationExtension
import SudoEmailNotificationExtension

class MyNotificationServiceExtension: UNNotificationServiceExtension {

    override func didReceive(
        _ request: UNNotificationRequest,
        withContentHandler contentHandler: @escaping (UNNotificationContent) -> Void
    ) {

    let bestAttemptContent = (request.content.mutableCopy() as? UNMutableNotificationContent)
    guard let bestAttemptContent = bestAttemptContent else {
        contentHandler(request.content)
        return
    }

    let sudoEmailNotifiableClient = DefaultSudoEmailNotifiableClient(keyNamespace: "eml")
    let sudoNotifiableClient = try DefaultSudoNotifiableClient(
        notifiableClients: [sudoEmailNotifiableClient]
    )

The keyNamespace specified in the construction of the DefaultSudoEmailNotifiableClient must match the keyNamespace you use to construct DefaultSudoEmailClient in the main application. If the key namespaces do not match then the DefaultSudoEmailNotifiableClient will not be able to access the keys needed to decrypt the notification payload.

To access the keys, the application and the notification service app extension must both have the Keychain Sharing capability and have the same Keychain group.

Once you have initialized the DefaultSudoNotifiableClient you can then extract any Sudo Platform notification data from the notification. If no data is extracted then the notification has come from a source other than a Sudo Platform service.

    guard let sudoNotificationData = sudoNotifiableClient.extractData(
        fromNotificationContent: bestAttemptContent
    ) else {
        // Handle non-Sudo Platform notification
    }

Once you have identified the notification as originating at a Sudo Platform service, you can then decode it to a specific notification class:

    switch sudoNotifiableClient.decodeData(data: sudoNotificationData) {
    case let decoded as EmailMessageReceivedNotification:
        // handle EmailMessageReceivedNotification
    case let decoded as ....
        // handle other Sudo Platform notification
    }

Notification Types

The Sudo Platform Email Service supports the following notification types

EmailMessageReceivedNotification

Sent on receipt of an email message, this notification contains metadata about the message that was received.

Last updated