@sentientui/snippet 0.32.2 → 0.33.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/README.md +39 -11
- package/dist/editor.global.js +9 -9
- package/dist/engagement.global.js +1 -1
- package/dist/install.cjs +2 -2
- package/dist/install.d.cts +28 -5
- package/dist/install.d.ts +28 -5
- package/dist/install.js +2 -2
- package/dist/preview.global.js +1 -1
- package/dist/snippet.global.js +2 -2
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -16,7 +16,7 @@ page is left exactly as it was.
|
|
|
16
16
|
|
|
17
17
|
The install is two tags in `<head>`: an inline tag that sets `window.sentient` and then runs
|
|
18
18
|
the pre-paint script, followed by the deferred loader. Copy the real thing from your dashboard's
|
|
19
|
-
Install page, or generate it (the pre-paint script is ~
|
|
19
|
+
Install page, or generate it (the pre-paint script is ~3.7 KB and byte-identical for every site,
|
|
20
20
|
so it is not reproduced here):
|
|
21
21
|
|
|
22
22
|
```html
|
|
@@ -24,8 +24,9 @@ so it is not reproduced here):
|
|
|
24
24
|
window.sentient = {
|
|
25
25
|
apiKey: 'pk_your_key', // sentient-ui.com → Settings
|
|
26
26
|
personaAttributes: true, // sets data-sentient-persona / -confidence on <html>
|
|
27
|
+
stageAttributes: true, // optional: sets data-sentient-stage on <html> (see below)
|
|
27
28
|
persona: () => window.myApp?.role, // optional: declare the role your site already knows
|
|
28
|
-
// (string or function; must be a key from
|
|
29
|
+
// (string or function; must be a key from Matrix → Audiences)
|
|
29
30
|
sections: ['#hero', '#pricing', '#faq'], // optional: sections eligible for reordering,
|
|
30
31
|
// CSS selectors in your theme's natural order
|
|
31
32
|
slots: {
|
|
@@ -65,10 +66,18 @@ meant for is not a failure.
|
|
|
65
66
|
and on a return visit the browser may already have painted your original section order and
|
|
66
67
|
baseline styles before it does. The pre-paint script closes that gap: a tiny synchronous inline
|
|
67
68
|
script that applies the last served decision *before* the page paints. It reads only the
|
|
68
|
-
snapshot already stored on that visitor's own device, makes no network request,
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
69
|
+
snapshot already stored on that visitor's own device, makes no network request, and does
|
|
70
|
+
nothing at all on a first visit, for a Do-Not-Track / Global Privacy Control visitor, or unless
|
|
71
|
+
the config says `consent: true` or has no consent gate at all. There is no page-wide cloak, by
|
|
72
|
+
design. The one thing it hides is narrow: when the landing URL says the visitor clicked an ad or
|
|
73
|
+
an email — an ad click ID (`gclid`, `gbraid`, `wbraid`, `ttclid`, `msclkid`, `twclid`,
|
|
74
|
+
`li_fat_id`; not `fbclid`, which organic Meta clicks carry too), a paid or email `utm_medium`
|
|
75
|
+
(`cpc`, `paid_social`, `display`, `email`, `sms`, …) or a `/discount/` link — the components
|
|
76
|
+
you published from the dashboard that it found in the visitor's snapshot are kept invisible
|
|
77
|
+
(`visibility: hidden`, so nothing on the page moves) until this visit's decision is applied,
|
|
78
|
+
or for at most 300 ms. That visit may be served a version written for the campaign it came from,
|
|
79
|
+
and showing last visit's version first is exactly the flicker that wastes the click. Every
|
|
80
|
+
other visitor is untouched, and there is no hold in previews or the editor, or without consent. It can't read a consent platform (it runs before any of them load),
|
|
72
81
|
so with `consentFrom` it steps aside and the loader applies the visitor's decision once the
|
|
73
82
|
platform grants. See [Consent](#consent). Anything it gets wrong — a
|
|
74
83
|
selector that resolved differently mid-parse, say — the loader reverts within the same page
|
|
@@ -98,7 +107,7 @@ up new snippet versions on its own and this tag is pasted once. That is the reco
|
|
|
98
107
|
and what the Shopify app embed and the dashboard's install page both hand out.
|
|
99
108
|
|
|
100
109
|
**Pinning instead.** Add `@<version>` to the package path
|
|
101
|
-
(`@sentientui/snippet@0.
|
|
110
|
+
(`@sentientui/snippet@0.32.2/dist/snippet.global.js`) when you want a controlled rollout, or
|
|
102
111
|
when you want Subresource Integrity — an SRI hash is only possible on a pinned URL, since the
|
|
103
112
|
hash changes with every release. Compute it from the published file
|
|
104
113
|
(`openssl dgst -sha384 -binary dist/snippet.global.js | openssl base64 -A`) and pass it as
|
|
@@ -112,8 +121,8 @@ version it sees running falls behind.
|
|
|
112
121
|
`engagement.global.js` (section and interaction capture, fetched at boot in parallel with the
|
|
113
122
|
decision, only for a visit that may be tracked), `consent.global.js` (only when a consent
|
|
114
123
|
source is configured, or on Shopify),
|
|
115
|
-
`preview.global.js` (only for `?sentient_preview=` / `?sentient_persona=`
|
|
116
|
-
dashboard) and `editor.global.js` (only when you open the on-site editor). Self-hosting? Put
|
|
124
|
+
`preview.global.js` (only for `?sentient_preview=` / `?sentient_persona=` /
|
|
125
|
+
`?sentient_context=` links from your dashboard) and `editor.global.js` (only when you open the on-site editor). Self-hosting? Put
|
|
117
126
|
all five files in one folder. If the chunk URL can't be derived (an inlined or bundled
|
|
118
127
|
snippet), set `consentSrc` / `editorSrc` in `window.sentient`. A missing consent chunk keeps
|
|
119
128
|
tracking **off** and logs a warning.
|
|
@@ -125,14 +134,33 @@ so a nonce-based policy needs no `'unsafe-inline'`.
|
|
|
125
134
|
```css
|
|
126
135
|
#hero[data-tone='urgent'] .cta { font-weight: 700; }
|
|
127
136
|
html[data-sentient-persona='trial_user'] .upgrade-banner { display: block; }
|
|
137
|
+
html[data-sentient-stage='returning'] .first-order-offer { display: none; }
|
|
128
138
|
```
|
|
129
139
|
|
|
140
|
+
`stageAttributes: true` puts the visitor's buying stage on `<html>` as `data-sentient-stage`, for
|
|
141
|
+
changes you want everyone at that stage to get — hiding the first-order discount from people who
|
|
142
|
+
have already bought, say. It only appears once stages are turned on for the project (e-commerce
|
|
143
|
+
projects record them from the start), and never for visitors in the control group: a stage rule
|
|
144
|
+
is the same for everyone at that stage, so it is not an experiment, and the control group is how
|
|
145
|
+
its effect is measured. The values are `new`, `browsing`, `carted` and `returning` (has bought
|
|
146
|
+
here before). Because any script on the page — and anyone at a shared computer — can read it,
|
|
147
|
+
`customer` and `lapsed` are only shown separately if you ask for them with
|
|
148
|
+
`stageAttributes: 'detailed'`. How the visitor arrived (an ad, an email) is never written to the
|
|
149
|
+
page. The value is set before paint from the visitor's last visit and corrected when this
|
|
150
|
+
visit's decision arrives.
|
|
151
|
+
|
|
152
|
+
To see your site as visitors at one stage, or arriving one way, see it, add
|
|
153
|
+
`?sentient_context=` to any page: `carted`, `customer`, `cart_recovery`, `product_ad`, and so on.
|
|
154
|
+
It previews read-only — nothing is recorded — showing the versions you limited to that audience
|
|
155
|
+
with **Show to**, and says so when those versions are not being served yet. It combines with
|
|
156
|
+
`?sentient_persona=`.
|
|
157
|
+
|
|
130
158
|
The first value of each dim is your baseline (what you show today). Decisions are locked per
|
|
131
159
|
session and learned per visitor type on the SentientUI API: a first visit sees your original, the return visit adapts.
|
|
132
160
|
|
|
133
161
|
`persona` declares the visitor type your site already knows (e.g. a role from your own
|
|
134
162
|
session state) instead of waiting for it to be inferred. It must be a key in the project's
|
|
135
|
-
persona vocabulary (dashboard →
|
|
163
|
+
persona vocabulary (dashboard → Matrix → Audiences); unrecognized values are ignored
|
|
136
164
|
server-side and surfaced in the dashboard so you can add them. Keep it a low-cardinality
|
|
137
165
|
role label — never a user id or email.
|
|
138
166
|
|
|
@@ -202,4 +230,4 @@ Everything stored and sent is listed in
|
|
|
202
230
|
|
|
203
231
|
The always-on bundle is capped at 29 KiB gzip, a ceiling that only ever goes down. The
|
|
204
232
|
engagement, consent and preview chunks are capped at 6.5, 3.5 and 3 KiB gzip, the editor overlay
|
|
205
|
-
at 30 KiB gzip, and the pre-paint tag at 3 KiB raw. All limits are CI-enforced. MIT.
|
|
233
|
+
at 30 KiB gzip, and the pre-paint tag at 3.7 KiB raw. All limits are CI-enforced. MIT.
|