From 46fcd5dc89ef6110cac767e3db0a30208d3fe65e Mon Sep 17 00:00:00 2001 From: Sharon Adewusi Date: Mon, 1 Sep 2025 16:37:44 +0100 Subject: [PATCH] Identify best practices audit [DOC-1199] --- .../spec/best-practices-identify.md | 88 +++++++++---------- 1 file changed, 43 insertions(+), 45 deletions(-) diff --git a/src/connections/spec/best-practices-identify.md b/src/connections/spec/best-practices-identify.md index 85b76c7844..fc0a43f42d 100644 --- a/src/connections/spec/best-practices-identify.md +++ b/src/connections/spec/best-practices-identify.md @@ -3,14 +3,14 @@ title: Best Practices for Identifying Users redirect_from: '/guides/how-to-guides/best-practices-identify/' --- -The most important calls you make with Segment are the [identify](/docs/getting-started/02-simple-install/#step-2-identify-users) and [track](/docs/getting-started/02-simple-install/#step-3-track-actions) calls. When you use these calls together, 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. Tracking users with the identify and track calls reduces the number of [Monthly Tracked Users](/docs/guides/usage-and-billing/mtus-and-throughput/) you are billed for. +The most important calls you make with Segment are the [Identify](/docs/getting-started/02-simple-install/#step-2-identify-users) and [Track](/docs/getting-started/02-simple-install/#step-3-track-actions) calls. When you use these calls together, 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. Tracking users with the Identify and Track calls reduces the number of [Monthly Tracked Users](/docs/guides/usage-and-billing/mtus-and-throughput/) that you are billed for. ## Identifying users -The Identify call specifies a customer identity that you can reference across the customer's 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. +The Identify call specifies a customer identity that you can reference across the customer's 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 an anonymous ID. -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. +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. 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. @@ -18,37 +18,37 @@ Whenever possible, follow the Identify call with a Track event that records what ## AnonymousId generation -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 visit to your site. 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. +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 visit to your site. 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. 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`. -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. +If you use Segment's server libraries, you must generate an `` manually. It can be any pseudo-unique identifier, for example, you might use a `sessionId` from a backend server. ## Best options for userIds -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. +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. You should include a `userId` in Identify calls as often as you can because these IDs are consistent across a customer's lifetime. If you don't have a userId, you need to include an anonymousId in your Identify call to record identifying information about your user. -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. +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){:target="_blank”}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. -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. +We do **not** recommend using simple email addresses or usernames as a user ID, as these can change over time. We recommend 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. You can also link your analytics data with your own internal database. -> success "" -> **Tip!** Even though Segment doesn'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). +> success "**Tip**" +> 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 a [trait](/docs/connections/spec/identify#traits). ## When to call Identify You should make an Identify call in the following situations: -- When the user provides any identifying information (such as a newsletter sign-up with email and name) -- When first you create a user (and so it is assigned a `userId`) -- When a user changes information in their profile -- When a user logs in -- *(Optional)* Upon loading any pages that are accessible by a logged in user +- When the user provides any identifying information (such as a newsletter sign-up with email and name.) +- When first you create a user (and so it is assigned a `userId`.) +- When a user changes information in their profile. +- When a user logs in. +- *(Optional)* Upon loading any pages that are accessible by a logged in user. -## Soft User Registration +## Soft user registration -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`. +An anonymous user visits the site for the very first time. The homepage 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`. ```js analytics.page({ @@ -60,7 +60,7 @@ analytics.page({ -You can see in this full page event, the `anonymousId` is populated, and the `userId` is null. +You can see in this full Page event, the `anonymousId` is populated, and the `userId` is null. ```js { @@ -101,7 +101,7 @@ You can see in this full page event, the `anonymousId` is populated, and the `us -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. +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 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. ```js analytics.identify({ @@ -113,7 +113,7 @@ analytics.identify({ -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 `localStorage`. +Notice the Identify call contains no `userId`. These traits are associated to the `anonymousId` that is available in the user's cookie and `localStorage`. ```js { @@ -160,9 +160,9 @@ You'll notice the Identify call contains no `userId`. These traits will be assoc -## Full User Registration +## Full user registration -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 and 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. +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 and capture additional traits. For this example, the `userId` that is assigned is _"123abc"_. This is when you want to fire an Identify call with this user's newly assigned `userId` and additional traits. ```js analytics.identify(`123abc`,{ @@ -179,7 +179,7 @@ analytics.identify(`123abc`,{ -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. +After you fire the Identify call with the `userId`, notice that the payload now has both a `userId` *and* an `anonymousId` attributed to the user. ```js { @@ -232,7 +232,7 @@ After you fire the Identify call with the `userId`, you'll notice that the paylo ## Merging Identified and Anonymous user profiles -The illustration below shows a timeline with a user's interactions on a website, including sample API calls above that show Segment calls, and the user's `anonymousId` and `userId`. +The illustration shows a timeline with a user's interactions on a website, including sample API calls that show Segment calls and the user's `anonymousId` and `userId`. ![This timeline illustration shows three points at which a user interacts with a website (visits homepage, signs up for newsletter, and clicks demo request button) and the corresponding API calls Segment makes for each step](images/identify-bp-1.png) @@ -242,7 +242,7 @@ When the user first visits a page, Analytics.js automatically assigns the user a 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. -The example below shows an Identify call including user traits. It uses a database ID (`97980cfea0067`) as the `userId`. +The following example shows an Identify call including user traits. It uses a database ID (_`97980cfea0067`_) as the `userId`. ```js analytics.identify("97980cfea0067", { @@ -252,7 +252,7 @@ analytics.identify("97980cfea0067", { }); ``` -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. +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). This example shows a Track call including properties that tell you about the user. ```js analytics.track("Signed Up", { @@ -288,7 +288,7 @@ In this scenario, the person uses both a web browser, and a mobile application t #### Scenario #3 - Multi-day, multi-device, multiple logins -Similar to the previous scenario, the user accessed both your website and mobile application, and also logged in on both. In this case, both sessions on the web and mobile app receive the user's `userId`, so Segment can tie the anonymous activity on both web and mobile to this user. +Similar to the previous scenario, the user accessed both your website and mobile application, and also logged in on both. In this case, both sessions on the web and mobile app receive the user's `userId` so Segment can tie the anonymous activity on both web and mobile to this user. ![This timeline illustration shows two parallel paths: one for a user logging in to a desktop site, and one for a user logging into a mobile app, and the API calls Segment makes to identify the users](images/identify-bp-4.png) @@ -297,15 +297,15 @@ Similar to the previous scenario, the user accessed both your website and mobile Your data warehouse has a schema for each of your Segment sources. User information is stored in two tables in your source schemas - the `identifies` and `users` table. -The `identifies` table contains all of your identify events, and the timestamps for these events. Every time you make an Identify call, Segment adds the `userId`, `anonymousId`, any updated or added user traits from the call, as well as the timestamp of when the call was made. Your `identifies` table is your first stop when you have questions about users and their traits. +The `identifies` table contains all identify events and their timestamps. Every time you make an Identify call, Segment adds the `userId`, `anonymousId`, any updated or added user traits from the call, as well as the timestamp of when the call was made. The `identifies` table is a record of users and their traits. -The `users` table contains only unique Identify method calls, and is a collation of the `identifies` table. The `users` table is the single source of truth for a user's most up-to-date traits. +The `users` table contains only unique Identify method calls and is a collation of the `identifies` table. The `users` table maintains the most current traits for each user. -These tables only contain information about a user *once they have been identified.* However, you can still find information about an _anonymous_ user on the `pages`, `screens`, and `tracks` tables, as well as the individual track event tables. +These tables only contain information about a user *once they have been identified.* However, you can find information about an _anonymous_ user in the `pages`, `screens`, and `tracks` tables, as well as the individual track event tables. ## ID expiration and overwriting -The Segment ID cookie is set with a one year expiration. However, there are some ways an ID can be reset or overwritten: +The Segment ID cookie has a one-year expiration. An ID can be, however, reset or overwritten in specific instances: - If you call `reset` during a user's browser session, it removes both their `userId` and `anonymousId`, which means the user generates a new `anonymousId` on the next visit. - If the user manually clears their cookies and local storage, they generate a new `anonymousId` on the next visit. @@ -316,10 +316,10 @@ The Segment ID cookie is set with a one year expiration. However, there are some - If you generate a new `anonymousId` on a server library, and pass it from the server to the browser, this could overwrite the user's existing `anonymousId`. -> info "" -> Remember, if a user has multiple devices, they can have different `anonymousId`s on each different device. +> info "Note:" +> A user with multiple devices can have different `anonymousId`s on each different device. -## Linking server and client generated Ids +## Linking server and client generated IDs 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: @@ -333,33 +333,31 @@ analytics.user().anonymousId() ![At Login](https://user-images.githubusercontent.com/78389005/214199506-e0251c90-c702-4760-a4a7-5bcd9e5a13f8.png) ---> -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 existing `anonymousId`s. +If you're identifying on the server, pass the userId from the server to the client using an Identify call with the `anonymousId`. This allows the `userId` to be aliased with the existing `anonymousId` and be stored in the cookie in localStorage. All previous anonymous activity and all subsequent activity is associated with the newly generated `userId` and any existing `anonymousId`s. -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](/docs/guides/how-to-guides/collect-on-client-or-server/#not-stored-in-your-database) in Segment's documentation. +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. If you want to send user data that is sensitive or which you don't want to expose to the client, you can make an Identify call from the server with all the traits you know about the user. For more about collecting data on the client or serversee [Segment's documentation](/docs/guides/how-to-guides/collect-on-client-or-server/#not-stored-in-your-database). ### Aliasing from a server library If you plan to track anonymous visitors from the browser and only make [Identify calls](/docs/connections/spec/identify) from your server libraries, Kissmetrics and Mixpanel might require that you make an [Alias call](/docs/connections/spec/alias) to link the records. The Alias call links client-side anonymous visitors with server-identified users. This isn't recommended, but if you do this, read the [Kissmetrics](/docs/connections/destinations/catalog/kissmetrics/#aliasing-new-users-server-side) and [Mixpanel](/docs/connections/destinations/catalog/mixpanel/#alias-using-cloud-mode) specific [alias](/docs/connections/spec/alias) docs. -### Common questions +### FAQs -There are a few things that might cause your numbers to be off. - -#### Missing sign-ups +#### Why are sign-ups missing in reports? The most common problem people run into when tracking new user signups client-side is that only a portion of their new users are showing up in reports. -This is usually caused by the page redirecting or reloading before the tracking calls get a chance to run. Segment recommends that you make those calls from a welcome page after the user registers, rather than trying to squeeze in the tracking calls on the sign-up page itself. +This is usually caused by the page redirecting or reloading before the tracking calls get a chance to run. We recommend that you make those calls from a welcome page after the user registers, rather than trying to squeeze in the tracking calls on the sign-up page itself. -#### Anonymous history is lost +#### Why is anonymous history lost? This is usually only an issue in [Mixpanel](/docs/connections/destinations/catalog/mixpanel#alias), since it's the only destination that requires a call to [alias](/docs/connections/spec/alias) in the browser to link anonymous browsing history to a new identified user. -Remember that for destinations that require aliasing, you must make the [Alias call](/docs/connections/spec/alias) before you make the [Identify call](/docs/connections/spec/identify) for that user. Even if you make an [Identify call](/docs/connections/spec/identify) from a server library, it can't happen before the client-side [alias](/docs/connections/spec/alias). +For destinations that require aliasing, you must make the [Alias call](/docs/connections/spec/alias) before you make the [Identify call](/docs/connections/spec/identify) for that user. Even if you make an [Identify call](/docs/connections/spec/identify) from a server library, it can't happen before the client-side [alias](/docs/connections/spec/alias). #### Can you update a userId? -Unfortunately, there is no way to change an existing `userId` within Segment. Historical data with an existing `userId` remains the same, and a new `userId` will not replace the existing `userId` in Segment event call logs. For downstream destinations, consult the corresponding docs about user profile behaviors when using a new `userId`. +There is no way to change an existing `userId` within Segment. Historical data with an existing `userId` remains the same, and a new `userId` will not replace the existing `userId` in Segment event call logs. For downstream destinations, consult the corresponding docs about user profile behaviors when using a new `userId`. -Changing a `userId` is incredibly hard to do, as that is a fundamental part of analytics. While some downstream analytics tools let you change a `userId` once set, others don't and the process will be different for each tool. +Some downstream analytics tools let you change a `userId` once set, while others don't. The process is different for each tool.