Initializing the SDK

Android

The SDK initializes automatically when the application starts. No manual setup is required.

Kotlin Multiplatform

The SDK initializes automatically when the application starts on Android. On other KMP targets, the platform-specific integration handles initialization.

iOS

The SDK initializes automatically when the application starts. Choose one of the options below.

Option A: Use EngagementCloudSDKAppDelegate (SwiftUI)

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

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

Option B: Inherit from EngagementCloudSDKAppDelegate

@UIApplicationMain
class AppDelegate: EngagementCloudSDKAppDelegate {
    override func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil) -> Bool {
        super.application(application, didFinishLaunchingWithOptions: launchOptions)
        // Your custom startup code here
        return true
    }
}

Option C: Manual AppDelegate

warning

Register the device token with try? await EngagementCloud.shared.push.registerToken(token: apnsToken) after receiving it from APNs.

@main
class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        Task {
            let center = UNUserNotificationCenter.current()
            center.delegate = EngagementCloud.shared.push.userNotificationCenterDelegate

            try? await EngagementCloud.shared.setup.enable(
                config: EngagementCloudConfig(applicationCode: <#String#>),
                onContactLinkingFailed: { onSuccess, onError in
                    Task {
                        guard let loggedInUser = await showLoginDialogAndAwaitResult() else { return }
                        onSuccess(LinkContactDataContactFieldValueData(contactFieldValue: loggedInUser.userId))
                    }
                }
            )

            try? await EngagementCloud.shared.contact.link(contactFieldValue: <String>)
            try? await EngagementCloud.shared.event.track(event: CustomEvent(name: <String>, attributes: <#Dictionary<String, String>>))
        }
        return true
    }
}

Web

The SDK initializes automatically after it is loaded.

Script:

<script src="engagement-cloud-sdk-loader.js"></script>

The loader provides window.EngagementCloud.loaded, a Promise that resolves when the SDK is ready.

NPM:

import("@sap/engagement-cloud-sdk")

info

The SDK does not send requests, track events, or collect any data until you call enable().

Lifecycle and Idempotency

Initialization is distinct from enabling the SDK:

Action	Effect
Auto-init (all platforms)	Prepares internal components. No network traffic.
initialize() (optional, iOS only)	Explicit initialization. Only needed with Option C.
enable(config)	Validates configuration, starts networking, processes pending events.
disable()	Stops new requests. Queued data is kept.

Calling enable more than once is safe — the SDK returns an “already enabled” error that you can ignore.

Best Practices

• Defer enable() until the user has given consent and the application code is available.
• To attribute early events to a known user, link the contact immediately after calling enable().
• For testing, call enable() with a test application code and verify events in SAP Engagement Cloud.