Skip to content

Commit e646210

Browse files
bot-docsteambot-docsteam
authored
Merge pull request #376 from segmentio/repo-sync
repo sync
2 parents 34ef0fe + 473683f commit e646210

File tree

2 files changed

+125
-0
lines changed

2 files changed

+125
-0
lines changed

‎src/_data/sidenav/strat.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -110,6 +110,8 @@ sections:
110110
title: Quickstart tutorial
111111
- path: /connections/sources/catalog/libraries/website/javascript/custom-proxy
112112
title: Custom proxy for Analytics.js
113+
- path: /connections/sources/catalog/libraries/website/javascript/persistence
114+
title: Client-side persistence in Analytics.js
113115
- path: /connections/sources/catalog/libraries/website/javascript/identity
114116
title: Managing identity in Analytics.js
115117
- path: /connections/sources/catalog/libraries/website/javascript/middleware

‎src/connections/sources/catalog/libraries/website/javascript/persistence.md

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
---
2+
title: Client-side persistence in Analytics.js
3+
strat: ajs
4+
---
5+
6+
This page explains what data Analytics.js stores on the client and how to override and change what and how this data is stored.
7+
8+
## Segment ID Persistence
9+
10+
<!-- Note: 1st 2 paragraphs copied from identity.md -->
11+
12+
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 for storing this type of first-party customer information.
13+
14+
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, it sets 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`](/docs/connections/sources/catalog/libraries/website/javascript/identity/#anonymous-ids) when they next visit the page.
15+
16+
### Cookie Settings
17+
18+
Analytics.js sets some default properties when creating cookies for user or group identities. You can override the default cookie properties in code when loading Analytics.js by passing in a `cookie` object to the load method.
19+
20+
Here is the full list of available parameters with their default values:
21+
22+
| Parameter | Description | Default value |
23+
| --- | --- | --- |
24+
| `domain` | The domain to set the cookie to. This must match the domain of the JavaScript origin. Cookies set on top-level domain are available to sub-domains. | Top-level domain |
25+
| `maxage` | The maximum amount of time in seconds before the cookie expires. Browsers may clear cookies before this elapses. | 1 year |
26+
| `path` | The path the cookie is valid for. | `"/"` |
27+
| `sameSite` | This prevents the browser from sending the cookie along with cross-site requests. | `Lax` |
28+
| `secure` | This determines whether cookies can only be transmitted over secure protocols such as https. | `false` |
29+
30+
Example:
31+
```js
32+
analytics.load('writeKey', {
33+
cookie: {
34+
domain: 'sub.site.example',
35+
maxage: 604800, // 7 days in seconds
36+
path: '/',
37+
sameSite: 'Lax',
38+
secure: true
39+
}
40+
})
41+
```
42+
43+
### User Settings
44+
45+
Analytics.js automatically persists the user's ID and traits locally. You can override how and where the user ID and traits are stored when loading Analytics.js by passing in a `user` object to the load method.
46+
47+
The user object has the following fields and default values:
48+
49+
| Option | Description | Default value |
50+
| ------ | ----------- | ------------- |
51+
| `persist` | This toggles storing user information locally. | `true` |
52+
| `cookie.key` | Name of the cookie used to store the user ID. | `ajs_user_id` |
53+
| `cookie.oldKey` | Name of a cookie previously used to store the user ID. Will be read if `cookie.key` can't be found. | `ajs_user` |
54+
| `localStorage.key` | Name of the key used to store user traits in localStorage. | `ajs_user_traits` |
55+
56+
Example:
57+
```js
58+
analytics.load('writeKey', {
59+
user: {
60+
persist: true,
61+
cookie: {
62+
key: 'ajs_user_id'
63+
},
64+
localStorage: {
65+
key: 'ajs_user_traits'
66+
}
67+
}
68+
})
69+
```
70+
71+
### Group Settings
72+
73+
Analytics.js automatically persists the user's group ID and group properties locally. You can override how and where the group ID and properties are stored when loading Analytics.js by passing in a `group` object to the load method.
74+
75+
The group object has the following fields and default values:
76+
77+
| Field | Description | Default value |
78+
| ----- | ----------- | ------------- |
79+
| `persist` | Toggles storing group information locally. | `true` |
80+
| `cookie.key` | Name of the cookie used to store the group id. | `ajs_group_id` |
81+
| `localStorage.key` | Name of the key used to store user traits in localStorage. | `ajs_group_properties` |
82+
83+
Example:
84+
```js
85+
analytics.load('writeKey', {
86+
group: {
87+
persist: true,
88+
cookie: {
89+
key: 'ajs_group_id'
90+
},
91+
localStorage: {
92+
key: 'ajs_group_properties'
93+
}
94+
}
95+
})
96+
```
97+
98+
## Persistent Retries
99+
100+
When enabled, Analytics.js automatically retries network and server errors. When the client is offline or your application can't connect to Segment's API, Analytics.js stores events in `localStorage` and falls back to in-memory storage when `localStorage` is unavailable.
101+
102+
## Disable All Client-Side Persistence
103+
104+
<!-- TODO: Mention GDPR and/or regulations as a reason to do this? -->
105+
Analytics.js supports disabling persisting any data locally. This will force analytics.js to store data in-memory only and disables automatic identity tracking across pages.
106+
107+
You can completely disable client-side persistence when loading Analytics.js by setting `disableClientPersistence` to `true`.
108+
109+
```js
110+
analytics.load('writeKey', { disableClientPersistence: true })
111+
```
112+
113+
### Identity
114+
115+
When `disableClientPersistence` is set to `true`, Analytics.js won't be able to automatically keep track of a user's identity when navigating to different pages. This can cause increased MTU usage if the anonymous usage can't be associated with a `userId`.
116+
117+
You can still manually track identity by calling `analytics.identify()` with the known identity on each page load, or you can pass in identity information to each page using the [querystring API](https://segment.com/docs/connections/sources/catalog/libraries/website/javascript/querystring/).
118+
119+
### Event Retries
120+
121+
Analytics.js tries to detect when a page is about to be closed and saves pending events to `localStorage`. When the user navigates to another page within the same domain, Analytics.js attempts to send any events it finds in localStorage.
122+
123+
When `disableClientPersistence` is set to `true`, Analytics.js won't store any pending events into `localStorage`.

0 commit comments

Comments
 (0)