Insights is joining HockeyApp! Read the blog post. FAQ

Identifying Users

PDF for offline use:
Related Links:

Let us know how you feel about this.


0/250
Thanks for the feedback!

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.

NOTE: You can identify the user at any time or even multiple times in your application (without worrying about multiple transmissions from the client), so you should add the call where it's most appropriate. To provide an example, we will be adding the call directly after our call to Insights.Initialize.

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.

NOTE: Up to 25 unique traits can be sent to Xamarin Insights within your application. The maximum amount of data that can be sent in a single Xamarin.Identify call is:

  • 100 characters for trait key name
  • 125 characters for trait values

Anything beyond this limit will be ignored

IMPORTANT: As the application developer, it is your responsibility to inform your users about the types of data you record, and to ensure your disclosure and storage of the data is covered by your privacy policy. You might also need to implement an application feature to disable Insights and prevent reporting of personal information, or any exception data at all.

Xamarin Workbook

If it's not already installed, install the Xamarin Workbooks app first. The workbook file should download automatically, but if it doesn't, just click to start the workbook download manually.