Merge pull request #7592 from segmentio/DOC-1101

stayseesong · web-flow · commit 3d2ba84c20f3 · 2025-05-01T13:20:00.000-07:00
Add analytics.instance.user().id(xxx) [DOC-1101]
diff --git a/src/connections/sources/catalog/libraries/website/javascript/index.md b/src/connections/sources/catalog/libraries/website/javascript/index.md
@@ -65,10 +65,13 @@ The Identify call has the following fields:
 
 | Field      |          | Type     | Description                                                                                                                                                                                                                                       |
 | ---------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `userId`   | optional | String   | The database ID for the user. If you don't know who the user is yet, you can omit the `userId` and just record `traits`. You can read more about identities in the [identify reference](/docs/connections/spec/identify).                         |
+| `userId`   | optional | String   | The database ID for the user. If you don't know who the user is yet, you can omit the `userId` and just record `traits`. You can read more about identities in the [identify reference](/docs/connections/spec/identify).                     |
 | `traits`   | optional | Object   | A dictionary of traits you know about the user, like `email` or `name`. You can read more about traits in the [identify reference](/docs/connections/spec/identify/).                                                                             |
 | `options`  | optional | Object   | A dictionary of options. For example, [enable or disable specific destinations](#managing-data-flow-with-the-integrations-object) for the call. _Note: If you do not pass a `traits` object, pass an empty object (as an '{}') before `options`._ |
-| `callback` | optional | Function | A function executed after a timeout of 300 ms, giving the browser time to make outbound requests first.                                                                                                                                           |
+| `callback` | optional | Function | A function executed after a timeout of 300 ms, giving the browser time to make outbound requests first.  |
+
+
+If you want to set the `userId` without sending an Identify call, you can use `analytics.user().id('123')`. In the NPM package, use `analytics.instance.user().id(xxx)`. This method updates the stored `userId` locally without triggering a network request. This is helpful if you want to associate a user ID silently, without sending additional data to Segment or connected destinations. Be cautious when changing the `userId` mid-session to avoid double-counting users or splitting their identity history.    
 
 By default, Analytics.js caches traits in the browser's `localStorage` and attaches them to each Identify call.
 
@@ -101,6 +104,7 @@ analytics.identify('12091906-01011992', function(){
 });
 ```
 
+
 ### Track
 
 The Track method lets you record actions your users perform. You can [see a track example in the Quickstart guide](/docs/connections/sources/catalog/libraries/website/javascript/quickstart/#step-4-track-actions) or find details on [the track method payload](/docs/connections/spec/track/).
diff --git a/src/connections/spec/best-practices-identify.md b/src/connections/spec/best-practices-identify.md
@@ -312,8 +312,10 @@ The Segment ID cookie is set with a one year expiration. However, there are some
 - If you invoke any call before you set an `anonymousId`, Segment automatically sets the `anonymousId` first. This means if you explicitly set an `anonymousId`, you might give the user two `anonymousId`s or overwrite an existing one.
 - If you fetch the `anonymousId` using `analytics.user().anonymousId()` before one is set, Segment generates and sets an `anonymousId` rather than returning `null`.
 - If you call `analytics.identify()` with a `userId` that is different from the currently cached `userId`, this can overwrite the existing one and cause attribution problems.
+- If you call `analytics.identify(xxx)` or `analytics.instance.user().id(xxx)`(In the NPM package, use `analytics.instance.user().id(xxx)`) with a `userId` that is different from the currently cached `userId`, this can overwrite the existing one and cause attribution problems.
 - 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.
 
diff --git a/src/guides/usage-and-billing/mtus-and-throughput.md b/src/guides/usage-and-billing/mtus-and-throughput.md
@@ -182,7 +182,7 @@ Check to see if you changed how you call `analytics.reset()`. This utility metho
 
 #### Overwriting an existing identity
 
-Segment's analytics libraries include methods that allow you to overwrite both the `userId` (using `identify(xxx)`) and `anonymousId` (using `analytics.user().anonymousId(xxx)`). Using these methods on a user whose tracking information already includes an ID can cause the user to be counted more than once.
+Segment’s analytics libraries include methods that allow you to overwrite both the `userId` (using `identify(xxx)` or `analytics.instance.user().id(xxx)`) and `anonymousId` (using `analytics.user().anonymousId(xxx)`). Using these methods on a user whose tracking information already includes an ID can cause the user to be counted more than once.
 
 If you find you need to use one of these overwrite methods, you should check to make sure that the field you are changing is `null` first. If the field is _not_ null, you probably don't want to overwrite it and lose the user's original tracked identity.
 
