When using Xamarin Insights to collect analytic and crash reports from an application, we can optionally identify the individual user of the application on the device. This is not required, but having the identity of the user will allow you to get feedback on an application feature.

When including user tracking into an application, users should always be informed that we are tracking events and should be provided with a mechanism, such as a dialog box or setting, for them to opt out of the tracking.

Xamarin Insights provides two methods that can be used to identify a user: Basic or Advanced. Both will be covered in the sections below.

Basic Identification

The following code snippet shows how to add a single user-attribute to an application:

Insights.Identify("Unique User ID", "Key", "Value");

Where:

• Unique User ID – This is a unique identifier for the given user such as the ID they have used to sign up for your application. This can be anything, but it should uniquely identify your user.
• Key – This is the Type of the Value provided. This type can be anything you choose, as a suggestion there are a number of Traits that can be used as a Key for some of the most common types. These are explained in the Traits section.
• Value – Is the user-specific value for the Key specified above.

Advanced Identification

Advanced Identification uses a unique identifier and a Dictionary of key/value pairs. This will allow you to provide more information to help identify the user, such as their full name and email address, as in the example below:

var manyInfos = new Dictionary<string,string> {
    {"Email", "john.doe@company.com"} ,
    {"Name", "John Doe"}
}
Insights.Identify("Unique User ID", manyInfos);

Guest Identities

Insights will by default identify a user as a guest until they are identified through the Identify method.

To revert back to a guest identity after previously identifying a user, use the following API call:

Insights.Identify(Insights.Traits.GuestIdentifier, null);

Any track events sent after this call will be associated with a guest user.

Using Traits During Identification

No matter which method we choose to use, the Xamarin Insights NuGet has a number of keys, or Traits, that can be used when identifying a user.

The following keys are available:

• Address – Insights.Traits.Address
• Age – Insights.Traits.Age
• Avatar – Insights.Traits.Avatar
• Account Creation Date – Insights.Traits.CreatedAt
• Date of Birth – Insights.Traits.DateOfBirth
• Description of User – Insights.Traits.Description
• Email Address – Insights.Traits.Email
• First Name – Insights.Traits.FirstName
• Gender – Insights.Traits.Gender
• Last Name – Insights.Traits.LastName
• Full Name – Insights.Traits.Name
• Phone Number – Insights.Traits.Phone
• Website Address – Insights.Traits.Website

The code snippet below demonstrates adding the email address, full name, and description of a user by taking advantage of Traits:

Xamarin.Insights.Identify ("123456789", new Dictionary <string, string> { 
                {Xamarin.Insights.Traits.Email, "Jane.Doe@xamarin.com"},
                {Xamarin.Insights.Traits.Name, "Jane Doe"},
                {Xamarin.Insights.Traits.Description, "Writer, Developer, Explorer."},
                {"Title", "Code Monkey"}
            });

Insights.Traits provides the key when sending a trait collection to identify a user, but you are still responsible for providing the value for the given trait key. The value must be of type String.