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 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
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.
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?
convertfox.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
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": "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
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": "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.
Special Properties
Gist defines a list of common properties that are useful to track:
Name | Description | Type | Example |
---|---|---|---|
id | The unique database ID for this user. (Email required) | String | 253552 |
email | The email address of this user. (Email Required) | String | email@example.com |
name | The full name of the user (automatically derived from first_name and last_name if this isn't set). | String | John Doe |
first_name | First name, concatenated with last_name . | String | John |
last_name | Last name, concatenated with first_name . | String | Doe |
username | The username for this person. | String | johndoe |
description | A short description for the user. Defaults to their Twitter bio if we can find it. | String | CEO of Example App |
avatar | The absolute URL of the avatar for this person. Defaults to the gravatar for email . | String | https://profile-img.com/johndoe.png |
phone | The phone number for this person. | String | +12025550180 |
created_at | Set 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 timestamp | String | 2017-09-04T17:24:51Z |
company | An object containing company details (name , size etc). | Object | { "name": "Example" } |
company_name | The name of the company the user works at. | String | Example |
company_size | The size of the company. | Number | 25 |
company_industry | The industry of the company. | String | Gaming |
company_position | The position of this user within the company. | String | CEO |
custom | An object of any other properties (custom properties) | Object | { "plan": "premium" } |