ContactManager reference
The ContactManager 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 in order to set their facets in xConnect.
The following example demonstrates 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
}
The ContactRepository should not be used. To modify a contact that does not have an ongoing session, use the xConnect Client API. 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() will save 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 demonstrates 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 will throw 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(Guid contactId) 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.
The RemoveFromSession() method is only available in 9.0 Update-1 onwards.