Enabling Tracking

Enable

Call enable with a platform-specific EngagementCloudConfiguration to start tracking. Calling enable with a valid configuration allows the SDK to track user activity, send custom events, and receive messages such as in-app and push notifications. See Initial Configuration. The onContactLinkingFailed parameter is a required callback invoked when automatic contact linking fails.

warning

The onContactLinkingFailed callback must be set on each app start, either by passing it to enable or by calling the setOnContactLinkingFailedCallback method.

Android

EngagementCloud.setup.enable(
    config = AndroidEngagementCloudSDKConfig(
        applicationCode = "ABCDE-12345",
        launchActivityClass = MainActivity::class.java
    ),
    onContactLinkingFailed = {
        // Example: Prompt user to log in and retrieve their contact identifier
        val loggedInUser = showLoginDialogAndAwaitResult()
        loggedInUser?.let { LinkContactData(contactFieldValue = it.userId) }
    }
)

Kotlin Multiplatform

EngagementCloud.setup.enable(
    config = SdkConfig(
        applicationCode = "ABCDE-12345"
    ),
    onContactLinkingFailed = {
        // Example: Prompt user to log in and retrieve their contact identifier
        val loggedInUser = showLoginDialogAndAwaitResult()
        loggedInUser?.let { LinkContactData(contactFieldValue = it.userId) }
    }
)

iOS

try await EngagementCloud.shared.setup.enable(
    config: EngagementCloudConfig(applicationCode: "ABCDE-12345"),
    onContactLinkingFailed: { onSuccess, onError in
        Task {
            guard let loggedInUser = await showLoginDialogAndAwaitResult() else { return }
            onSuccess(LinkContactDataContactFieldValueData(contactFieldValue: loggedInUser.userId))
        }
    }
)

Web

await window.EngagementCloud.setup.enable(
    { applicationCode: "ABCDE-12345" },
    async () => {
        // Example: Prompt user to log in and retrieve their contact identifier
        const loggedInUser = await showLoginDialogAndAwaitResult();
        if (!loggedInUser) return null;
        return { contactFieldValue: loggedInUser.userId };
    }
);

Parameters

Parameter	Type	Required	Description
config	EngagementCloudSDKConfig	Yes	Platform-specific SDK configuration
onContactLinkingFailed	Callback returning LinkContactData?	Yes	Invoked when contact linking fails. Return contact data for the SDK to retry linking.

LinkContactData

The LinkContactData object can contain either:

• contactFieldValue: A string identifier for the contact
• openIdToken: An OpenID token for authenticated linking

Disable

To stop tracking while keeping the SDK initialized, call disable.

Android

EngagementCloud.setup.disable()

Kotlin Multiplatform

EngagementCloud.setup.disable()

iOS

await EngagementCloud.shared.setup.disable()

Web

await window.EngagementCloud.setup.disable();

isEnabled

Checks whether the SDK is enabled.

Android

EngagementCloud.setup.isEnabled()

Kotlin Multiplatform

EngagementCloud.setup.isEnabled()

iOS

await EngagementCloud.shared.setup.isEnabled()

Web

await window.EngagementCloud.setup.isEnabled();

setOnContactLinkingFailedCallback

warning

Must be called on each app start.

Sets the callback used to acquire contact data when automatic contact linking fails. Must be called on each app start.

Android

EngagementCloud.setup.setOnContactLinkingFailedCallback {
    // Prompt user to log in and retrieve their contact identifier
    val loggedInUser = showLoginDialogAndAwaitResult()
    loggedInUser?.let { LinkContactData(contactFieldValue = it.userId) }
}

Kotlin Multiplatform

EngagementCloud.setup.setOnContactLinkingFailedCallback {
    // Prompt user to log in and retrieve their contact identifier
    val loggedInUser = showLoginDialogAndAwaitResult()
    loggedInUser?.let { LinkContactData(contactFieldValue = it.userId) }
}

iOS

EngagementCloud.shared.setup.setOnContactLinkingFailedCallback(
    onContactLinkingFailed: { onSuccess, onError in
        Task {
            guard let loggedInUser = await showLoginDialogAndAwaitResult() else { return }
            onSuccess(LinkContactDataContactFieldValueData(contactFieldValue: loggedInUser.userId))
        }
    }
)

Web

window.EngagementCloud.setup.setOnContactLinkingFailedCallback(async () => {
    // Prompt user to log in and retrieve their contact identifier
    const loggedInUser = await showLoginDialogAndAwaitResult();
    if (!loggedInUser) return null;
    return { contactFieldValue: loggedInUser.userId };
});

Parameters

Parameter	Type	Description
onContactLinkingFailed	Callback returning LinkContactData?	Invoked when contact linking fails. Return contact data for the SDK to retry linking.

What Happens After Enabling the SDK

Aspect	Behavior After Enable
Event Dispatch	Sends queued and new events
Push Token	Attempts to register the token if one was captured before enabling
Contact Re-Link	Re-links the contact automatically if previously linked
In-App	Starts listening for in-app message triggers

Idempotency and Errors

Calling enable again returns an error that is safe to ignore.

Before You Start Tracking Events

Follow this order:

Initialize the SDK -> Enable the SDK -> Link a contact -> Register a push token -> Track events

Disabling Tracking

For example, when a user revokes consent:

• Queued events remain in the database and are sent when the SDK is re-enabled.
• The SDK automatically calls unlink(). When calling enable() again, call link() to re-identify the contact.
• Push tokens are not deleted automatically. Call EngagementCloud.push.clearToken() if needed.