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
- Update intro paragraph
- Update AnonymousID generation blurb
- Add section on soft user registration
- Add section on full user registration
- Improve identifying users paragraph
- Add section on Linking server and client generated Ids
- Add situation to When to make identify call
- Keep formatting of Segment methods consistent throughout page
The most important calls you make with Segment are the Track and Identify calls. With the Track call, you can attribute actions on your site or app to individuals, and gain a better understanding of their activities, identity, and use patterns over time.
6
+
The most important calls you make with Segment are the [identify](https://segment.com/docs/getting-started/02-simple-install/#step-2-identify-users) and [track](https://segment.com/docs/getting-started/02-simple-install/#step-3-track-actions) calls. When you use these calls together, you can start to attribute actions on your site or app to individuals, and gain a better understanding of their activities, identity, and use patterns over time -- and help reduce the number of [Monthly Tracked Users](/docs/guides/usage-and-billing/mtus-and-throughput/) you are billed for.
7
7
8
-
When you use the Segment Identify call with the Track call, you can start to build a complete picture of a user's interactions with your systems, and help [reduce the number of Monthly Tracked Users](/docs/guides/usage-and-billing/mtus-and-throughput/) you are billed for.
9
8
9
+
## Identifying users
10
10
11
-
## AnonymousId generation
12
-
13
-
The Segment libraries generate an `anonymousId` for each user, even before you Identify them.
11
+
The `identify` call specifies a customer identity that you can reference across the customer's whole lifetime. There are instances where you want to record information about a user that isn't already known to you. An example of this might be, a user that visits your site and doesn't register, but they do give you their email address through a newsletter email sign-up form. In this instance, you would record that email address as a trait, and for the identifier (ID), you would use anonymous ID.
14
12
15
-
An `anonymousId` is a randomly generated 36 character string automatically assigned to a user on their first visit to your website or mobile application. You can use the `anonymousId` to link events performed by the user as they navigate around your website. When you track the `anonymousId`, you can attribute activities over multiple days to the same user by collecting all of the activities with that ID. If a user chooses to register for your site, or log in to your app, you can Identify them, and still include their `anonymousId` in the event payload along with the new `userId`.
13
+
When you make an [identify](/docs/connections/spec/identify) call using Segment's Analytics.js library, Segment saves the `userId` to the browser cookie, and writes all the user traits in `localStorage`. If you're using one of the Segment mobile libraries, the `userId` and traits are stored in the device's memory. This makes it possible to append the user's data to all subsequent [page calls](/docs/connections/sources/catalog/libraries/website/javascript#page) or [track calls](/docs/connections/sources/catalog/libraries/website/javascript#track) for the user, so you can properly attribute those actions.
16
14
17
-
> success ""
18
-
> **Tip!** Only the Segment mobile and website libraries automatically generate an `anonymousId`. If you use Segment's Server libraries, you must generate an `anonymousId` manually. It can be any pseudo-unique identifier, for example you might use a `sessionId` from a backend server.
15
+
If a user returns to your site after the [cookie expires](#id-expiration-and-overwriting), Analytics.js looks for an old ID in the user's `localStorage`, and if one is found, sets it as the user's ID again in a new cookie. If the user clears their cookies *and*`localStorage`, all of the IDs are removed and the user gets a completely new `anonymousId` when they next visit the page.
19
16
20
-
## Identifying users
17
+
Whenever possible, follow the `identify` call with a `track` event that records what caused the user to be identified.
21
18
22
-
Segment's Identify method lets you link a user to their actions and record traits about them. It includes a unique User ID, and records any traits you know about them, such as their email address, and name.
19
+
## AnonymousId generation
23
20
24
-
Segment recommends that you use a unique user identifier that won't change for your `userId`, for example a database ID from your organization's internal systems. (See below)
21
+
If you're using Segment's browser or mobile libraries, the Segment SDK generates and sets a UUID as `anonymousID` at the user's first presence. That `anonymousId` is saved in the user's cookie, as well as localStorage, and will stick with that user until the cache is cleared or a `reset` call is triggered.
25
22
26
-
When you make an [Identify call](/docs/connections/spec/identify) using Analytics.js, Segment saves the `userId` to the browser cookie, and writes all the user traits in local storage. If you're using one of the Segment mobile libraries, the `userId` and traits are stored in the device's memory. This makes it possible to append the user's data to all subsequent [Page calls](/docs/connections/sources/catalog/libraries/website/javascript#page) or [Track calls](/docs/connections/sources/catalog/libraries/website/javascript#track) for the user, so you can properly attribute those actions.
23
+
You can use the `anonymousId` to link events performed by the user as they navigate around your website. When you track the `anonymousId`, you can attribute activities over multiple days to the same user by collecting all of the activities with that ID. If a user chooses to register for your site, or log in to your app, you can `identify` them, and still include their `anonymousId` in the event payload along with the new `userId`.
27
24
28
-
If a user returns to your site after the [cookie expires](#id-expiration-and-overwriting), Analytics.js looks for an old ID in the user's `localStorage`, and if one is found, sets it as the user's ID again in a new cookie. If the user clears their cookies *and*`localStorage`, all of the IDs are removed. The user gets a completely new `anonymousId` when they next visit the page.
25
+
If you use Segment's server libraries, you must generate an `anonymousId` manually. It can be any pseudo-unique identifier, for example, you might use a `sessionId` from a backend server.
29
26
30
27
31
28
## Best options for userIds
32
29
33
-
A User ID should be a robust, static, unique identifier that you recognize a user by in your own systems. Because these IDs are consistent across a customer's lifetime, you should include a User ID in Identify calls as often as you can.
30
+
Segment recommends that you use a unique user identifier (UUID) that won't change for your `userId`. A `userId`should be a robust, static, unique identifier that you recognize a user by in your own database systems. Because these IDs are consistent across a customer's lifetime, you should include a `userId`in `identify` calls as often as you can. If you don't have a userId, you need to include an anonymousId in your `identify` call in order to record identifying information about your user.
34
31
35
-
Ideally, the User ID could be a database ID. For example, if you're using MongoDB it might be a row identifier and look something like `507f191e810c19729de860ea`. These can also be [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier)s that you generate somewhere in your application. You can also use identifiers that you get from other tools - such as Shopify or Braze - however this approach can lead to extra complexity in your systems.
32
+
Ideally, the `userId` could be a database ID. For example, if you're using MongoDB it might be a row identifier and look something like `507f191e810c19729de860ea`. These can also be [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier)s that you generate somewhere in your application. You can also use identifiers that you get from other tools - such as Shopify or Braze - however this approach can lead to extra complexity in your systems.
36
33
37
34
Segment does **not** recommend using simple email addresses or usernames as a User ID, as these can change over time. Segment recommends that you use static IDs instead, so the IDs *never* change. When you use a static ID, you can still recognize the user in your analytics tools, even if the user changes their email address. And even better, you can link your analytics data with your own internal database.
38
35
39
36
> success ""
40
-
> **Tip!** Even if you don't use an email address or a username as a User ID, you should still send them in the analytics payload as [traits](/docs/connections/spec/identify#traits).
37
+
> **Tip!** Even though we don't recommend using an email address or a username as a User ID, you can still send that identifying information in your `identify` call as [traits](/docs/connections/spec/identify#traits).
41
38
42
39
## When to call Identify
43
40
44
-
You should make an Identify call in the following situations:
41
+
You should make an `identify` call in the following situations:
42
+
43
+
- When the user provides any identifying information (such as a newsletter sign-up with email and name)
44
+
- When first you create a user (and so it is assigned a `userId`)
45
+
- When a user changes information in their profile
46
+
- When a user logs in
47
+
- Optionally, when you call `identify` upon loading any pages that are accessible by a logged in user
48
+
49
+
## Soft User Registration
50
+
51
+
An anonymous user visits the site for the very first time. The home page has the analytics.js tracking snippet loaded in its header. When the page loads, this sets off the default `page` call to Segment. The Segment SDK generates and sets `anonymousId`.
The user signs up for an email newsletter and fills out the form giving you their first and last name, as well as their email address. At this point, you will fire off an `identify` call. You won't yet assign them a user ID in this example, but you can still grab these traits about them.
You'll notice the identify call contains no `userId`. These traits will be associated to the `anonymousId` that is available in the user's cookie and `localStroage`.
45
64
46
-
- when first you create a user (and so it is assigned a `userId`)
47
-
- when a user changes information in their profile
48
-
- when a user logs in
49
-
- Optionally, when you call Identify upon loading any pages that are accessible by a logged in user
65
+
66
+
67
+
68
+
## Full User Registration
69
+
70
+
An anonymous visitor registers for an account and becomes a known user. The account creation process allows you to assign a `userId` from your production database, as well as capture additional traits. For this example, the `userId` that is assigned is "123abc". This is when you'll want to fire an `identify` call with this user's newly assigned `userId` and additional traits.
71
+
72
+
73
+
74
+
After you fire the `identify` call with the `userId`, you'll notice that the payload now has both a `userId`*and* an `anonymousId` attributed to the user.
75
+
76
+
50
77
51
78
## Merging Identified and Anonymous user profiles
52
79
@@ -56,11 +83,11 @@ The illustration below shows a timeline with a user's interactions on a website,
When the user first visits a page, Analytics.js automatically assigns the user an `anonymousId` and saves it to the user's local storage. As the user interacts with the site, for example clicking around to different pages, Analytics.js includes this `anonymousId` and some [contextual information](/docs/connections/spec/common#context) with each Page and Track call. The contextual information might be the user's [IP address, browser, and more](/docs/connections/spec/common#context-fields-automatically-collected).
86
+
When the user first visits a page, Analytics.js automatically assigns the user an `anonymousId` and saves it to the user's `localStorage`. As the user interacts with the site, for example clicking around to different pages, Analytics.js includes this `anonymousId` and some [contextual information](/docs/connections/spec/common#context) with each `page` and `track` call. The contextual information might be the user's [IP address, browser, and more](/docs/connections/spec/common#context-fields-automatically-collected).
60
87
61
-
When a user signs up to create an account on the website, the `.identify(UID)` and `.track(“Signed Up”)` events fire, in that order. You pull the `userId` unique to the user from your systems, and send it to the Segment library so you can label that user's later events with their ID. The later Track call (“Signed Up”) contains both the `userId`*and* the automatically-collected `anonymousId` for the user, and any other information you capture about them - such as their first name, last name, and email address.
88
+
When a user signs up to create an account on the website, the `.identify("userId")` and `.track(“Signed Up”)` events fire, in that order. You pull the `userId` unique to the user from your systems, and send it to the Segment library so you can label that user's later events with their ID. The later Track call (“Signed Up”) contains both the `userId`*and* the automatically-collected `anonymousId` for the user, and any other information you capture about them - such as their first name, last name, and email address.
62
89
63
-
The example below shows an Identify call including user traits. It uses a database ID (`97980cfea0067`) as the `userId`.
90
+
The example below shows an `identify` call including user traits. It uses a database ID (`97980cfea0067`) as the `userId`.
For a Track call, information about this event is stored either in the `context` field or in the event [properties](/docs/connections/spec/track#properties). The example below shows a Track call including properties that tell you about the user.
100
+
For a `track` call, information about this event is stored either in the `context` field or in the event [properties](/docs/connections/spec/track#properties). The example below shows a `track` call including properties that tell you about the user.
Additionally, Analytics.js adds a `message_id` and [four timestamps](/docs/connections/spec/common#timestamp-overview) to the call.
85
112
86
-
Now, as the user interacts with your site and different buttons or links that you track using Segment, their `userId` and `anonymousId` are sent with each tracking API call.
113
+
Now, as the user interacts with your site and different buttons or links that you track using Segment, their `userId`*and*`anonymousId` are sent with each subsequent tracking API call.
87
114
88
-
### UserID merge examples
115
+
### UserId merge examples
89
116
90
-
Let's go through some more scenarios to explain how an `anonymousId` is assigned and how it might be merged with a UID.
117
+
Let's go through some more scenarios to explain how an `anonymousId` is assigned and how it might be merged with a `userId`.
91
118
92
119
#### Scenario #1 - Multi-day, single device
93
120
94
-
If a user clicks on an ad and is directed to a webpage, they are assigned an `anonymousId`. While this user is anonymous they navigate to different pages and click around on the website. Say they come back two days later from the same device, sign up, and are assigned a `userId`.
121
+
If a user clicks on an ad and is directed to a webpage, they are assigned an `anonymousId`. While this user is anonymous, they navigate to different pages and click around on the website. Say they come back two days later from the same device, sign up, and are assigned a `userId` from your database.
95
122
96
123
97
124
98
125
For simplicity, we're assuming that the user has _not_ cleared their cookies or `localStorage`, where the original `anonymousId` is stored. If they had, they'd be assigned a new `anonymousId` when they visited the website, and the `userId` they got when they register on the website would _not_ be attached to the activities tracked with the old `anonymousId`.
99
126
100
127
#### Scenario #2 - Multi-day, multi-device, single login
101
128
102
-
In this scenario, the person uses both a web browser, and a mobile application to interact with your site. In each case, they are assigned a different `anonymousId`. In this scenario, the user signs up on the web browser, so Segment assigns their _web_ session a `userId`. However, because they do not log in on the mobile application, Segment cannot tie the mobile activity to this specific user. Their mobile application activity remains anonymous unless they log in on the mobile application.
129
+
In this scenario, the person uses both a web browser, and a mobile application to interact with your site. In each case, they are assigned a different `anonymousId`. In this scenario, the user signs up on the web browser, so their _web_ session is assigned a `userId`. However, because they do not log in on the mobile application, Segment cannot tie the mobile activity to this specific user. Their mobile application activity remains anonymous unless they log in on the mobile application.
103
130
104
131
105
132
@@ -135,11 +162,23 @@ The Segment ID cookie is set with a one year expiration. However, there are some
135
162
> info ""
136
163
> Remember, if a user has multiple devices, they can have different `anonymousId`s on each different device.
137
164
138
-
## Linking server- and client- generated Ids
165
+
## Linking server and client generated Ids
166
+
167
+
If you're tracking on the client and on the server, the `anonymousId` can be retrieved from `localStorage` on the client and passed to the server. You can access a user's anonymousId using the following call:
168
+
169
+
```js
170
+
analytics.user().anonymousId()
171
+
```
172
+
173
+
There are some advantages to sending details about your users directly from your server once the user registers. Server library [Identify calls](/docs/connections/spec/identify) are invisible to the end user, making them more secure, and much more reliable.
179
+
If you're identifying on the server, then you will want to pass the user ID from the server to the client using an `identify` call with the `anonymousId`. That will allow the `userId` to be aliased with the existing `anonymousId` and stored in the cookie in localStorage. With that, all previous anonymous activity and all subsequent activity is associated to the newly generated `userId`, as well as exisiting `anonymousId`s.
141
180
142
-
If you want to send user data that is sensitive or which you don't want to expose to the client, then you can make an Identify call from the server with all the traits you know about the user.
181
+
There are some advantages to sending details about your users directly from your server once the user registers. Server library [Identify calls](/docs/connections/spec/identify) are invisible to the end user, making them more secure, and much more reliable. Or, if you want to send user data that is sensitive or which you don't want to expose to the client, then you can make an `identify` call from the server with all the traits you know about the user. More about [collecting data on the client or server](https://segment.com/docs/guides/how-to-guides/collect-on-client-or-server/#not-stored-in-your-database) in our documentation.
0 commit comments