Spec: Identify
The Innkeepr Identify call lets you tie a user to their actions and record traits about them. It includes a unique User ID and any optional traits you know about the user, like their email, name, and more.
We recommend that you make an Identify call:
After a user first registers
After a user logs in
When a user updates their info (for example, they change or add a new address)
Upon loading any pages that are accessible by a logged in user (optional)
The first three examples are pretty self-explanatory, but many might ask: why you would call identify on every page load if we’re storing the userId in the cookie/local storage?
Let’s imagine this scenario:
I log into your app. Identify is called. For whatever reason, I close the browser and don’t return until later. There’s no way of knowing where I will reenter your app from. I could start my session from anywhere. And because there are many tools out there that require an initial identify call for certain features (e.g. Intercom chat widget) it’s important to tell your end tools who the user is when they first start their session.
Calling identify is one of the first steps to getting started with Innkeepr. Refer to library-specific documentation for more details.
Here’s the payload of a typical identify call:
And here’s the corresponding JavaScript event that would generate the above payload:
Beyond common fields, an identify call has the following fields:
traits
optional
Object
userId
required; optional if anonymousID is set instead
String
Unique identifier for the user in your database. A userId or an anonymousId is required.
Example
Here’s a complete example of an identify call:
Identities
The identify call specifies a customer identity that you can reference across the customer’s whole lifetime. Every identify call must have a User ID or an Anonymous ID, depending on how much you know about the user in question.
Anonymous ID
There are certain cases where you don’t actually know who the user is according to your database, but you still want to be able to tie them to traits, events, or page views. For example, you may not know who a user is when tracking newsletter signups or anonymous page views.
In these cases, you should use an Anonymous ID.
The Anonymous ID can be any pseudo-unique identifier. For example, on your servers you can use a session id. If you don’t have any readily available identifier, you can always generate a new random one—we recommend UUIDs.
Note: Innkeepr’s libraries automatically use Anonymous IDs to keep track of users as they navigate around your website or app, so you don’t need to worry about them when using those libraries.
Here’s an example of a JavaScript event for an anonymous user:
User ID
User IDs are a more permanent and robust identifier, like a database ID. Since these IDs are consistent across a customer’s lifetime, identify calls should include a User ID as often as possible.
A User ID is usually the unique identifier that you recognize a user by in your own database. For example, if you’re using MongoDB it might look something like 507f191e810c19729de860ea.
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 in all of your analytics tools. And even better, you’ll be able to correlate analytics data with your own internal database.
Instead of using an email address or a username as a User ID, send them along as traits.
Traits
Traits are pieces of information you know about a user that are included in an identify call. These could be demographics like age or gender, account-specific like plan, or even things like whether a user has seen a particular A/B test variation. Up to you!
Innkeepr has reserved some traits that have semantic meanings for users, and we handle them in special ways. For example, we always expect email to be a string of the user’s email address. We’ll send this on to destinations like Klaviyo that require an email address to build targeting lists.
You should only use reserved traits for their intended meaning.
Reserved traits at Innkeepr:
TRAIT
TYPE
DESCRIPTION
address
Object
Street address of a user optionally containing: city, country, postalCode, state, or street
age
Number
Age of a user
avatar
String
URL to an avatar image for the user
birthday
Date
User’s birthday
company
Object
Company the user represents, optionally containing: name (String), id (String or Number), industry (String), employee_count (Number) or plan (String)
createdAt
Date
description
String
Description of the user
email
String
Email address of a user
email_sha256
String
The email of a user hashed with SHA256.
firstName
String
First name of a user
gender
String
Gender of a user
id
String
Unique ID in your database for a user
lastName
String
Last name of a user
name
String
Full name of a user. If you only pass a first and last name we automatically fill in the full name for you.
phone
String
Phone number of a user
title
String
Title of a user, usually related to their position at a specific company. Example: “VP of Engineering”
username
String
User’s username. This should be unique to each user, like the usernames of Twitter or GitHub.
website
String
Website of a user
Last updated
