@sentientui/snippet 0.32.3 → 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 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 ~2.6 KB and byte-identical for every site,
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,6 +24,7 @@ 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
29
  // (string or function; must be a key from Matrix → Audiences)
29
30
  sections: ['#hero', '#pricing', '#faq'], // optional: sections eligible for reordering,
@@ -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, hides nothing
69
- (there is no cloak here, by design), and does nothing at all on a first visit, for a
70
- Do-Not-Track / Global Privacy Control visitor, or unless the config says `consent: true` or
71
- has no consent gate at all. It can't read a consent platform (it runs before any of them load),
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
@@ -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=` links from your
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,8 +134,27 @@ 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
 
@@ -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.