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
`identify` 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 them like their email, name, etc.
7
18
8
19
Our recommendation for when and how often you should call identify is as follows:
@@ -39,79 +50,59 @@ And here's the corresponding Javascript event that would generate the above payl
39
50
40
51
```js
41
52
analytics.identify("97980cfea0067", {
42
-
name:"Peter Gibbons",
43
-
email:"peter@initech.com",
44
-
plan:"premium",
53
+
name:"Peter Gibbons",
54
+
email:"peter@initech.com",
55
+
plan:"premium",
45
56
logins:5
46
57
});
47
58
```
48
59
49
60
Beyond the common fields, an `identify` call has the following fields:
50
61
51
-
<table>
52
-
<tr>
53
-
<th>**Field**</th>
54
-
<th>**Type**</th>
55
-
<th>**Description**</th>
56
-
</tr>
57
-
{% include content/spec-field-identify-traits.md %}
58
-
{% include content/spec-field-user-id.md %}
59
-
</table>
62
+
| Field | Type | Description |
63
+
| --- | --- | --- |
64
+
|`traits` <br> optional | Object | Free-form dictionary of traits of the user, like `email` or `name`. <br> See the [Traits field docs](/docs/spec/identify#traits)|
65
+
|`userId` <br> optional/required | String | Unique identifier for the user in your database. A userId or an anonymousId is required.<br> See the [Identities docs](/docs/spec/identify#identities) for more detail. |
60
66
67
+
{% include components/alert.html type="success" content="Your message has been sent successfully. This is a paragraph showing alert box. Indicates a successful or positive action." %}
61
68
62
69
## Example
63
70
64
71
Here's a complete example of an `identify` call:
65
72
66
73
```json
67
74
{
68
-
"anonymousId": "507f191e810c19729de860ea",
69
-
"channel": "browser",
70
-
"context": {
71
-
"ip": "8.8.8.8",
72
-
"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"
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](/docs/spec/identify#user-id) or an [Anonymous ID](/docs/spec/identify#anonymous-id)**, depending on how much you know about the user in question.
105
89
90
+
{% include components/alert.html type="info" content="Please read the comments carefully. This is a paragraph showing information box. Indicates a neutral informative change or action." %}
91
+
106
92
### Anonymous ID
107
93
108
94
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
95
110
96
In these cases, you should use an Anonymous ID.
111
97
98
+
{% include components/alert.html type="warning" content="There was a problem with your network connection. Indicates a warning that might need attention. This is a paragraph showing warning box." %}
99
+
112
100
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](http://en.wikipedia.org/wiki/Universally_unique_identifier).
113
101
114
-
**Note:** Our [browser and mobile libraries](/docs/sources/)**automatically** use Anonymous IDs under the covers 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.
102
+
{% capture AnonymousID_note %}
103
+
Our [browser and mobile libraries](/docs/sources/)**automatically** use Anonymous IDs under the covers 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.
104
+
{% endcapture %}
105
+
{% include components/note.html content=AnonymousID_note %}
115
106
116
107
### User ID
117
108
@@ -123,6 +114,8 @@ We recommend using database IDs instead of simple email addresses or usernames,
123
114
124
115
**Instead of using an email address or a username as a User ID, send them along as [traits](/docs/spec/identify#traits).**
125
116
117
+
118
+
126
119
## Traits
127
120
128
121
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!
@@ -133,105 +126,29 @@ You should **only use reserved traits for their intended meaning**.
133
126
134
127
Reserved traits we've standardized:
135
128
136
-
<table>
137
-
<tr>
138
-
<th>**Trait**</th>
139
-
<th>**Type**</th>
140
-
<th>**Description**</th>
141
-
</tr>
142
-
<tr>
143
-
<td>`address`</td>
144
-
<td>Object</td>
145
-
<td>Street address of a user optionally containing: `city`, `country`, `postalCode`, `state` or `street`</td>
146
-
</tr>
147
-
<tr>
148
-
<td>`age`</td>
149
-
<td>Number</td>
150
-
<td>Age of a user</td>
151
-
</tr>
152
-
<tr>
153
-
<td>`avatar`</td>
154
-
<td>String</td>
155
-
<td>URL to an avatar image for the user</td>
156
-
</tr>
157
-
<tr>
158
-
<td>`birthday`</td>
159
-
<td>Date</td>
160
-
<td>User's birthday</td>
161
-
</tr>
162
-
<tr>
163
-
<td>`company`</td>
164
-
<td>Object</td>
165
-
<td>Company the user represents, optionally containing: `name` (a String), `id` (a String or Number), `industry` (a String), `employee_count` (a Number) or `plan` (a String)</td>
166
-
</tr>
167
-
<tr>
168
-
<td>`createdAt`</td>
169
-
<td>Date</td>
170
-
<td>Date the user's account was first created
171
-
<p>We recommend [ISO-8601](http://en.wikipedia.org/wiki/ISO_8601) date strings.</p></td>
172
-
</tr>
173
-
<tr>
174
-
<td>`description`</td>
175
-
<td>String</td>
176
-
<td>Description of the user</td>
177
-
</tr>
178
-
<tr>
179
-
<td>`email`</td>
180
-
<td>String</td>
181
-
<td>Email address of a user</td>
182
-
</tr>
183
-
<tr>
184
-
<td>`firstName`</td>
185
-
<td>String</td>
186
-
<td>First name of a user</td>
187
-
</tr>
188
-
<tr>
189
-
<td>`gender`</td>
190
-
<td>String</td>
191
-
<td>Gender of a user</td>
192
-
</tr>
193
-
<tr>
194
-
<td>`id`</td>
195
-
<td>String</td>
196
-
<td>Unique ID in your database for a user</td>
197
-
</tr>
198
-
<tr>
199
-
<td>`lastName`</td>
200
-
<td>String</td>
201
-
<td>Last name of a user</td>
202
-
</tr>
203
-
<tr>
204
-
<td>`name`</td>
205
-
<td>String</td>
206
-
<td>Full name of a user
207
-
<p> If you only pass a first and last name we'll automatically fill in the full name for you.</p>
208
-
</td>
209
-
</tr>
210
-
<tr>
211
-
<td>`phone`</td>
212
-
<td>String</td>
213
-
<td>Phone number of a user</td>
214
-
</tr>
215
-
<tr>
216
-
<td>`title`</td>
217
-
<td>String</td>
218
-
<td>Title of a user, usually related to their position at a specific company
219
-
<p>Example: "VP of Engineering"</p>
220
-
</td>
221
-
</tr>
222
-
<tr>
223
-
<td>`username`</td>
224
-
<td>String</td>
225
-
<td>User's username
226
-
<p> This should be unique to each user, like the usernames of Twitter or GitHub.</p></td>
227
-
</tr>
228
-
<tr>
229
-
<td>`website`</td>
230
-
<td>String</td>
231
-
<td>Website of a user</td>
232
-
</tr>
233
-
</table>
234
-
235
-
**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. Luckily, you don't have to worry about those inconsistencies. Just pass us `createdAt`. **We’ll handle all of the destination-specific conversions for you automatically.** Same goes for the rest of the reserved traits.
236
-
237
-
**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.
129
+
| Trait | Type | Description |
130
+
| --- | --- | --- |
131
+
|`address`| Object | Street address of a user optionally containing: `city`, `country`, `postalCode`, `state` or `street`|
132
+
|`age`| Number | Age of a user |
133
+
|`avatar`| String | URL to an avatar image for the user |
134
+
|`birthday`| Date | User's birthday |
135
+
|`company`| Object | Company the user represents, optionally containing: `name` (a String), `id` (a String or Number), `industry` (a String), `employee_count` (a Number) or `plan` (a String) |
136
+
|`createdAt`| Date | Date the user's account was first created <br> We recommend [ISO-8601](http://en.wikipedia.org/wiki/ISO_8601) date strings. |
137
+
|`description`| String | Description of the user |
138
+
|`email`| String | Email address of a user |
139
+
|`firstName`| String | First name of a user |
140
+
|`gender`| String | Gender of a user |
141
+
|`id`| String | Unique ID in your database for a user |
142
+
|`lastName`| String | Last name of a user |
143
+
|`name`| String | Full name of a user <br> If you only pass a first and last name we'll automatically fill in the full name for you. |
144
+
|`phone`| String | Phone number of a user |
145
+
|`title`| String | Title of a user, usually related to their position at a specific company <br> Example: "VP of Engineering" |
146
+
|`username`| String | User's username <br> This should be unique to each user, like the usernames of Twitter or GitHub. |
147
+
|`website`| String | Website of a user |
148
+
149
+
{% capture Traits_note %}
150
+
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. Luckily, you don't have to worry about those inconsistencies. Just pass us `createdAt`. **We’ll handle all of the destination-specific conversions for you automatically.** Same goes for the rest of the reserved traits.
151
+
**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.
152
+
{% endcapture %}
153
+
154
+
{% include components/note.html content=Traits_note %}
{% include components/media-icon.html href="#" icon="media/icon-academy.svg" title="Title" content="Lorem ipsum dolor sit amet consectetur, adipisicing elit. Iusto ratione ipsum fugiat nostrum velit iure, molestiae accusamus tempora quos laborum, ex modi illum delectus. Suscipit nesciunt labore nulla numquam excepturi?" %}
{% include components/alert.html type="success" content="This is my sample note." %}
133
127
{% include components/alert.html type="warning" content="This is my sample note." %}
134
128
{% include components/alert.html type="error" content="This is my sample note." %}
135
-
136
-
---
137
-
138
-
## Callout
139
-
140
-
{% include components/callout.html title="Get started with Segment" content="Segment is the easiest way to integrate your websites & mobile apps data to 250+ analytics and growth tools." %}
0 commit comments