Skip to main content

Troubleshooting

This guide helps you diagnose and resolve common issues with the SAP Engagement Cloud SDK.

Initial Checklist​

SymptomCheck
ActivationWas enable() called without errors?
ContactIs link()/linkAuthenticated() succeeding?
PushDoes getToken() return a value?
NetworkAre there no proxies or firewalls blocking SAP Engagement Cloud endpoints?

Activation Issues​

Symptom: No SDK events are visible.

  • Confirm if the application code is correct.
  • Enable verbose logging.
  • Verify that disable() is not called unintentionally (search the codebase).

Duplicate Enable Attempts​

Symptom: "Already enabled" console log

  • It's safe to ignore this message.
  • Remove redundant enable() calls in AppDelegate or your app to prevent confusion.

Contact Linking Fails​

Likely causes:

  • contactFieldId is not configured or misconfigured for the application.
  • Network failure during linking.
  • OpenID token expired. Try refreshing and re-calling linkAuthenticated().

Push Token Is Null​

  • Verify push permissions are granted and the push provider is initialized correctly.

Push Is Not Delivered​

Likely causes for Android:

  • Notification channel importance was lowered. Check the channel settings.
  • Push token has changed but wasn't re-registered. Verify that you call registerToken.

Likely causes for iOS:

  • APNs permissions were denied and therefore re-prompt cannot happen automatically.
  • Notification Service Extension is missing or not subclassing EngagementCloudNotificationService.

Likely causes for Web:

  • Mismatch in service worker scope. Verify serviceWorkerScope matches the pages using the SDK.
  • VAPID public key is incorrect.

Rich Push Image Is Missing​

  • The image URL is not using HTTPS.
  • Image parameters are outside the recommended range. Aspect ratio: landscape ~16:9, width: 800-1038px.

Duplicate Push Notifications​

  • Verify only one push provider is registered on the device.

In-App Not Appearing​

  • Check isPaused; in-app may be paused.
  • Check isEnabled(); enable() may not have been called.
  • Check if the custom event name matches the in-app campaign trigger.
  • Contact isn't linked. Some campaigns target identified contacts only.
  • Android: In-App requires MainActivity to extend FragmentActivity or AppCompatActivity. ComponentActivity is not supported.
  • iOS: continueUserActivity isn't calling trackDeepLink.
  • Android: onNewIntent was overwritten and you forgot to do the manual call.
  • Web: URL is missing ems_dl query parameter.
  • Ensure the domain is associated and the intent filter matches.
  • Verify you're not manually tracking where automatic tracking is already happening.
  • Ensure your link includes the required query parameters.

Embedded Messaging Is Not Displaying Messages​

  • Check that the SDK was properly initialized.
  • Check that enable() was called with a valid application code.
  • Check that the correct contact is linked. If intended, verify that the contact is anonymous.
  • Check that the device is connected to the internet.

Language Wasn't Updated​

  • setLanguage returns a failure with an invalid code. Use valid BCP-47 codes (en-US, fr-FR).
  • After reset: confirm the default language falls back to the device language.

OpenID Rotation Problems​

  • Ensure you don't cache the OpenID token so it is up to date.
  • Always call linkAuthenticated with a fresh token. You don't need to call contact.unlink() to unlink first.

Handling Temporary Network Failures​

  • The SDK automatically retries failed network requests. Do not implement a manual retry logic.
  • Events are queued locally until successfully delivered. Clearing app data results in data loss.
  • Verify device connectivity. Check for network intermediaries (proxies, VPNs, firewalls, ad blockers, DNS-level filtering, TLS interception) or browser policies (CSP, CORS) that may block SDK endpoints.

Device Time Drift​

  • Large time differences may affect token expiration. Advise the user to correct their device time.

Rich Push Content Is Missing​

  • Service worker or notification service extension configuration is incorrect. Revalidate paths and permissions.

Event Name Does Not Match Campaign Trigger​

  • Align event naming and confirm the exact trigger in SAP Engagement Cloud.

Excessive High-Frequency Events​

  • Aggregate events into summary events.

Including IDs in Event Name​

  • Move IDs to event attributes instead.

Silent Failure After Enable​

  • Ensure you are checking the Result (Android/KMP) or catching errors (Swift/Web).

Invalid Application Code​

  • Check for typos or environment mismatches between staging and production.

How to Create a Support Ticket​

When contacting support, provide the following information:

  • Application code and version
  • SDK version (getSdkVersion())
  • Platform and OS version
  • Steps to reproduce the error and logs of failing calls
  • Severity and number of affected devices