Send logged-in user data from your database or third-party tool

In the dynamic digital landscape, it's important to ensure smooth and seamless user experiences, as well as efficient data management. With Gist, you can use the 'Identify' call to do just that. This guide aims to educate you about the identify call and how you can use it to send your logged-in user data to Gist servers. This helps in tracking user behaviour on your website and also lets you know who you're communicating with via live chat.

The Problem: Losing User Data and Conversation History

Imagine a user logs into your app and starts a conversation with your support team via Messenger but chooses not to enter their email address. If they close the browser and return later, there's no way to know who they are. They lose their conversation history, resulting in a poor user experience.

The Solution: Tracking Users with the Identify Call

You can track your logged-in users and keep their conversation history intact across multiple visits by using Gist's Identify call. This call lets Gist know the user's email address without requiring the user to submit it again in Messenger or any Gist forms.

What is the Identify Call?

The Identify call in Gist is a method that helps in identifying the user and associating them with a unique identifier. This identifier ensures that their activity and conversation history are maintained across multiple visits to your website. The method also allows you to send additional user information to Gist using JavaScript, saving them as Contact Properties, which can be used to segment the contacts for targeted communication.

Note: setting this up correctly may require the involvement of your web developer to ensure data is being sent accurately.

The Structure of the Identify Call

The gist.identify method is used to identify a user and assign certain attributes to them. Here's an example of how it's used:

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
});

The first part, 12345, should be a case-sensitive string containing the User ID from your own user database or an empty string ("") if it's not known. The second part consists of key-value pairs within a JSON object, defining Contact Property names and their values.

Types of properties

Gist allows you to send various types of custom properties. Here are some examples:

1. String: This includes words, URLs, plan names, user types, etc.
2. Number: You can send any integer value.
3. Boolean: This includes true or false values.
4. Timestamp: This is a record of the date and time something occurred, e.g., "converted_at".

Important Notes

Property names

1. Both the User ID and email fields are mandatory. They uniquely identify your user.
2. Avoid using periods (.) or dollar signs ($) in property names to prevent issues with data parsing.
3. Special characters such as ~`!@#%^&*'{}|'", and even the NULL character, should not be used in property keys. They could lead to unexpected results.
4. Be mindful that property keys are case-sensitive. "Name" and "name" would be treated as two different properties.

Property values

1. Use only JSON Strings, Numbers, or Booleans (true or false) as property values. Objects, nested hashes, and array data formats are not accepted.
2. You can clear existing data values by sending empty strings.
3. Text string values should not exceed 255 characters.
4. When sending dates, use Unix timestamps. This provides a standard, cross-platform compatible format.
5. Make sure all property keys have a valid JSON value. Wrap strings in double quotes and use null when there is no value for a particular user property. This helps maintain data integrity and ensures your data is always in a format that can be read correctly.
6. Gist automatically tracks a number of default contact properties. Check these before creating custom properties.

When to Call Identify?

Gist recommends that you make the identify call:

1. When a user registers
2. When a user logs in
3. When users update their info (change their email address, billing method, subscription plan, etc.)
4. Upon loading any pages that are accessible by a logged-in user (optional)

An Example Identify Call

You can leverage the Identify call to send relevant messages to users based on their tiered pricing plans. Here's an example:

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

After your properties are added to Gist, you can head to the 'Contacts' page and apply filters based on contact properties to group your contacts. This allows for targeted and efficient communication with your user base, enhancing user experience and improving data management.

Need Help?

If you have any questions, please start a Live Chat. Just "Click" on the Chat Icon in the lower right corner to talk with our support team.