Identify logged in users and send custom properties

Gist gives you the ability to use the rich information about your users to build custom segments, and better target your users to send relevant and useful emails and messages.

The primary way of enriching user data in Gist is the 'identify' method. The identify method allows you to identify users with a unique identifier and maintain user histories across sessions and devices under a single profile. It also allows you to attach custom properties to your users when they are identified.

The process of 'identifying' an anonymous visitor as a known user is a crucial part of your funnel, and requires special tracking. Tracking signups correctly in your marketing funnels and identifying those new users is important so their information can be sent to your sales, support and email tools.

Anonymous Users

When a person interacts with your site or app, Gist generates a random unique user ID and stores it in a cookie. You won't be able to see these users in your Gist project but you should know that Gist tracking code tracks all anonymous users and their user histories and once you identify these anonymous users, you can instantly access all they previous activities. 

Identified Users

You can use the identify call to attach your own unique User ID to a user. The identify call takes a single case-sensitive string value as an argument.

Every identified user must be assigned a unique userId so they can be tracked consistently across different browsers or devices without any inconsistencies. When a new user registers on your website, they should be assigned a userId at that point. 

We recommend using database IDs instead of simple email addresses or usernames because database IDs never change. That guarantees that even if the user changes their email address, you can still recognize them as the same person on Gist, and be able to correlate their tracked data with your own internal database.

If you use the same identity for another user, their past sessions and event activity will be merged into the existing Gist user with that identity. That is why it is important to note that each user must be given a unique user ID.

When should you call identify?

The identify call can be made at any time, and as many times as needed. We recommend making the identify call a single time when the user’s account is first created, and only identifying again later when their traits change.

The typical place for an identify call includes:

• When a user registers
• When a user logs in
• When a user updates their info (when they add a new address, billing method, change plans, etc.)
• Upon loading any pages that are accessible by a logged in user (optional)

How to make the identify call?

If you assign the same identity to a user on a separate device, their past sessions and event activity will be merged into the existing Gist user with that identity.

gist.identify('12345', {
    "email": "johndoe@example.com"
});

Here, the argument for the identify call is a case-sensitive string that uniquely identifies a user, such as an email, database ID, or username. This means no two users in one project may share the same identity. Must be fewer than 255 characters.

Next steps:

Now, that you have identified the user, you should track at least a couple of custom properties. Here you can learn how to track custom properties for each user.

Many products include some sort of tiered pricing plans. Using Gist .identify to attach this information to your users' Gist profiles can help you target those users and send relevant messages.

Gist's own pricing tiers include Free, Basic, and Pro plans. We use the identify  call ourselves so we can send pre-sale messages to Free users and customer success messages to Paid users etc.

When someone visits Gist, we pull their account plan from our database and include that into an identify call like this:

gist.identify("12345", {
    "email": "johndoe@example.com", 
    "plan": "Pro"
});

This allows you to filter your user list and send messages when users meet criteria specific to your business. The sky is the limit. For instance, you could add custom properties such as "number of projects completed", or "number of incomplete tasks" etc, and Gist tracks those for you and makes them available for you to filter your users and create more specific segments of users.

So, how to send custom properties to Gist?

You can send custom attributes by adding them to your Gist .identify code snippet as additional key/value pairs. Make sure to double check that your custom attribute keys always have a JSON-valid value - double quotes around strings and sending null as a value when there isn't a value for that user.

Also, here are some important directions:

• Field names must not contain Periods ('.') or Dollar ('$')
• Field values must be JSON Strings, Numbers or Booleans. Objects and Arrays will be rejected.
• Keys cannot contain special characters such as ~`!@#%^&*'{}|\'" or even the NULL character.
• Keys are case-sensitive.
• Values cannot be nested hashes or arrays.
• Only custom data attributes of string type are allowed to have up to 255 characters.

Here are some custom attribute examples:

gist.identify("12345", { 
    "email": "johndoe@tacos.com", 
    "name": "John Doe",
    "subdomain": "app", // Put quotes around text strings
    "active_accounts": 1872, // Send numbers without quotes
    "last_paid_at" : 1283495946, // Send dates in unix timestamp format and end key names with "_at"
    "teammates": null, // Send null when no value exists for a user
    "tags": "Free, popular", // Multiple tags can be added separated by comma
    "overwrite_tags": false // Defaults to true. If set to false, will merge the tags
});

Once you have your attributes added to Gist, you can head over to the ‘People’ page and apply filters based on custom properties, the same way you would with standard properties.