@usesequential/browser 0.0.0-stage → 1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +7 -0
- package/LICENSE +21 -0
- package/README.md +84 -2
- package/dist/index.cjs +1950 -0
- package/dist/index.d.cts +49 -0
- package/dist/index.d.mts +49 -0
- package/dist/index.mjs +1948 -0
- package/package.json +48 -4
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## 1.0.0
|
|
4
|
+
|
|
5
|
+
- First release: `init(options)` and `VERSION`. The SDK code is `sequential.js`, the file the script tag loads, with
|
|
6
|
+
the same behaviour: autocapture, session replay, identify, accounts, opt-out (no id or session value stored before
|
|
7
|
+
opt-in or while opted out) and the context cookie `__sq_ctx`.
|
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Sequential
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,85 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @usesequential/browser
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
The [Sequential](https://www.usesequential.com) browser SDK as an npm package: product analytics and session replay
|
|
4
|
+
from one call. The code is `sequential.js`, the file that the Sequential script tag loads, with the same behaviour.
|
|
5
|
+
|
|
6
|
+
- Page views, clicks, form submits, rage clicks and dead clicks, recorded automatically.
|
|
7
|
+
- Session replay, when replay is on for your project. The SDK loads the recorder from your ingest host.
|
|
8
|
+
- `identify`, `account`, custom events and errors.
|
|
9
|
+
- Consent: start opted out, and nothing is stored on the device until `optIn()`.
|
|
10
|
+
- No dependencies. ES modules and CommonJS. Types included. Safe to import in server-rendered apps.
|
|
11
|
+
|
|
12
|
+
## Install
|
|
13
|
+
|
|
14
|
+
```bash
|
|
15
|
+
npm install @usesequential/browser
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
Copy the project's **sequential** key (`sq_sequential_…`) and the API host from **Setup** in Sequential.
|
|
19
|
+
|
|
20
|
+
## Start it
|
|
21
|
+
|
|
22
|
+
Call `init()` once, in the browser, as early as you can:
|
|
23
|
+
|
|
24
|
+
```ts
|
|
25
|
+
import { init } from '@usesequential/browser';
|
|
26
|
+
|
|
27
|
+
const sequential = init({
|
|
28
|
+
key: 'sq_sequential_…',
|
|
29
|
+
api: 'https://api.usesequential.com',
|
|
30
|
+
release: 'web@2.14.1', // optional: your app's build, on every event
|
|
31
|
+
});
|
|
32
|
+
|
|
33
|
+
sequential.identify(user.id, { email: user.email });
|
|
34
|
+
sequential.capture('checkout_started', { plan: 'pro' });
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
`init()` also sets `window.sequential`, the same object, so code written for the script tag works.
|
|
38
|
+
|
|
39
|
+
- **Server rendering.** Importing the package does nothing. Without a window, `init()` returns an object whose
|
|
40
|
+
methods do nothing. Call it from client code: in SvelteKit in `onMount` or a `+layout.svelte` browser block, in
|
|
41
|
+
Next.js in a client component's `useEffect`.
|
|
42
|
+
- **Call it once.** A second `init()` returns the running SDK and writes a warning to the console.
|
|
43
|
+
- **Not with the script tag.** Use the package or the tag, not both. If the tag already loaded the SDK, `init()`
|
|
44
|
+
returns that SDK and does not read its options. If the tag's install snippet ran first, `init()` sends the calls
|
|
45
|
+
that it queued.
|
|
46
|
+
|
|
47
|
+
## Options
|
|
48
|
+
|
|
49
|
+
| Option | Same as the tag's | |
|
|
50
|
+
|---|---|---|
|
|
51
|
+
| `key` | `data-key` | Required. |
|
|
52
|
+
| `api` | `data-api` | Required. |
|
|
53
|
+
| `release` | `data-release` | 1 to 64 printable ASCII characters. |
|
|
54
|
+
| `optOut: true` | `data-opt-out` | Start opted out. |
|
|
55
|
+
| `autocapture: false` | `data-autocapture="false"` | No automatic page views, clicks or form submits. |
|
|
56
|
+
| `identityText: false` | `data-identity-text="off"` | No check for the signed-in person's name and email in click text. |
|
|
57
|
+
| `contextCookieDomain` | `data-context-cookie-domain` | `Domain=` for the context cookie `__sq_ctx`. |
|
|
58
|
+
|
|
59
|
+
Without `key` and `api`, `init()` writes one error to the console and sends nothing.
|
|
60
|
+
|
|
61
|
+
## Consent
|
|
62
|
+
|
|
63
|
+
For a site that waits for consent, start opted out and call `optIn()` when the visitor agrees:
|
|
64
|
+
|
|
65
|
+
```ts
|
|
66
|
+
const sequential = init({ key: 'sq_sequential_…', api: 'https://api.usesequential.com', optOut: true });
|
|
67
|
+
consentBanner.onAccept(() => sequential.optIn());
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
Before opt-in, and while a visitor is opted out, the SDK stores no id, no session value and no cookie on the device.
|
|
71
|
+
With `optOut: true`, it stores nothing at all. `optOut()` deletes the ids that the SDK stored and keeps one key,
|
|
72
|
+
`__sq_opt`, that holds only the visitor's choice, so the opt-out stays in force on the next pages. `optIn()` deletes
|
|
73
|
+
it.
|
|
74
|
+
|
|
75
|
+
## Methods
|
|
76
|
+
|
|
77
|
+
`capture(name, props)`, `identify(userId, props)`, `account(id, traits)`, `register(props)`, `unregister(name)`,
|
|
78
|
+
`reset()`, `optOut()`, `optIn()`, `captureException(error, props)` and `flush()`. Names that start with `$` are
|
|
79
|
+
reserved, and `capture()` throws on them.
|
|
80
|
+
|
|
81
|
+
Full documentation: https://www.usesequential.com/docs/browser-npm and https://www.usesequential.com/docs/sequential.
|
|
82
|
+
|
|
83
|
+
## Licence
|
|
84
|
+
|
|
85
|
+
MIT
|