Identifying contacts

Current version: 10.4

Contact identification is the process of connecting the current session, device, and contact session to an identifier. Use the IContactIdentificationManager.IdentifyAs() method to identify a contact. For example:

Important

Sitecore.Analytics.Tracking.Identification.IContactIdentificationManager is a transient service.

RequestResponse

var identificationManager = Sitecore.DependencyInjection.ServiceLocator.ServiceProvider.GetRequiredService<Sitecore.Analytics.Tracking.Identification.IContactIdentificationManager>();
Sitecore.Analytics.Tracking.Identification.IdentificationResult result = identificationManager.IdentifyAs(new Sitecore.Analytics.Tracking.Identification.KnownContactIdentifier("twitter", "myidentifier"));

if(!result.Success)
    {
        //check result.ErrorCode and result.ErrorMessage for more details
    }

Note

<name of a service> depends on the Sitecore.Context.Site and must be resolved in the context where it is available.

When IdentifyAs() is called during an anonymous contact’s session, one of the following occurs:

If the identifier does not exist, it is created. The current contact becomes known.
If the identifier does exist, the existing known contact is loaded from xConnect and merged with the anonymous contact.
If an explicit consent is required but no consent is provided by the contact, or, if the consent is revoked by the contact, identification fails.

The IdentifyAs method returns a Sitecore.Analytics.Tracking.Identification.IdentificationResult object, which contains the following properties:

A boolean Success property. The property is set to false if identification is unsuccessful.
An ErrorCode property (string), which contains the error code for a failed result.
An ErrorMessage property, which contains a message about the failed result.

Identifiers consist of an identifier and a source. An identifier is a unique piece of information about the contact, such as a username, and the identifier source indicates where the identifier came from. A contact can have multiple identifiers. The following table lists a few examples of known identifiers and sources:

Identifier	Source
myrtlesitecore	twitter
m_McSitecore	brandextranet
abc10769150	facebookauth

Important

You cannot use an anonymous identifier to identify a contact. The only exception to this rule is the alias identifier.

Tracker identifier

Every contact that has visited your website has an anonymous tracker identifier. The tracker identifier matches Sitecore.Analytics.Tracker.Current.Contact.ContactId property, and is different from the contact’s ID in xConnect. Refer to the Set contact facets topic for more information.

When to identify

Identification is separate from authentication, and usually occurs at the same time. However, once a contact has been identified on a device, the tracker uses the analytics cookie to automatically re-identify (not re-authenticate) that contact even when the ASP.NET session cookie is removed.

Depending on your requirements, there are different identification strategies that you can implement to identify contacts across their devices. For example:

Scenario	Identification
Contact logs in.	Username can be used as an identifier - call IdentifyAs(“usernamesource”, “username”) if login is successful.
Contact opens email link sent by E-mail Experience Manager.	Email link includes contact’s alias identifier in a query string. This data is used to identify the contact.

In the following example, contact identification occurs after the contact has successfully logged in:

Identifier sources

It is your responsibility to decide what source to use when identifying a contact. There is no central repository of sources. If contacts use the same details to login across all systems, ensure your source is consistent across all login and registration code.

Identification scenarios

The following table describes what happens when IdentifyAs() is called:

Contact in session	IdentifyAs() parameters	Identification
Contact in session is anonymous. Contact in session exists in xConnect as anonymous contact.	Identifier matches an existing, known contact in xConnect.	Information in the anonymous contact merges with the known contact, making the anonymous contact record obsolete and replacing it with a pointer to the known contact record. After merging, the context contact is deleted from the session state. The merged contact includes custom contact facets and interaction history.
Contact in session is anonymous. Contact in session does not exist in xConnect.	Identifier matches an existing, known contact in xConnect.	Tracker continues the current interaction on behalf of the known contact. No merge occurs, as anonymous contact did not exist in xConnect.
Contact in session is known. Contact in session exists in xConnect as a known contact.	Identifier matches an different known contact in xConnect.	Current interaction is terminated and a new interaction for the known contact begins. The new interaction begins on the last page of the terminated interaction, and the link between the current device and the known contact is updated.
Contact in session is anonymous. Contact in session does not exist in xConnect.	Identifier does not yet exist in xConnect.	The current contact is saved to xConnect along with a new known identifier, and the session continues.

Do you have some feedback for us?

If you have suggestions for improving this article,