100% compatible with Segment

These specs are 100% compatible with http://segment.com specs.

Topics

1 100% compatible with Segment
2 Example
3 Identities
- 3.1 Anonymous ID
- 3.2 User ID
- 3.3 Traits

The journy.io 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.

journy.io recommends 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)

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?

Calling identify in one of our libraries is one of the first steps to getting started with journy.io .

Here’s the payload of a typical identify call with most common fields

{  "type": "identify", 
   "userId": "abc123" 
   "traits": { 
      "firstname": "Elon", 
      "lastname": "Musk",
      "email": "elon.musk@tesla.com", 
      "Country of birth": "South Africa" }
}

And here’s the corresponding JavaScript event that would generate the above payload:

analytics.identify("abc123", { 
   firstname: "Elon", 
   lastname: "Musk",
   email: "elon.musk@tesla.com", 
   Country_of_birth: "South Africa"
});

Based on the library you use, the syntax in the examples might be different. You can find library-specific documentation on the page.Sources Overview

Beyond the common fields, an identify call has the following fields:

FIELD	REQUIRED?	TYPE	DESCRIPTION
`traits`	optional	Object	Free-form dictionary of traits of the user, like `email` or `name`.
`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:

{  "anonymousId": "507f191e810c19729de860ea", 
   "type": "identify", 
   "userId": "97980cfea0067", 
   "channel": "browser", 
   "context": { 
      "ip": "8.8.8.8", 
      "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_9_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/40.0.2214.115 Safari/537.36" }, 
   "integrations": { 
      "All": false, 
      "Mixpanel": true, 
      "Salesforce": true }, 
   "messageId": "022bb90c-bbac-11e4-8dfc-aa07a5b093db", 
   "receivedAt": "2015-02-23T22:28:55.387Z", 
   "sentAt": "2015-02-23T22:28:55.111Z", 
   "timestamp": "2015-02-23T22:28:55.111Z", 
   "traits": { 
      "firstname": "Elon", 
      "lastname": "Musk",
      "email": "elon.musk@tesla.com", 
      "Place of birth": "South Africa",
      "address": { "street": "6th St", "city": "Durban", "country": "South Africa" } }, 
   "version": "1.1" 
}

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

In certain scenarios, there are instances where you lack information about a user's identity within your database, yet you still wish to associate them with traits, events, or page views. For instance, when tracking actions like newsletter signups or interactions with anonymous page views, the concept of an Anonymous ID comes into play.

The Anonymous ID can take the form of any pseudo-unique identifier. For instance, on your servers, you can employ a session ID. Alternatively, in cases where you lack an readily available identifier, you can generate a new random one, and we recommend using UUIDs for this purpose.

Please note that journy.io 's browser libraries automatically utilize Anonymous IDs to trace users as they navigate your website or app. Hence, when using these libraries, you need not concern yourself with managing them separately.

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.

journy.io suggests employing database IDs over mere email addresses or usernames due to the inherent stability of database IDs. Database IDs remain constant, ensuring that even if a user modifies their email address, you can consistently identify them across all your analytics tools. Moreover, this approach facilitates the correlation of analytics data with your internal database seamlessly.

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!

journy.io has reserved some traits that have semantic meanings for users, and we handle them in special ways. For example, journy.io always expects email to be a string of the user’s email address. We’ll send this on to destinations like Mailchimp that require an email address for their tracking.

You should only use reserved traits for their intended meaning.

Reserved traits journy.io has standardized:

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	Date the user’s account was first created. journy.io recommends using ISO-8601 date strings.
`description`	String	Description of the user
`email`	String	Email address of a user
`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 journy.io automatically fills 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

Note: You might be used to some destinations recognizing special traits by slightly different names. For example, Mixpanel recognizes a $created trait when the user’s account was first created, while Intercom recognizes the same trait as created_at instead. journy.io attempts to handle all the destination-specific conversions for you automatically.

You can pass these reserved traits using camelCase or snake_case, so in JavaScript you can match the rest of your camel-case code by sending firstName, while in Ruby you can match your snake-case code by sending first_name. That way the API never seems alien to your code base. Keep in mind that not all destinations support these reserved traits, so sending these traits in camelCase and snake_case can result in two sets of traits in other destinations.

journy.io - Help Center

The Identify Spec