Push Integration

The SAP Engagement Cloud SDK supports push messages with rich content such as long text, images, and actions. These actions include push-to-in-app campaigns, opening external URLs, custom event tracking, and more.

A device must meet the following prerequisites to receive push notifications:

• The device registers with the platform-specific provider and, on success, receives a pushToken. The provider forwards messages sent with this token to the device.
• The application asks the user for consent to display push messages. If the user denies consent, the application does not show notifications, even if the rest of the requirements are met.
• The pushToken is registered to the contact profile by calling the registerToken method provided by the SDK.

Prerequisites

Android

• Add the required dependencies for the selected provider(s) to your project
• If you support Android API levels above 26, set up your notification channels within your application.
• To integrate multiple push providers, see Using Multiple Push Providers.
• For FCM, download the google-services.json from Firebase and include it in the application.
• For HMS, download the agconnect-services.json from Huawei and include it in the application.

Kotlin Multiplatform

Kotlin Multiplatform apps run on multiple platforms. The push prerequisites depend on the platform the app is running on. Refer to the Android and iOS tabs for the platform-specific requirements.

iOS

Add the Push notifications capability to the application on the Signing & Capabilities tab.

Web

When setting up the SDK, also set up the Web Push capabilities for your domain and include the vapid public key in the configuration.

Registering for Push Notifications

Android

If you support Android API levels above 26, set up your notification channels within your application.

The SDK's FCM and HMS library modules include the required messaging service declarations in their own AndroidManifest.xml files. These are automatically merged into your application manifest by the Android build system — you do not need to declare them manually.

note

In case of HMS, the SDK automatically enables the hms-push-kit, you can overwrite it by following the Official Guide

note

For working push integration Google Services Plugin is required: verify that you have included Google Services Plugin (com.google.gms.google-services) in your app's build.gradle file's plugins section.

Once the SDK dependency is added, the application receives a pushToken when the application is started. By default the SDK tracks the pushToken automatically when enable is called.

Custom Push Notification Icon

By default, the SDK uses a built-in notification icon. To display your own custom icon for push notifications, add a meta-data entry inside the <application> tag of your AndroidManifest.xml:

<meta-data
    android:name="com.sap.ec.small_notification_icon"
    android:resource="@drawable/notification_icon" />

Replace @drawable/notification_icon with a reference to your own drawable resource.

Kotlin Multiplatform

Kotlin Multiplatform apps run on multiple platforms. The push registration mechanism depends on the platform the app is running on. Refer to the Android and iOS tabs for the platform-specific registration steps.

Once the platform-specific setup is complete, the application receives a pushToken when the application is started. By default the SDK tracks the pushToken automatically when enable is called.

iOS

With EngagementCloudSDKAppDelegate

If you're using the EngagementCloudSDKAppDelegate then the following steps are completed automatically once the application is started:

• userNotificationCenterDelegate is registered as a delegate on the UserNotificationCenter to handle notifications.
• The application registers for remote notifications using UIApplication.shared.registerForRemoteNotifications().
• If the registration succeeds, the received deviceToken is registered on the SAP Engagement Cloud systems, after enable is called.
• The deviceToken is stored locally until the SDK is enabled.
• The token can be accessed using the getToken() method on the push API.

Example usage of the EngagementCloudSDKAppDelegate:

@main
struct iOSApp: App {
    @UIApplicationDelegateAdaptor private var appDelegate: EngagementCloudSDKAppDelegate

    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}

Without EngagementCloudSDKAppDelegate

If you choose to not use the AppDelegate solution, you call the necessary methods on the API in your AppDelegate's didFinishLaunchingWithOptions method.

• You create an EngagementCloudSDKConfiguration.
• You register for remote notifications.
• You register the acquired deviceToken using the registerToken() method.
• The deviceToken is stored locally until the SDK is enabled.

NotificationService Setup

1. Add a new target for the notification service extension to your project.

2. Add the EngagementCloudNotificationService to this target in XCode.

3. Open the NotificationService Class in the Target

• import the EngagementCloudSDKNotificationService
• extend the class UNNotificationServiceExtension
• create an instance of the EngagementCloudNotificationService
• delegate calls to the EngagementCloudNotificationService

class NotificationService: UNNotificationServiceExtension {
    let engagementCloudNotificationService = EngagementCloudNotificationService()

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

    override func serviceExtensionTimeWillExpire() {
        engagementCloudNotificationService.serviceExtensionTimeWillExpire()
    }
}

4. Request authorization for push notifications in the AppDelegate application:didFinishLaunchingWithOptions: method.

info

You can skip this step if you are using the EngagementCloudSDKAppDelegate.

application.registerForRemoteNotifications()

var options: UNAuthorizationOptions = [.alert, .sound, .badge]
UNUserNotificationCenter.current().requestAuthorization(options: options) { [unowned self] granted, error in
    print(granted, error ?? "no error")
    if (granted) {
        UNUserNotificationCenter.current().delegate = EngagementCloud.shared.push.userNotificationCenterDelegate
    }
}

5. If needed, use other UNUserNotificationCenterDelegate.

If you need to use other UNUserNotificationCenterDelegate providers, you can register them with the SDK using the registerNotificationCenterDelegate method. For details, see Using Multiple Push Providers.

Web

Service Worker

A service worker is a script the browser runs in the background, separate from the web page. Its task is to receive push events.

If your website already has a service worker, import the SDK's service worker by adding the following line to your existing service worker file:

self.importScripts("https://emartech.github.io/engagement-cloud-sdk/<latest-version>/ec-service-worker.js")

Replace <latest-version> with an exact version like 4.0.0 or latest.

If your website does not have a service worker, create a file called service-worker.js, add the line above, and place it in the website's root directory.

caution

The service worker file must be stored in the website's root directory.

Subscription to web push notifications should happen after user interaction. Use the subscribe method on the Web Push API to register the service worker and create the push subscription using the applicationServerKey provided in the configuration.

Push Lifecycle

Phase	Android/iOS	Web
Permission Prompt	System dialog	Browser notification permission
Token Fetch	FCM/HMS/APNs callback	Service worker subscription
Registration	registerToken	registerToken
Delivery	OS routes and displays	Service worker displays

Campaign Action Types

• Launch activity or deep link
• Open external URL
• Trigger custom event
• Show in-app message (push-to-inapp)

Reliability Practices

Practice	Benefit
Early token registration	Ensures campaigns reach first session
Channel importance audit (Android)	Avoid silent demotion
Delegate chain verification (iOS)	Prevent lost tracking

Rich Content Considerations

• Validate image URL reachability (HEAD request) on the server side before sending.
• Provide alternative fallback text for screens with limited space and for accessibility reasons.

Token Rotation Handling

On Android and iOS, token rotation is handled automatically via provider callbacks. On Web, browser subscription changes trigger re-registration. Do not poll for token updates.

Monitoring Recommendations

Track the following information internally:

• Registration success timestamp
• Last token change
• Delivery success events (future event types)