.identify call

🚧

Note that Sherlock does not support tracking anonymous users.

The .identify call allows you to identify the users navigating through and using your application. This is a required step before tracking any user activity.

Using the .identify call is simple. As an example, if the user is [email protected], you would call:

sherlock.identify("{userID}");

You can optionally assign user traits when identifying the user:

sherlock.identify("1234", {
  first_name: "John",
  paid_user: true,
  plan_type: "Enterprise",
  created_at: "2019-03-27T01:20:00Z"
});

When to make .identify call

You should make an .identify call upon every page load to ensure that your user actions will be assigned correctly. You should set up the Sherlock library in your top-level template - the same place you add the snippet:

<script type="text/javascript">
  // snippet goes here
</script>
<script type="text/javascript">
  sherlock.load(apiKey);
  sherlock.identify(userID, {...traits...});
</script>

The library keeps track of the current user on the page. Once a user is identified, all subsequent .track calls will be scoped to that user.

You should also make separate .identify calls with any significant change in user status. For example:

  • Conversion from trial to paid
  • Upgrade/Downgrade
  • Cancellation
  • Change of location
  • Etc.

Recommended User traits

User traits are descriptive pieces of information about a user that can be sent with an .identifycall. While the traits you send are up to you, there are some standard traits that we recommend using for each user.

TRAIT

RECOMMENDATION

SAMPLE VALUES

DESCRIPTION

userID

Required

String or number

.identify calls require a UserID as the first argument.

email

Highly recommended

String

It is highly recommended you provide email addresses for your users as this will be the common identity that many of our connections will use.

name

Highly recommended

String

Providing a name for users will help make your Sherlock account look prettier. We use a name trait when displaying users in the application. if we don't have a name we display email addresses - which definitely don't look pretty.

created_at

Highly recommended

Date (ISO8601 or unix timestamp)

This trait is necessary to calculate the tenure of your users.

*If you don't provide a created_at trait for an account, we will use the earliest created_at date for the users on that account to calculate the account tenure.

role

Recommended

{ Admin, owner ,
team member ,
manager }

It’s very helpful to include the role of your users
as a trait. In Sherlock, it is very helpful to set
different engagement scores for different user
types.