From a58ffdbbd58e1720c616a49d2088db58256ae7a8 Mon Sep 17 00:00:00 2001 From: stayseesong Date: Wed, 30 Apr 2025 11:36:03 -0700 Subject: [PATCH 1/3] Add analytics.instance.user().id(xxx) [DOC-1101] --- .../sources/catalog/libraries/website/javascript/index.md | 8 ++++++-- src/connections/spec/best-practices-identify.md | 2 ++ src/guides/usage-and-billing/mtus-and-throughput.md | 2 +- 3 files changed, 9 insertions(+), 3 deletions(-) diff --git a/src/connections/sources/catalog/libraries/website/javascript/index.md b/src/connections/sources/catalog/libraries/website/javascript/index.md index 0c0579d06f..01ebd01d1b 100644 --- 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')`. On 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 index 622f714c41..56db08280a 100644 --- 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)`(On 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 index de50b9504d..4467ba335a 100644 --- 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. From 8a3ba7fc90be2f8a5b9e37094c27fb18869447e2 Mon Sep 17 00:00:00 2001 From: stayseesong <83784848+stayseesong@users.noreply.github.com> Date: Thu, 1 May 2025 10:11:52 -0700 Subject: [PATCH 2/3] Apply suggestions from code review Co-authored-by: rchinn1 <93161299+rchinn1@users.noreply.github.com> --- .../sources/catalog/libraries/website/javascript/index.md | 2 +- src/connections/spec/best-practices-identify.md | 2 +- src/guides/usage-and-billing/mtus-and-throughput.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/src/connections/sources/catalog/libraries/website/javascript/index.md b/src/connections/sources/catalog/libraries/website/javascript/index.md index 01ebd01d1b..7e882a0ef1 100644 --- a/src/connections/sources/catalog/libraries/website/javascript/index.md +++ b/src/connections/sources/catalog/libraries/website/javascript/index.md @@ -71,7 +71,7 @@ The Identify call has the following fields: | `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')`. On 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. +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. diff --git a/src/connections/spec/best-practices-identify.md b/src/connections/spec/best-practices-identify.md index 56db08280a..85b76c7844 100644 --- a/src/connections/spec/best-practices-identify.md +++ b/src/connections/spec/best-practices-identify.md @@ -312,7 +312,7 @@ 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)`(On 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 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`. diff --git a/src/guides/usage-and-billing/mtus-and-throughput.md b/src/guides/usage-and-billing/mtus-and-throughput.md index 4467ba335a..a9453b6f7e 100644 --- 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)` 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. +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. From 42112943e2e616f575d522de034d6811207a3d67 Mon Sep 17 00:00:00 2001 From: stayseesong <83784848+stayseesong@users.noreply.github.com> Date: Thu, 1 May 2025 12:18:04 -0700 Subject: [PATCH 3/3] Update src/connections/sources/catalog/libraries/website/javascript/index.md Co-authored-by: pwseg <86626706+pwseg@users.noreply.github.com> --- .../sources/catalog/libraries/website/javascript/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/connections/sources/catalog/libraries/website/javascript/index.md b/src/connections/sources/catalog/libraries/website/javascript/index.md index 7e882a0ef1..e3c83feb50 100644 --- a/src/connections/sources/catalog/libraries/website/javascript/index.md +++ b/src/connections/sources/catalog/libraries/website/javascript/index.md @@ -71,7 +71,7 @@ The Identify call has the following fields: | `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. +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.