Skip to main content

Linking Contacts

Use the following methods to identify users in SAP Engagement Cloud. Typically called during login and logout, but can be used independently.

Linking a Contact​

After the SDK is initialized and enabled, call the link method to identify the user with a contactFieldValue.

Without a linked contact, tracked events are attributed to an anonymous contact (if anonymous tracking is enabled).

EngagementCloud.contact.link(contactFieldValue)
  • contactFieldValue is the contact identifier as a string

linkAuthenticated​

After the SDK is initialized and enabled, call the linkAuthenticated method to identify the user with an openIdToken.

For more information, see OpenID Connect.

EngagementCloud.contact.linkAuthenticated(openIdToken)
  • openIdToken is the string value of the OpenID token

Unlinking a Contact​

Call unlink to return the user to an anonymous state.

EngagementCloud.contact.unlink()

Identity Strategy​

ApproachUse Case
Plain link (contactFieldValue)Basic identification
Authenticated link (OpenID)Strongly verified identity and session security
UnlinkLogout, consent revocation, user switch
  • Immediately after login, so subsequent events are attributed to the contact profile.
  • After calling enable. Events tracked before linking are queued and attributed once the contact is linked.

Effects of Unlinking​

  • Future events become anonymous.
  • Previously sent events retain prior contact attribution and cannot be anonymized retroactively. For deletion requests, contact support.

Error Handling Examples​

EngagementCloud.contact.link(value).onFailure { e -> logger.error("Link failed", e) }

OpenID Token Rotation​

When the token expires:

  1. Fetch the new OpenID token.
  2. Call linkAuthenticated(newToken).
  3. Verify that the SDK is using the new token.

Privacy Notes​

  • Avoid embedding full email or personally identifiable information in logs. Mask values instead.
  • Use authenticated links for actions that require secure identity.