User Identity Mapping

The Marketing Cloud Personalization identity system helps map events sent from the Salesforce Interactions SDK to user records in Personalization. This article describes how events are mapped to user records in Personalization by the identity system and guidance on how to configure the identity system.

For additional information about how to configure identity types and attributes in the Personalization UI, see Identity Management.

The following table lists and describes terms used on this page and in the Identity System.

Term	Description
User	A record in Personalization that attempts to track and personalize for one individual.
Anonymous ID	An identifier generated by the Web SDK that typically stays the same on a given device.
Named ID	An identifier set in the integration by calling `setUser`. Before the Identity feature was released, only one type of named ID was allowed per integration and per user (except for the Eloqua/Salesforce sync). With the release of the Identity feature, you can provide one or more identity attributes in addition to calling `setUser`.
Primary User ID	The internal identifier of the user record in Personalization that tracks the user's activity. Before the Identity feature was released, the primary user ID was always an anonymous ID or named ID called user ID.
Identity	A new concept introduced by the Identity feature that connects an arbitrary number of identifiers of different types with each user by Primary User ID.
Identity Type	The field used for identity matching; defined at the account level. Examples of identity types that you can create are email address and web user ID.
Identity Attribute	Any user attribute that is associated with an identity type; defined per dataset. These attributes can hold a user's identities. The attribute type must be string.
Identity Namespace	An Identity Type uniqueness value that indicates that the identity attribute value is assigned to only one user in the dataset. The identity namespace is equivalent to the dataset.
Resolve User ID	A command that requests the primary user ID associated with the set of identities.
Persisted User ID	Traditionally, the Web SDK remembered the user ID from the previous request using an opaque token encrypted by the server. Instead, with the new Identity feature, the same encrypted token stores the primary user ID resolved by the server along with the set of identities (name and value) provided for the user in this visit. New identities are added/replaced as they are provided to the Web SDK.

As of September 2020, Personalization supports a more powerful way to map incoming events to users based on one or more identity attributes present in the event. To use this functionality, you must have the Pipeline Identity Resolution feature enabled for the tenant, and the identity system must be configured for the dataset as described in the help article Configure the Identity System for the Web SDK.

After you've configured a dataset to use identity attributes for user identity resolution, users are looked up purely by identity attributes rather than by primary ID, which Personalization automatically generates for new users as a unique, 24-character hexadecimal ID. Note that the primary ID is now system-managed and can no longer be used to look up users.

The new system is more powerful for a number of reasons. Whereas previously a known user could only be identified with one ID, now the user can still be identified by any known identifier. For example, consider that you've configured a customer ID for the web identity attribute. If a user clicks a link in an email, the landing page URL could contain the user's email address or an ID assigned by the ESP. As long as they have been configured as identity attributes, the email address, or ESP ID could then be included in the event sent from the web to Personalization and used to look up an existing known user.

he approach described in this section is no longer supported in the Personalization identity system. This section only describes the legacy approach to assist users from migrating away from directly manipulating user.id.

Traditionally, Personalization mapped incoming web events to a known user based on an event's user.id property. This ID represented the primary ID of the user entity stored by Personalization. On specifying user.id within a visit, the server would include the user ID in the persistedUserId property in the event response. The Web SDK would then automatically include this encrypted form of the ID in subsequent events in the same visit. When the user.id property was not yet known, the Web SDK would automatically include an anonId property in the event, which contained a 16-character unique hexadecimal anonymous ID generated by the Web SDK. On receiving an event with a set user.id, Personalization would temporarily use this anonymous ID as the user's primary ID and then automatically merge the user into a user with a named ID.

The process for configuring the Personalization Identity System is detailed in the Identity Types and Attributes article on Salesforce Help and requires Personalization administrator permissions.

At a high level, you need to:

Review existing identity types: Personalization has five pre-built identity types: email address, Salesforce CRM contact ID, Salesforce CRM lead ID, Salesforce Marketing Cloud contact key, and secondary email address.
Add any additional identity types: Add any additional identity types to meet the needs of your business.
Configure attributes that correspond to identity types: Even if you do not add additional identity types, you need to configure the attributes that correspond to the default identity types.

In all events, the Web SDK includes a generated anonymous ID in the user.anonymousId property in the SalesforceInteractions namespace and the user.anonId property in the Evergage namespace. However, Personalization only considers the event anonymous and uses the anonymous ID as the user ID if the event does not include either user.id or any identity attributes are present in the event (remember user.id now represents the main web user ID, not the primary ID of the user in Personalization). If one or more identity attributes are present, Personalization uses them along with the main web user ID to look up an existing user. If not found, Personalization creates a user with a server-generated primary ID and does not use the anonymous ID from the event. As always, when an anonymous user logs in or is otherwise identified, Personalization automatically merges their activity into the identified user's profile.

Server-generated user IDs for identified users consist of 24 hexadecimal characters. On the other hand, Web-SDK-generated user IDs for anonymous users consist of 16 hexadecimal characters.

The persistedUserId property in the event response is still essential in web identity tracking. Traditionally, the persisted user ID was simply the encrypted user.id. After the new identity resolution is enabled, it is still an encrypted string, but it is encoded in two parts instead:

the server-resolved primary user ID
the list of identity attribute name-value pairs that were used to resolve the primary user ID. This list is cumulative throughout a visit.

For example, if page 1 sends emailAddress=joe@example.com and page 2 sends loyaltyId=abc123, Personalization uses both of these attributes to resolve the user and is encoded in the persisted user ID. As the Web SDK developer, you can include identity attributes in events as they are discovered; Personalization accumulates and remembers those IDs for the remainder of the visit. You do not need to track the set of discovered identity attributes.

Previously, the Personalization server would only include persistedUsedId in the response to the first event in a visit containing the user.id property. After identity resolution is enabled, the server will include the latest persistedUserId in every event response after the user is identified. The Web SDK automatically saves the most recently received persistedUserId in subsequent events, meaning that the Personalization server can reuse the resolved identity to avoid performing redundant identity resolutions. However, if an event contains a new identity attribute that is not already encoded in the persisted user ID, the server performs a new identity resolution that considers the new identity.

You can supply the default identity attribute you select as the Web SDK Identity as the user.id in web events configured in the Sitemap. In addition to the default identity, Personalization supports lookup and merges using the Web SDK for any other identity attributes supplied under user.attributes in web events. The set of all supplied identity attributes accumulates in the web browser. If there are changes to the default identity sent as user.id, Personalization clears the set of all identity attributes stored on the client. Changes to the default identity can happen when a different individual starts using the browser on the same device and logs in to a different account.

webUserIdentityTypeId is set to webId. The user's web ID is known, so the Web SDK sends an event containing:

The Personalization server checks for an existing user with a webId identity attribute with value abc123. If found, the event activity is tracked against that user. If not, a new user is created with a generated primary ID, such as 8675309abacab5551212acdc, and attribute webId with a value such as abc123. If there was any previous activity for the anonymous user with ID 0123456789abcdef, that activity is merged into the identified user.

An alternate way to send the same information would be through the following event:

webUserIdentityTypeId is set to webId. The user's web ID is not known by the beacon, but the user's email address is known (a common scenario for an email clickthrough, or a non-logged-in user who signs up for an email list), so the Web SDK sends an event containing:

The Personalization server checks if there is an existing user with a emailAddress identity attribute with value billybob@example.com. If found, the event activity is tracked against that user. If not, a new user is created with a generated primary ID, such as 8675309abacab5551212acdc, and attribute emailAddress with value billybob@example.com. If there was any previous activity for the anonymous user with ID 0123456789abcdef, that activity is merged into the identified user.

webUserIdentityTypeId is set to webId. Both the user's web ID and email address are known, so the web SDK sends an event containing:

The Personalization server checks for existing users with webId identity attribute with a value of abc123 or emailAddress identity attribute with a value of billybob@example.com. Typically for a repeat visit, a single existing user is matched, but it is possible that two users could be matched - one user with webId=abc123 and another user with emailAddress=billybob@example.com. When two users are matched, the Personalization server selects the user who was most recently active before this event. The activity from the other user is automatically merged into the selected user, and the other user is deleted from the system.

The resulting user record looks like:

where 8675309abacab5551212acdc is the ID of the user that was selected based on having more recent activity than the other user.