Push API

Use the following methods to get, register, or clear the push token on the device: For details on the Web Push API please check out this page.

registerToken

Stores the push token locally and registers it with the contact profile, enabling push notifications.

Android

EngagementCloud.push.registerToken(token)

Kotlin Multiplatform

EngagementCloud.push.registerToken(token)

iOS

try await EngagementCloud.shared.push.registerToken(token: token)

Convert the deviceToken from the didRegisterForRemoteNotificationsWithDeviceToken callback to a String before passing it to the SDK. You can use the following code as an example:

//in Swift
let token = deviceToken.map { data in String(format: "%02.2hhx", data) }.joined()

• token refers to the string value of the push token.

getToken

Retrieves the currently registered push token.

Android

EngagementCloud.push.getToken().getOrNull()

Kotlin Multiplatform

EngagementCloud.push.getToken().getOrNull()

iOS

try await EngagementCloud.shared.push.getToken()

note

The SDK returns the deviceToken as a String, not as Data.

clearToken

Clears the push token from local storage and removes it from the contact profile, disabling push notifications.

Android

EngagementCloud.push.clearToken()

Kotlin Multiplatform

EngagementCloud.push.clearToken()

iOS

try await EngagementCloud.shared.push.clearToken()

Understanding Token Lifecycle

Stage	Description
Acquisition	Push provider issues token (FCM/HMS/APNs/Browser subscription)
Registration	registerToken stores the token locally and adds it to the contact profile
Rotation	Provider may rotate tokens periodically
Clearing	clearToken removes the token from the contact profile

Following Best Practices

• Register tokens immediately upon receipt. The SDK queues events before enable is called.
• Implement callbacks to handle token rotations from push providers.
• Avoid unnecessary registerToken calls. The SDK ignores unchanged tokens.
• Call clearToken only when a user revokes push notifications consent. Otherwise, keep the token for win-back campaigns.

Handling Errors

Android

EngagementCloud.push.registerToken(token).onFailure { e -> logger.warn("Push token failed", e) }

Kotlin Multiplatform

EngagementCloud.push.registerToken(token).onFailure { e -> logger.warn("Push token failed", e) }

iOS

do { try await EngagementCloud.shared.push.registerToken(token: token) } catch { print(error) }