ContactManager reference
The ContactManager class is used internally by Sitecore to pass requests on to the underlying XConnectDataAdapterProvider and is required in a limited number of scenarios, such as saving new, anonymous contacts to set their facets in xConnect.
The following example shows how to retrieve an instance of the contact manager in a Sitecore context:
var manager = Sitecore.Configuration.Factory.CreateObject("tracking/contactManager", true) as Sitecore.Analytics.Tracking.ContactManager;
if (manager != null)
{
// Use contact manager
}
To modify a contact that does not have an ongoing session, use the xConnect Client API. Do not use the ContactRepository. To update a contact with an ongoing session, refer to read this topic about updating facets.
AddIdentifier(Guid id,ContactIdentifier identifier)
This method adds an identifier to the current contact by calling xConnect in the background. Use this method if the current contact is known and you want to add an additional known or anonymous identifier. Calling AddIdentifier() saves the contact to xConnect if it has not already been saved.
The id in this context is the tracker identifier, not the contact ID generated by xConnect.
The following example shows you how to use AddIdentifier():
var manager = Sitecore.Configuration.Factory.CreateObject("tracking/contactManager", true) as Sitecore.Analytics.Tracking.ContactManager;
if (manager != null)
{
var currentContact = Sitecore.Analytics.Tracker.Current.Contact;
manager.AddIdentifier(currentContact.ContactId, new ContactIdentifier(identifier.Source, identifier.Identifier, ContactIdentificationLevel.Known));
}
Be aware of the following:
-
If the identifier you have tried to submit is already in use, xConnect throws an exception.
-
The
Sitecore.Analytics.Tracker.Current.Contact.Identifierscollection is currently not reloaded after an identifier has been added.
CreateContact([NotNull] ID id)
This method is used by the tracker to create a new tracker contact (Sitecore.Analytics.Tracking.Contact) in session - at this point, the contact does not exist in xConnect and the IsNew property is set to true.
The id in this context becomes the tracker identifier - it is not the final ID of the contact, which is generated by xConnect.
LoadContact([NotNull] string source,[NotNull] string identifier)
This method loads a contact with a matching identifier/source combination from the xDB and represents it as a Sitecore.Analytics.Tracker.Contact. You can use this method to check if a contact exists. To update a contact, use the xConnect Client API.
LoadContact(Guid contactId,bool exclusive=true)
This method loads a contact from the xDB where the contactId matches the contact’s tracker identifier and represents it as a Sitecore.Analytics.Tracker.Contact. In the unlikely event that you require an exclusive lock, remember to release the contact by using SaveAndReleaseInSharedSessionState.
The lock is a lock in shared session state, not a lock in xConnect. Other sources can still update the contact in xConnect.
SaveAndReleaseInSharedSessionState([NotNull] Contact contact)
This method is used in conjunction with LoadContact(). If you have requested an exclusive lock, use this method to release it.
SaveContactToCollectionDb(Contact contact)
This method saves a contact to xConnect without interrupting an ongoing session. Use this method if you need to save an anonymous contact before setting its facets. Make sure you set contact.ContactSaveMode to ContactSaveMode.AlwaysSave.
Do not use the SaveContactToCollectionDb(GuidcontactId) overload.
RemoveFromSession(Guid contactId)
This method removes a contact from shared session state. Use as shown in the following example:
manager.RemoveFromSession(Sitecore.Analytics.Tracker.Current.Contact.ContactId);
Sitecore.Analytics.Tracker.Current.Session.Contact = manager.LoadContact(Sitecore.Analytics.Tracker.Current.Contact.ContactId);
The contact is re-loaded into shared session state during the next request. Use this method if want to re-load a contact after using the xConnect Client API to make changes to that contact’s facets. This ensures that the data that is cached in session is as up-to-date as possible.
SetTrackingConsent(Contact contact, bool isConsentGiven)
This method sets tracking consent for the contact, for the current site. Then, if the contact is not new, it immediately saves the choice to the ConsentInformation xConnect facet:
manager.SetTrackingConsent(contact, true);
If the contact is new, it is saved at the same time as the ConsentInformation facet, when the current session expires.