Configuring at Runtime

Use these functions to read and modify the SDK's runtime configuration, including contact language and application code settings.

getApplicationCode

Returns the application code as a string, or null if not set.

Android

EngagementCloud.config.getApplicationCode()

Kotlin Multiplatform

EngagementCloud.config.getApplicationCode()

iOS

await EngagementCloud.shared.config.getApplicationCode()

Web

await window.EngagementCloud.config.getApplicationCode();

getClientId

Returns the client ID as a string.

Android

EngagementCloud.config.getClientId()

Kotlin Multiplatform

EngagementCloud.config.getClientId()

iOS

await EngagementCloud.shared.config.getClientId()

Web

await window.EngagementCloud.config.getClientId();

getLanguageCode

Returns the language code as a string.

Android

EngagementCloud.config.getLanguageCode()

Kotlin Multiplatform

EngagementCloud.config.getLanguageCode()

iOS

await EngagementCloud.shared.config.getLanguageCode()

Web

await window.EngagementCloud.config.getLanguageCode();

getApplicationVersion

Returns the application version as a string.

Android

EngagementCloud.config.getApplicationVersion()

Kotlin Multiplatform

EngagementCloud.config.getApplicationVersion()

iOS

await EngagementCloud.shared.config.getApplicationVersion()

Web

await window.EngagementCloud.config.getApplicationVersion();

getSdkVersion

Returns the SDK version as a string.

Android

EngagementCloud.config.getSdkVersion()

Kotlin Multiplatform

EngagementCloud.config.getSdkVersion()

iOS

await EngagementCloud.shared.config.getSdkVersion()

Web

await window.EngagementCloud.config.getSdkVersion();

getCurrentSdkState

Returns the SDK state as an SdkState enum: Active, OnHold, Initialized, or UnInitialized.

Android

EngagementCloud.config.getCurrentSdkState()

Kotlin Multiplatform

EngagementCloud.config.getCurrentSdkState()

iOS

await EngagementCloud.shared.config.getCurrentSdkState()

Web

await window.EngagementCloud.config.getCurrentSdkState();

On Web, the method returns a string instead of an enum. The possible values are "active", "on_hold", "un_initialized", and "initialized".

SdkState	Description
Active	The SDK is enabled and processing requests.
OnHold	The SDK is temporarily paused, for example during an application code change.
Initialized	The SDK is initialized but not yet enabled.
UnInitialized	The SDK is not initialized.

changeApplicationCode

Changes the application code. The new code is validated before the change takes effect.

warning

Changing the application code automatically resets the contact to anonymous. Call link() to re-identify the user.

Android

EngagementCloud.config.changeApplicationCode(applicationCode)

Kotlin Multiplatform

EngagementCloud.config.changeApplicationCode(applicationCode)

iOS

await EngagementCloud.shared.config.changeApplicationCode(applicationCode)

Web

await window.EngagementCloud.config.changeApplicationCode(applicationCode);

• applicationCode is the string value of the new application code

setLanguage

Sets the contact language. This determines the language in which contacts receive messages across all channels.

Android

EngagementCloud.config.setLanguage(language)

Kotlin Multiplatform

EngagementCloud.config.setLanguage(language)

iOS

await EngagementCloud.shared.config.setLanguage(language)

Web

await window.EngagementCloud.config.setLanguage(language);

• language is the string value of the BCP-47 code of the new language Example input format: "en-US", "zh-Hans-CN"

resetLanguage

Resets the contact language to the device language.

Android

EngagementCloud.config.resetLanguage()

Kotlin Multiplatform

EngagementCloud.config.resetLanguage()

iOS

await EngagementCloud.shared.config.resetLanguage()

Web

await window.EngagementCloud.config.resetLanguage();

getNotificationSettings

Returns the current notification settings. The return type is platform-specific.

Android

EngagementCloud.config.getNotificationSettings()

Returns an AndroidNotificationSettings object:

Property	Type	Description
areNotificationsEnabled	Boolean	Whether notifications are enabled for the app.
importance	Int	The importance level of the notification channel.
channelSettings	List<ChannelSettings>	Settings for each notification channel.

Each ChannelSettings entry contains:

Property	Type	Description
channelId	String	The notification channel identifier.
importance	Int	The importance level of the channel.
canBypassDnd	Boolean	Whether the channel can bypass Do Not Disturb.
canShowBadge	Boolean	Whether the channel can show badges.
shouldVibrate	Boolean	Whether the channel vibrates.
shouldShowLights	Boolean	Whether the channel shows lights.

Kotlin Multiplatform

EngagementCloud.config.getNotificationSettings()

Returns a NotificationSettings object with the cross-platform subset of notification settings. Available fields depend on the platform target, but the return type is consistent across all KMP targets.

iOS

await EngagementCloud.shared.config.getNotificationSettings()

Returns an IosNotificationSettings object:

Property	Type	Description
authorizationStatus	IosAuthorizationStatus	The app's notification authorization status.
soundSetting	IosNotificationSetting	Whether sounds are enabled.
badgeSetting	IosNotificationSetting	Whether badges are enabled.
alertSetting	IosNotificationSetting	Whether alerts are enabled.
notificationCenterSetting	IosNotificationSetting	Whether notifications appear in Notification Center.
lockScreenSetting	IosNotificationSetting	Whether notifications appear on the lock screen.
carPlaySetting	IosNotificationSetting	Whether notifications appear in CarPlay.
alertStyle	IosAlertStyle	The alert style for notifications.
showPreviewsSetting	IosShowPreviewSetting	The preview display setting.
criticalAlertSetting	IosNotificationSetting	Whether critical alerts are enabled.
providesAppNotificationSettings	Boolean	Whether the app provides its own notification settings UI.
scheduledDeliverySetting	IosNotificationSetting	Scheduled delivery setting (iOS 15.0+).
timeSensitiveSetting	IosNotificationSetting	Time-sensitive notification setting (iOS 15.0+).

Web

await window.EngagementCloud.config.getNotificationSettings();

Returns a WebNotificationSettings object:

Property	Type	Description
permissionState	PermissionState	The push notification permission state: "granted", "denied", or "prompt".
isServiceWorkerRegistered	Boolean	Whether the push service worker is registered.
isSubscribed	Boolean	Whether the user is subscribed to push notifications.

Best Practices for Language Handling

• Use valid BCP-47 codes (en-US, de-DE, zh-Hans-CN).
• Call setLanguage only when the user changes the app language. There is no need to call it on each app start.
• Calling resetLanguage reverts to either the device or browser language.

Failure Modes:

Cause	Effect
Invalid code format	Operation returns failure result or throws (platform).
Language not supported by SAP Engagement Cloud	Silent fallback to the device language.

Version Introspection

To display runtime details in a diagnostics screen:

Android

val sdkVersion = EngagementCloud.config.getSdkVersion()
val appVersion = EngagementCloud.config.getApplicationVersion()
val language = EngagementCloud.config.getLanguageCode()

Kotlin Multiplatform

val sdkVersion = EngagementCloud.config.getSdkVersion()
val appVersion = EngagementCloud.config.getApplicationVersion()
val language = EngagementCloud.config.getLanguageCode()

iOS

let version = try? await EngagementCloud.shared.config.getSdkVersion()

Web

const version = await window.EngagementCloud.config.getSdkVersion();

Thread-Safety and Concurrency

All configuration reads are fast and safe from any thread. Language and application code changes are serialized internally. Debounce user-facing controls to avoid triggering multiple concurrent changes.

Error Handling Examples

Android

EngagementCloud.config.setLanguage("xx-YY").onFailure { e ->
  logger.warn("Language update failed", e)
}

Kotlin Multiplatform

EngagementCloud.config.setLanguage("xx-YY").onFailure { e ->
  logger.warn("Language update failed", e)
}

iOS

do { try await EngagementCloud.shared.config.setLanguage("en-GB") } catch { print("Language failed: \(error)") }

Web

try { await window.EngagementCloud.config.setLanguage("en-GB"); } catch(e) { console.error("Language failed", e); }

Observability Tips

• Log the application code and SDK version once after calling enable().
• Include language and contact state in support bundles.
• Mask sensitive tokens.