Lifecycle and Consent

The SDK lifecycle controls when data collection begins relative to user consent and identification.

States Recap

State	Characteristics	Data Collection	Network Activity
Initialized	Context loaded, dependencies wired	None	None (except internal health)
Enabled	Tracking & features active	Yes (events, push registration)	Yes

Transition Rules

• Calling enable when already enabled returns an error that is safe to ignore.
• Calling disable stops future requests. Previously queued data is retained until the SDK is re-enabled.

Recommended Consent Flow

1. The SDK initializes automatically.
2. Present the consent UI to the user.
3. Register the push token.
4. After the user accepts, build an EngagementCloudConfiguration and call enable.
5. Link the contact if available. Without a linked contact, events are attributed to an anonymous contact.

Consent and Linking Strategies

Method	Pros	Cons
Enable early, then link later	Fast first event capture	Some events might be anonymous
Link before enabling	All events attributed	Slightly more complex gating
Delay both until consent	Maximum privacy compliance	Fewer early engagement signals

Pausing In-App Tracking During Sensitive Flows

During sensitive flows like payment or data entry, displaying in-app messages can be disruptive. Use pause and resume to control when overlays can appear:

Android

EngagementCloud.inApp.pause()
// ...
EngagementCloud.inApp.resume()

Kotlin Multiplatform

EngagementCloud.inApp.pause()
// ...
EngagementCloud.inApp.resume()

iOS

await EngagementCloud.shared.inApp.pause()
// ...
await EngagementCloud.shared.inApp.resume()

Web

This feature is not supported on Web.

Detecting Enabled State

Use EngagementCloud.setup.isEnabled() to check if tracking is enabled.

Re-Enable After Disable

Call enable again with the same or updated configuration. Since disable() automatically calls unlink(), you must call link() again to re-identify the contact. Language settings and the push token are preserved.

Error Handling Strategy

Wrap calls to handle failures gracefully:

Android

EngagementCloud.setup.enable(config)
  .onFailure { throwable -> log("Enable failed: $throwable") }

Kotlin Multiplatform

EngagementCloud.setup.enable(config)
  .onFailure { throwable -> log("Enable failed: $throwable") }

iOS

do { try await EngagementCloud.shared.setup.enable(config) } catch { print(error) }

Web

try { await window.EngagementCloud.setup.enable(config); } catch(e) { console.error(e); }

Handling Consent Revocation

1. Call disable().
2. The SDK automatically calls unlink() if a contact is linked. When calling enable() again, call link() to re-identify the contact.
3. Clear your app's local caches separately. The SDK does not manage them.

OpenID Rotation

If the token has expired:

1. Acquire a new token.
2. Call linkAuthenticated(newToken). You do not need to call unlink() first.