# 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](https://help.salesforce.com/s/articleView?id=sf.mc_pers_identity.htm).

## Terms

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. |

## Current Best Practice - Look Up Users Using Identity Attributes

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](https://help.salesforce.com/s/articleView?id=sf.mc_pers_identity_web_sdk_configure.htm).

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.

## The Traditional Approach - Look Up Users via Primary ID

:::important
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.

## Configuring the Identity System

The process for configuring the Personalization Identity System is detailed in the [Identity Types and Attributes](https://help.salesforce.com/s/articleView?id=sf.mc_pers_identity_type_attributes.htm) 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.

## Anonymous Users

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.

:::note
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.
:::

## Persisted User ID

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.

## Sending Identities Through the Sitemap

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.

### Examples

#### Scenario 1: Only web user ID is known

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

```sfdocs-code {"lang":"javascript", "title": "SalesforceInteractions Namespace"}
{
    user: {
        anonymousId: '0123456789abcdef',
        id: 'abc123'
    }
}
```

```sfdocs-code {"lang":"javascript", "title": "Evergage Namespace"}
{
    user: {
        anonId: '0123456789abcdef',
        id: 'abc123'
    }
}
```

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:

```sfdocs-code {"lang":"javascript", "title": "SalesforceInteractions Namespace"}
{
    user: {
        anonymousId: '0123456789abcdef',
        identities: {
            webId: 'abc123'
        }
    }
}
```

```sfdocs-code {"lang":"javascript", "title": "Evergage Namespace"}
{
    user: {
        anonId: '0123456789abcdef',
        attributes: {
            webId: 'abc123'
        }
    }
}
```

#### Scenario 2: Only some other identity attribute is known

`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:

```sfdocs-code {"lang":"javascript", "title": "SalesforceInteractions Namespace"}
{
    user: {
        anonymousId: '0123456789abcdef',
        identities: {
            emailAddress: 'billybob@example.com'
        }
    }
}
```

```sfdocs-code {"lang":"javascript", "title": "Evergage Namespace"}
{
    user: {
        anonId: '0123456789abcdef',
        attributes: {
            emailAddress: 'billybob@example.com'
        }
    }
}
```

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.

#### Scenario 3: Web user ID and another identity attribute are known but match two different users

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

```sfdocs-code {"lang":"javascript", "title": "SalesforceInteractions Namespace"}
{
    user: {
        anonymousId: '0123456789abcdef',
        id: 'abc123',
        identities: {
            emailAddress: 'billybob@example.com'
        }
    }
}
```

```sfdocs-code {"lang":"javascript", "title": "Evergage Namespace"}
{
    user: {
        anonId: '0123456789abcdef',
        id: 'abc123',
        attributes: {
            emailAddress: 'billybob@example.com'
        }
    }
}
```

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:

```sfdocs-code {"lang":"javascript", "title": "SalesforceInteractions Namespace"}
{
    id: '8675309abacab5551212acdc',
    identities: {
        webId: 'abc123',
        emailAddress: 'billybob@example.com'
    },
    <merged activity from both matched users>
}
```

```sfdocs-code {"lang":"javascript", "title": "SalesforceInteractions Namespace"}
{
    id: '8675309abacab5551212acdc',
    attributes: {
        webId: 'abc123',
        emailAddress: 'billybob@example.com'
    },
    <merged activity from both matched users>
}
```

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

## See Also

- [*Salesforce Help*: Identity Management](https://help.salesforce.com/s/articleView?id=sf.mc_pers_identity.htm)
- [*Salesforce Help*: Configure the Identity System for the Web SDK](https://help.salesforce.com/s/articleView?id=sf.mc_pers_identity_web_sdk_configure.htm)