|
| 1 | +--- |
| 2 | +title: Managing identity in Analytics.js |
| 3 | +--- |
| 4 | + |
| 5 | +This page explains how Analytics.js identifies users, and passes userID and anonymousID data, and how to override and change this information. |
| 6 | + |
| 7 | +## Segment ID Persistence |
| 8 | + |
| 9 | +To ensure high fidelity, first-party customer data, Segment writes the user's IDs to the user's local storage, and uses that as the Segment ID on the cookie whenever possible. Local Storage is meant for storing this type of first-party customer information. |
| 10 | + |
| 11 | +If a user returns to your site after the cookie expires, 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 the new cookie. If a 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. |
| 12 | + |
| 13 | +<!-- TODO: add info on how user and group info is stored - on cookie, in mem, in localStorage--> |
| 14 | + |
| 15 | +<!-- TODO: also info on |
| 16 | +- what is the userId |
| 17 | +- what's it mean |
| 18 | +- where's it set |
| 19 | +- methods for working w/ |
| 20 | +- retrieving the userID --> |
| 21 | + |
| 22 | + |
| 23 | +## Anonymous IDs |
| 24 | + |
| 25 | +Analytics.js generates a [universally unique ID (UUID)](https://en.wikipedia.org/wiki/Universally_unique_identifier) for the viewer during the library's initialization phase, and sets this as `anonymousId` for each new visitor to your site. This happens before Analytics.js loads any device-mode destinations, and so before these destination-libraries can generate their own user IDs. |
| 26 | + |
| 27 | +Example: |
| 28 | +```js |
| 29 | +ajs_anonymous_id=%2239ee7ea5-b6d8-4174-b612-04e1ef3fa952 |
| 30 | +``` |
| 31 | + |
| 32 | +You can override the default-generated anonymousID in code using the methods described below: |
| 33 | +- [Set anonymousId from the Segment snippet](#override-the-anonymous-id-from-the-segment-snippet) (before the `ready` method returns) |
| 34 | +- [Use a call to override the anonymousID](#override-the-default-anonymous-id-with-a-call) |
| 35 | +- [Set anonymousId in the `options` object of a call](#override-the-anonymous-id-using-the-options-object) |
| 36 | + |
| 37 | +### Retrieve the Anonymous ID |
| 38 | + |
| 39 | +You can get the user's current `anonymousId` using either of the following calls: |
| 40 | + |
| 41 | +```js |
| 42 | +analytics.user().anonymousId(); |
| 43 | +``` |
| 44 | + |
| 45 | +If the user's `anonymousId` is `null` (meaning not set) when you call this function, Analytics.js automatically generated and sets a new `anonymousId` for the user. |
| 46 | + |
| 47 | + |
| 48 | +### Refreshing the Anonymous ID |
| 49 | + |
| 50 | +A user's `anonymousId` changes when any of the following conditions are met. |
| 51 | + |
| 52 | +- The user clears their cookies _and_ `localstorage`. |
| 53 | +- Your site or app calls [`analytics.reset()`](/docs/connections/sources/catalog/libraries/website/javascript/#reset-or-logout) during in the user's browser session. |
| 54 | +- Your site or app calls `analytics.identify()` with a userId that is different from the current userId. |
| 55 | + |
| 56 | + |
| 57 | +### Override the Anonymous ID from the Segment snippet |
| 58 | + |
| 59 | +You can also set the `anonymousId` immediately inside your Segment snippet, even before the `ready` method returns. |
| 60 | + |
| 61 | + ```js |
| 62 | + analytics.load('writekey'); |
| 63 | + analytics.page(); |
| 64 | + analytics.setAnonymousId('ABC-123-XYZ'); |
| 65 | +``` |
| 66 | + |
| 67 | +Use this method if you are queueing calls before `ready` returns and they require a custom `anonymousId`. Keep in mind that setting the `anonymousId` in Analytics.js does not overwrite the anonymous tracking IDs for any destinations you're using. |
| 68 | + |
| 69 | +> info "" |
| 70 | +> Device-mode destinations that load their code on your site _might_ also set their own anonymous ID for the user that is separate and different from the Segment generated one. Some destinations use the Segment anonymousId. Read the documentation for each destination to find out if a destination sets its own ID. |
| 71 | +
|
| 72 | +### Override the default Anonymous ID with a call |
| 73 | + |
| 74 | +If the default generated UUID does not meet your needs, you can override it `anonymousId` for the current user using either of the following methods. |
| 75 | + |
| 76 | +```js |
| 77 | +analytics.user().anonymousId('ABC-123-XYZ'); |
| 78 | +``` |
| 79 | + |
| 80 | +```js |
| 81 | +analytics.setAnonymousId('ABC-123-XYZ') |
| 82 | +``` |
| 83 | + |
| 84 | +These methods behave exactly the same. |
| 85 | + |
| 86 | +### Override the Anonymous ID using the options object |
| 87 | + |
| 88 | +Or in the `options` object of [`identify`](/docs/connections/spec/identify/), [`page`](/docs/connections/spec/page/), or [`track`](/docs/connections/spec/track/) calls, like this: |
| 89 | + |
| 90 | + |
| 91 | +Set the anonymousId in the Options object using the format in the following examples. |
| 92 | + |
| 93 | +The custom anonymousId persists when you use these methods, even if you do not explicitly specify the anonymousId in the calls. |
| 94 | + |
| 95 | +For example, after the Track call below sets the anonId, any later track calls from this user will have the anonymousId of `ABC-123-XYZ`, even if it is not explicitly specified in the track call. |
| 96 | + |
| 97 | +#### Override anonymousId in an Identify call |
| 98 | + |
| 99 | +```js |
| 100 | +analytics.identify('user_123', { |
| 101 | + name: 'Jane Kim' |
| 102 | +}, { |
| 103 | + anonymousId: 'ABC-123-XYZ' |
| 104 | +}); |
| 105 | +``` |
| 106 | + |
| 107 | +#### Override anonymousId on a Page call |
| 108 | + |
| 109 | +```js |
| 110 | +analytics.page({}, { anonymousId: 'ABC-123-XYZ' }); |
| 111 | +``` |
| 112 | + |
| 113 | +#### Override anonymousId on a Track call |
| 114 | + |
| 115 | +```js |
| 116 | +analytics.track('Email Clicked', { |
| 117 | + callToAction: 'Signup' |
| 118 | +}, { |
| 119 | + anonymousId: 'ABC-123-XYZ' |
| 120 | +}); |
| 121 | +``` |
| 122 | + |
| 123 | + |
| 124 | +## Saving traits to the context object |
| 125 | + |
| 126 | +Traits are individual pieces of information that you know about a user or a group, and which can change over time. |
| 127 | + |
| 128 | +The `options` dictionary contains a sub-dictionary called `context` which automatically captures data depending on the event- and source-type. See the [Context documentation](https://segment.com/docs/connections/spec/common/#context) to learn more. |
| 129 | + |
| 130 | +The `context` object contains an optional `traits` dictionary that contains traits about the current user. You can use this to store information about a user that you got from previous Identify calls, and that you want to add to Track or Page events. |
| 131 | + |
| 132 | +The information you pass in `context.traits` _does not_ appear in your downstream tools (such as Salesforce, Mixpanel, Google Analytics, etc.); however, this data _does_ appear in your [warehouses and storage destinations](/docs/connections/storage/). |
| 133 | + |
| 134 | +> note "" |
| 135 | +> The `options` object described in the previous seciton behaves differently from the `options.context.traits` object discussed here. The `traits` object described here does not cause the anonymousId to persist across different calls. |
| 136 | +
|
| 137 | +Consider this Identify event: |
| 138 | + |
| 139 | +```js |
| 140 | +analytics.identify('12091906-01011992', { |
| 141 | + plan_id: 'Paid, Tier 2' |
| 142 | + |
| 143 | +}); |
| 144 | +``` |
| 145 | + |
| 146 | +The "trait" on this event is `plan_id`. You can pass these traits into `context.traits`, so you can use them in Track or Page events that the user triggers later. |
| 147 | + |
| 148 | +The example below shows how you could pass the `plan_id` as a trait so you can use it later. |
| 149 | + |
| 150 | +```js |
| 151 | +analytics.track('Clicked Email', { |
| 152 | + emailCampaign: 'First Touch' |
| 153 | + }, |
| 154 | + { |
| 155 | + traits: { |
| 156 | + plan_id: 'Paid, Tier 2' |
| 157 | + } |
| 158 | + } |
| 159 | +); |
| 160 | +``` |
| 161 | + |
| 162 | +This appends the `plan_id` trait to this Track event. This does _not_ add the name or email, since those traits were not added to the `context` object. You must do this for every following event you want these traits to appear on, as the `traits` object does not persist between calls. |
| 163 | + |
| 164 | + |
| 165 | +## Clearing Traits |
| 166 | + |
| 167 | +You can pass an empty object to the `traits` object to clear _all_ cached traits for a User or Group. |
| 168 | + |
| 169 | +Traits are cached by default when you call the Identify and Group methods. You can clear the `traits` object for the user or group by passing `traits` an empty object: |
| 170 | + |
| 171 | +```js |
| 172 | +analytics.user().traits({}); |
| 173 | +``` |
| 174 | +```js |
| 175 | +analytics.group().traits({}); |
| 176 | +``` |
| 177 | + |
| 178 | +## User and Group Information |
| 179 | + |
| 180 | +You can use the `user` or `group` method as soon as the Analytics.js library loads, to return information about the currently identified user or group. This information is retrieved from the user's cookie. |
| 181 | + |
| 182 | +<!-- TODO: retrieves info from cookie, if they have any info - maybe link to the top section--> |
| 183 | + |
| 184 | + |
| 185 | +> success "" |
| 186 | +> **Tip:** You can wrap any reference to `user()` or `group()` in a [ready function block](/docs/connections/sources/catalog/libraries/website/javascript#ready) to ensure that Analytics.js has fully loaded so these methods are available. |
| 187 | +
|
| 188 | +Examples: |
| 189 | + |
| 190 | +```js |
| 191 | +analytics.ready(function() { |
| 192 | + |
| 193 | + var user = analytics.user(); |
| 194 | + var id = user.id(); |
| 195 | + var traits = user.traits(); |
| 196 | + |
| 197 | +}); |
| 198 | +``` |
| 199 | + |
| 200 | +```js |
| 201 | +analytics.ready(function() { |
| 202 | + |
| 203 | + var group = analytics.group(); |
| 204 | + var id = group.id(); |
| 205 | + var traits = group.traits(); |
| 206 | + |
| 207 | +}); |
| 208 | +``` |
| 209 | + |
| 210 | + |
| 211 | +## Anonymizing IP |
| 212 | + |
| 213 | +Segment automatically collects the user's IP address for device-based (iOS, Android, Analytics.js and Xamarin) events. |
| 214 | + |
| 215 | +You can pass a value for `options.context.ip` to prevent the Segment systems from recording the IP address for the request, as in the example below. |
| 216 | + |
| 217 | +```js |
| 218 | + analytics.track("Order Completed", {}, { context: { ip: "0.0.0.0" }}); |
| 219 | +``` |
| 220 | + |
| 221 | +You must add this override to _every_ Track call to explicitly override IP collection. If you reset this trait in the context object, Segment defaults to the normal IP collection behavior. |
0 commit comments