You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: src/connections/spec/identify.md
+23-27Lines changed: 23 additions & 27 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,21 +2,19 @@
2
2
title: 'Spec: Identify'
3
3
---
4
4
5
-
The Segment 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.
5
+
The Segment 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 emailand name.
6
6
7
-
{% include components/reference-button.html href="https://university.segment.com/introduction-to-segment/299968?reg=1&referrer=docs" icon="media/academy.svg" title="Segment University: The Identify Method" description="Check out our high-level overview of the Identify method in Segment University. (Must be logged in to access.)" %}
7
+
{% include components/reference-button.html href="https://university.segment.com/introduction-to-segment/299968?reg=1&referrer=docs" icon="media/academy.svg" title="Segment University: The Identify Method" description="Check out the high-level overview of the Identify method in Segment University. (You must be logged in to access.)" %}
8
8
9
9
Segment recommends that you make an Identify call:
10
10
11
11
- After a user first registers
12
12
- After a user logs in
13
13
- When a user updates their info (for example, they change or add a new address)
14
14
15
-
The first three examples are pretty self-explanatory, but many might ask: why you would call Identify on every page load if you're storing the `userId` in the cookie/local storage?
15
+
Calling Identify in one of Segment's [libraries](/docs/connections/sources/) is one of the first steps to getting started with Segment. You can refer to library-specific documentation for more details.
16
16
17
-
Calling Identify in one of Segment's [libraries](/docs/connections/sources/) is one of the first steps to getting started with Segment. Refer to library-specific documentation for more details.
18
-
19
-
Here's the payload of a typical Identify call with most [common fields](/docs/connections/spec/common/) removed:
17
+
For example, here's the payload of a typical Identify call with most [common fields](/docs/connections/spec/common/) removed:
20
18
21
19
```json
22
20
{
@@ -31,7 +29,7 @@ Here's the payload of a typical Identify call with most [common fields](/docs/co
31
29
}
32
30
```
33
31
34
-
And here's the corresponding JavaScript event that would generate the above payload:
32
+
Here's the corresponding JavaScript event that would generate the above payload:
35
33
36
34
```js
37
35
analytics.identify("97980cfea0067", {
@@ -105,14 +103,12 @@ The Identify call specifies a customer identity that you can reference across th
105
103
106
104
### Anonymous ID
107
105
108
-
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.
109
-
110
-
In these cases, you should use an Anonymous ID.
106
+
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.
111
107
112
-
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 — Segment recommends [UUIDv4 format](/docs/guides/working-with-ids/#segments-guidance-on-identifier-formats).
108
+
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 — Segment recommends [UUIDv4 format](/docs/guides/working-with-ids/#segments-guidance-on-identifier-formats).
113
109
114
110
> info ""
115
-
> Segment's [browser and mobile libraries](/docs/connections/sources/) 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.
111
+
> Segment's [website and mobile libraries](/docs/connections/sources/) 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.
116
112
117
113
Here's an example of a JavaScript event for an anonymous user:
118
114
@@ -128,7 +124,7 @@ User IDs are a more permanent and robust identifier, like a database ID. Since t
128
124
129
125
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, User IDs might look something like this: `507f191e810c19729de860ea`.
130
126
131
-
Segment recommends using database IDs, [in `uuidv4` format](/docs/guides/working-with-ids/#segments-guidance-on-identifier-formats), instead of 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 you'll be able to correlate analytics data with your own internal database.
127
+
Segment recommends using database IDs, [in `uuidv4` format](/docs/guides/working-with-ids/#segments-guidance-on-identifier-formats), instead of email addresses or usernames because database IDs _never_ change. This 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 you'll be able to correlate analytics data with your own internal database.
132
128
133
129
> success ""
134
130
> Instead of using an email address or a username as a User ID, send them along as [custom traits](/docs/unify/traits/custom-traits/).
@@ -147,24 +143,24 @@ Reserved custom traits Segment has standardized:
|`address`| Object | Street address of a user optionally containing: `city`, `country`, `postalCode`, `state`, or `street`|
150
-
|`age`| Number | Age of a user |
151
-
|`avatar`| String | URL to an avatar image for the user |
152
-
|`birthday`| Date |User's birthday |
153
-
|`company`| Object |Company the user represents, optionally containing: `name` (String), `id` (String or Number), `industry` (String), `employee_count` (Number) or `plan` (String) |
146
+
|`age`| Number | Age of a user.|
147
+
|`avatar`| String | URL to an avatar image for the user.|
148
+
|`birthday`| Date |The user's birthday.|
149
+
|`company`| Object |The company the user represents, optionally containing: `name` (String), `id` (String or Number), `industry` (String), `employee_count` (Number) or `plan` (String) |
154
150
|`createdAt`| Date | Date the user's account was first created. Segment recommends using [ISO-8601](http://en.wikipedia.org/wiki/ISO_8601){:target="_blank"} date strings. |
155
-
|`description`| String | Description of the user |
156
-
|`email`| String | Email address of a user |
157
-
|`firstName`| String | First name of a user |
158
-
|`gender`| String | Gender of a user |
159
-
|`id`| String | Unique ID in your database for a user |
160
-
|`lastName`| String | Last name of a user |
161
-
|`name`| String | Full name of a user. If you only pass a first and last name Segment automatically fills in the full name for you. |
162
-
|`phone`| String | Phone number of a user |
151
+
|`description`| String | Description of the user.|
152
+
|`email`| String | Email address of a user.|
153
+
|`firstName`| String | First name of a user.|
154
+
|`gender`| String | Gender of a user.|
155
+
|`id`| String | Unique ID in your database for a user.|
156
+
|`lastName`| String | Last name of a user.|
157
+
|`name`| String | Full name of a user. If you only pass a first and last name, Segment automatically fills in the full name for you. |
158
+
|`phone`| String | Phone number of a user.|
163
159
|`title`| String | Title of a user, usually related to their position at a specific company. Example: "VP of Engineering" |
164
160
|`username`| String | User's username. This should be unique to each user, like the usernames of Twitter or GitHub. |
165
-
|`website`| String | Website of a user |
161
+
|`website`| String | Website of a user.|
166
162
167
163
> info ""
168
164
> 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. Segment attempts to handle all the destination-specific conversions for you automatically. If you need help understanding if a specific field will be converted to a destination, take a look at Segment's [open source integration code](https://github.com/segment-integrations?q=&type=all&language=&sort=){:target="_blank"}, view the destination's documentation, or [contact Segment support](https://app.segment.com/workspaces?contact=1){:target="_blank"}.
169
165
170
-
**You can pass these reserved traits using camelCase or snake_case**, so in JavaScript you can match the rest of your camelCase 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.
166
+
You can pass these reserved traits using camelCase or snake_case. For example, in JavaScript you can match the rest of your camelCase code by sending `firstName`, while in Ruby you can match your snake-case code by sending `first_name`. This keeps the API consistent 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.
0 commit comments