Identify logged in users and send custom properties

By Jitta

Updated 3 months ago

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.
convertfox.identify('12345', {
	"email":  ""

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:

convertfox.identify("12345", {
	"email":  "", 
	"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:

convertfox.identify("12345", { 
	"email":  "", 
	"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.

Special Properties

Gist defines a list of common properties that are useful to track:

idThe unique database ID for this user. (Email required)String253552
emailThe email address of this user. (Email Required)
nameThe full name of the user (automatically derived from first_name and last_nameif this isn't set).StringJohn Doe
first_nameFirst name, concatenated with last_name.StringJohn
last_nameLast name, concatenated with first_name.StringDoe
usernameThe username for this person.Stringjohndoe
descriptionA short description for the user. Defaults to their Twitter bio if we can find it.StringCEO of Example App
avatarThe absolute URL of the avatar for this person. Defaults to the gravatar for email.String
phoneThe phone number for this person.String+12025550180
created_atSet the date that the user first signed up for your service – ISO 8601 timestamp. When the user is being identified for the first time, this defaults to the current timestampString2017-09-04T17:24:51Z
companyAn object containing company details (namesize etc).Object{ "name": "Example" }
company_nameThe name of the company the user works at.StringExample
company_sizeThe size of the company.Number25
company_industryThe industry of the company.StringGaming
company_positionThe position of this user within the company.StringCEO
customAn object of any other properties (custom properties)Object{ "plan": "premium" }

Did this answer your question?