SDK Documentation
@sentientui/react — styling, content, and section order per visitor type, no tagging required
Overview
SentientUI is intent-adaptive UI for React: visitor profiles and audience groups drive which variant each visitor sees, trained from conversion scores on SentientUI's hosted API (you do not deploy the learning stack). Install the open SDK from npm — the client source is on GitHub — and add API keys from the dashboard.
It works in any React app and has first-class support for Next.js App Router with server-side rendering — code variants listed in AdaptiveRoot are preloaded so they appear in the initial HTML for SEO and zero layout shift on first paint. Generated versions arrive just after the page loads: a first visit shows your original briefly before the version swaps in.
The adaptive ladder
One concept at four altitudes: a bounded, designer-approved piece of UI with a declared set of variations and a goal. Climb one rung at a time — every rung pays for itself. A visitor's first visit teaches Sentient who they are; the next visit shows them the page most likely to convert.
Rung 0 — Observe. Install is the integration: the dashboard immediately shows your traffic — and, as personas are declared by your app or discovered, how it splits — and suggests the next rung with a copy-pasteable snippet.
Rung 1 — Style (CSS only). The SDK sets data-sentient-persona and data-sentient-confidence on <html> before first paint — write plain CSS against them. Or declare a bounded token set and let the optimizer learn which look converts best per visitor type:
import { useAdaptiveTokens } from '@sentientui/react';
function Hero() {
const t = useAdaptiveTokens('hero', {
tone: ['calm', 'urgent'], // first value = what you show today
});
return <section {...t.props} className="hero">…</section>;
}
/* CSS */
.hero[data-tone='urgent'] .cta { font-weight: 700; }
html[data-sentient-persona='admin'] .admin-tools { display: block; }
html[data-sentient-confidence='low'] .admin-tools { display: none; }Stores: the buying stage. Turn on stageAttributes (an AdaptiveRoot prop, or a key in the snippet's window.sentient) and the SDK also sets data-sentient-stage on <html>: new, browsing, carted or returning (has bought here before). Use it for changes everyone at that stage should get — like hiding the first-order discount from people who have already bought. Any script on the page can read it, so customer and lapsed are only shown separately with stageAttributes: 'detailed', and how the visitor arrived (an ad, an email) is never written to the page. Visitors in the control group don't get it: a stage rule isn't an experiment, and the control group is how its effect is measured.
html[data-sentient-stage='returning'] .first-order-offer { display: none; }To see your site the way one stage or one kind of arrival sees it, add ?sentient_context=carted (or customer, cart_recovery, product_ad, …) to any page. Like ?sentient_persona=, it's read-only — nothing is recorded — and it shows the versions you limited to that audience with Show to.
Rung 2 — Swap (alternate content). Headless variant selection with measurement built in — goal is required and bind must be attached:
import { useAdaptive } from '@sentientui/react';
const { value, bind } = useAdaptive('buy-box', {
variants: { calm: <CalmBuyBox />, urgent: <UrgentBuyBox /> }, // first key = baseline
goal: 'buy_click',
});
return <div {...bind}>{value}</div>;Rung 3 — Reorder (structure). Designer-approved arrangements of keyed children — never free shuffling, and every decision is locked for the visit:
import { AdaptiveGroup } from '@sentientui/react';
<AdaptiveGroup id="pricing-area" arrangements={{
standard: ['plans', 'faq', 'social'], // first key = baseline
social_first: ['social', 'plans', 'faq'],
}}>
<PlanGrid key="plans" /> <Faq key="faq" /> <Testimonials key="social" />
</AdaptiveGroup>Try it with no account — keyless local mode
npx @sentientui/cli init # detects your framework, prints a wrap snippet, adds an example
# you still wrap <AdaptiveProvider> yourself — init does not edit layout
npm run dev
# open http://localhost:3000?sentient_persona=a, then ?sentient_persona=b — watch the page adaptWithout an API key, development builds simulate every decision on your machine — deterministic, zero network, nothing sent anywhere. Force any persona with ?sentient_persona= or the devtools panel. Add a pk_… key later to learn from real traffic; nothing else changes. Production bundles physically exclude the local engine.
@sentientui/snippet package brings the ladder to any site with a script tag — persona attributes and learned style tokens, the components you publish from the dashboard's on-site editor (copy, styles and composition blocks, built element by element — never raw HTML), and reordering of the sections you list. Any error leaves the page untouched. See Setup — Shopify and no-code sites. The install is two tags in <head>: one inline tag that sets window.sentient and applies the visitor's last decision before first paint, then the deferred loader — copy both from your project's Install page. Sites with a hash-based Content-Security-Policy use the three-tag form shown there instead: split out, the pre-paint tag is byte-identical on every site, so one hash covers it. Existing three-tag and two-tag installs keep working.Installation
Install the React package. The core engine is included automatically as a dependency.
npm install @sentientui/react
# or
yarn add @sentientui/react
# or
pnpm add @sentientui/reactYou only ever import from @sentientui/react. The @sentientui/core package is the framework-agnostic engine — it ships as a dependency and you do not need to install or import it directly.
API key
Each project gets an API key when you create it in the dashboard, and you can issue more or rotate from Project settings → API key. Keys look like pk_xxxxxxxxxxxxxxxx. A pk_ key is public by design — it ships in your site's HTML — so teammates can copy it from that page any time (an older key that shows only its prefix there can't be recovered: use Issue an additional key, which leaves the live one working). Server keys (sk_) are secrets: stored only as a hash and shown once, when you generate them, so copy one before closing the dialog. If you lose it, generate a new one (that revokes the old one).
pk_ (public key). It is designed for browser and SSR helpers: the API checks an allowed-origins allowlist so other websites cannot casually reuse your key from a visitor's browser. That allowlist is not cryptographic authentication — anyone who has the pk_ can set an Origin header from a server. Protect the key like any client credential, keep origins tight, rely on rate limits and session ownership checks, and record trusted server-side conversions with an sk_ key (accepted on /v1/goals and /v1/events without an Origin). Add your production domain in Project settings → Allowed domains.Environment variables
Add your API key to .env.local. One variable is all you need.
# .env.local
NEXT_PUBLIC_SENTIENT_API_KEY=pk_your_key_hereSetup — Next.js App Router
Wrap your root layout with <AdaptiveProvider>. That is the whole setup: every <Adaptive> under it registers itself the first time it renders, with nothing to declare here.
// app/layout.tsx
import { AdaptiveProvider } from '@sentientui/react';
export default function RootLayout({ children }) {
return (
<html lang="en">
<body>
<AdaptiveProvider apiKey={process.env.NEXT_PUBLIC_SENTIENT_API_KEY!}>
{children}
</AdaptiveProvider>
</body>
</html>
);
}Optional: the chosen version in the first HTML
<AdaptiveRoot> is a server component that decides components before the HTML is sent, so they render with real content on the first paint instead of showing your original first — no swap, and crawlers see the served markup. Wrap the page that adapts in it, and list code-variant components in components and generated ones in registrySlotIds, using the same ids as on the page:
// app/pricing/page.tsx — only this route pays for it
import { AdaptiveRoot } from '@sentientui/react/next';
export default function PricingPage() {
return (
<AdaptiveRoot
components={[{ id: 'hero_cta', variantIds: ['control', 'variant_a'] }]} // <Adaptive id="hero_cta" variants={…}>
registrySlotIds={['pricing-headline']} // <Adaptive id="pricing-headline">
apiKey={process.env.NEXT_PUBLIC_SENTIENT_API_KEY!}
timeoutMs={300}
>
<Pricing />
</AdaptiveRoot>
);
}<AdaptiveRoot> out of your root layout. It reads the request to decide per visitor, so every route under it renders on each request — none can be statically generated or served from the edge cache — and each waits for one API round trip (capped by timeoutMs) before sending HTML. In app/layout.tsx that is your whole site. Put it on the pages that adapt, or in a route group's layout.tsx for several, and do not nest it inside the root layout's <AdaptiveProvider>: those pages belong in a route group whose layout does not render the provider.<AdaptiveRoot> wraps, whether or not the component is on the page, and each of those counts as a view that can never convert.'use client' to the file that renders it, and do not nest <AdaptiveRoot> inside any component that has it. If it ends up in a client boundary, the server-side /v1/decide call never fires — sessions will be created but no events, assignments, or dashboard data will appear.AdaptiveRoot props
componentsArray<{ id: string; variantIds: string[] }> (optional)<Adaptive> components to decide server-side. The id must match exactly what you pass to <Adaptive id="...">, and variantIds must include every key in its variants prop. List only components rendered on every page this root wraps: each listed id records a view on every request, rendered or not. Omit and they are decided in the browser after mount.registrySlotIdsstring[] (optional)<Adaptive>s (no variants) to decide server-side, so the first paint shows the published version instead of your original. Same rule: only ids rendered on every wrapped page. Omit and they swap in after mount.apiKeystringpk_… API key, set via NEXT_PUBLIC_SENTIENT_API_KEY. Used by both the browser SDK and server-side SSR requests — one env var is all you need.context'saas' | 'landing' | 'ecommerce' | 'marketplace' (optional, deprecated)consentboolean (default: true)false to prevent the SDK from initialising. No events are sent, no cookies are written. Flip to true once the visitor grants consent. See Consent / GDPR below.respectDoNotTrackboolean (default: true)consent is true — and grantConsent() will not re-enable it. Set to false to make your own consent gate authoritative. See Consent / GDPR below.appOriginstring (optional)https://yourapp.com. Must match a value in the project's allowed origins list. Used in server-side assignment and session requests. When omitted it is https:// plus the request's Host header in production, and http://localhost:3001 in development — set it explicitly if your host serves more than one domain or sits behind a proxy that rewrites Host.enableGraphboolean (default: true)false to turn it off.captureAgentsboolean (default: true)<AdaptiveRoot> is a Server Component it sees these requests even though they never run JavaScript — no middleware needed. Machine telemetry only: no cookie, no session, independent of consent / Do Not Track. See Explore → AI agents in the dashboard. Set false to opt out.engagementboolean (default: true)false to turn it off.noncestringheaders(). Omit it if you don't use a nonce-based CSP.Setup — other React apps
For Vite, Create React App, Remix, or any React app without Next.js App Router, use <AdaptiveProvider> directly. Variants are assigned on the client after mount — there is no SSR preloading, but the optimizer still learns and optimises normally.
// main.tsx or App.tsx
import { AdaptiveProvider } from '@sentientui/react';
export default function App() {
return (
<AdaptiveProvider
apiKey="pk_your_key_here"
>
<YourApp />
</AdaptiveProvider>
);
}<AdaptiveProvider> accepts the same consent prop as <AdaptiveRoot>, plus onAssignment (not available on <AdaptiveRoot> — function props can't cross the RSC boundary), initialAssignments for Pages Router SSR, and debug?: boolean to log assignment and event activity to the console. DOM graph scanning and behavioral engagement capture are on by default (see enableGraph and engagement above to opt out).
Setup — Shopify and no-code sites
Sites not built with React — Shopify, Webflow, WordPress, plain HTML — use the script tag (@sentientui/snippet). It sets visitor-type attributes your CSS can react to, serves the components you publish from the dashboard's on-site editor (copy, styles and composition blocks — never raw HTML), and can reorder the page sections you list. Goals are defined in the editor too, so nothing else needs code.
Shopify
The SentientUI Shopify app installs the script through a theme app embed and forwards paid, refunded and cancelled orders, so revenue is measured from Shopify's own records. The app is not listed on the Shopify App Store yet: create a project with the Shopify framework, then request an install link from the Install page.
- Install the app, open it in your Shopify admin, paste the project's
pk_andsk_keys, and save. The purchase goal, checkout funnel and refund netting are set up on save. - In Online Store → Themes → Customize → App embeds, switch SentientUI on and save the theme.
- Place a test order: it appears as a purchase in your dashboard.
Consent follows Shopify's Customer Privacy API (consentFrom: 'shopify', snippet 0.32+), which Shopify's banner and Shopify cookie-banner apps report into — see Consent platforms.
Any other site
Copy the install tags from your project's Install page into the site's <head>. There are two: an inline tag that sets window.sentient and applies the visitor's last decision before the page paints, then the deferred loader. Then open the on-site editor from the dashboard to publish your first component. If the site has a cookie banner, add consentFrom to window.sentient (see Consent platforms).
How variants are created
There are three ways to fill a component. The difference is about where the content lives and how the variant gets registered — and it determines whether you need to do anything in the dashboard at all.
Generated versions (start here)
Wrap a section in <Adaptive> without a variants prop and your children become the original. SentientUI writes versions per visitor type from the dashboard — open the component on Components, under Who sees it — no code, no redeploy. See Generated versions below.
Code-native variants
The variants you declare in your app — the keys of the variants prop on <Adaptive> — live in your code. You do not create them in the dashboard first. The SDK reports the variant IDs when it requests an assignment, and the API registers them automatically the first time traffic hits the component after you deploy. They go live and start learning immediately. This is the path developers (and AI agents writing code) use.
No-code (managed) variants
Variants with no code — created from the dashboard (Components, open the component, Add text version), via <AdaptiveText>, or through the MCP create_variant tool. Their content is stored on the SentientUI API and rendered by the SDK without a redeploy, which is what lets you iterate copy without shipping code. Managed variants start as a draft and must be activated from the dashboard before traffic is assigned to them.
<Adaptive> with no variants and deploy. If you are writing the variant in code, add it to the variants map (and to the AdaptiveRoot components list for SSR) and deploy — it registers itself. Only use Add text version in the dashboard or MCP create_variant for no-code variants whose content lives in SentientUI.<Adaptive> component
The main building block. Wrap any piece of UI you want to adapt. There are two ways to fill it: leave out variants and let SentientUI write versions for each visitor type, or write the variants yourself in code. Either way the SDK picks what each visitor sees, tracks impressions automatically, and records a score when the goal fires.
Generated versions — start here
Wrap a section and give it an id. Your children are the original. SentientUI may replace them with a version written for the visitor's type — edits to your own text, replacement copy, or a small designed layout built from a validated set of building blocks (headings, text, buttons, badges, images, and forms), styled with your site's own styles. Versions are created on each component's Who sees it and approved on Needs you — no redeploy.
import { Adaptive } from '@sentientui/react';
<Adaptive id="hero-cta" goal="signup_click">
<a className="btn" href="/signup">Start free trial</a>
</Adaptive>The children render untouched for control/holdout traffic, visitors whose type isn't known yet, visitor types with no version, and every error path — the worst case is always your original renders, never a broken or empty section.
Props — generated versions
idstring_ or -, up to 128 characters.childrenReactNodegoalstring | GoalConfig (optional)onFormSubmit(values: Record<string, string>) => void (optional)classNamestring (optional)<div>.reportBaselineTextboolean (default: true)false for personalized or account content. See below.Forms — your goal fires, your handler gets the values
A version may contain one small form: at most 5 fields, every field labeled, input types limited to text, email, number, and tel — never password, file, or hidden inputs. Submitting fires one of your project's own goals (a form is only valid if its submit goal resolves to a real goal you defined), then calls your onFormSubmit with the values. SentientUI credits the conversion; the field values never reach SentientUI.
<Adaptive
id="hero-cta"
onFormSubmit={(values) => {
// Your handler, your data — SentientUI never stores form values.
createLead(values);
}}
>
<a className="btn" href="/signup">Start free trial</a>
</Adaptive>Works in any React app — no server preload
Wrap the section and deploy; that is the whole integration. It works as-is under <AdaptiveRoot> (Next.js App Router) or <AdaptiveProvider> (everything else). When generated <Adaptive>s mount, the SDK asks for exactly those in one request and swaps in the version this visitor should see. Only sections actually on the page are decided, so one on another page never counts this visit against its versions. On a first visit your original shows briefly before a version replaces it; later visits start from the last version they were shown. In keyless local mode generated versions don't serve — your original renders.
Sections register themselves
Mount a generated <Adaptive> in a keyed app and deploy — that's the whole registration. If the server has no definition for the id, the SDK reports it once (batched, deduped) and it appears on Components as a draft, its Who sees it showing “Original” for every visitor type, ready to generate into. Nothing serves and nothing on your page changes until a first version goes live.
The first report also carries the region's rendered text (whitespace-collapsed, capped at 400 characters, recorded only once) so generated versions are grounded in what they replace. Only the wrapped region is read — never the page around it. For a section wrapping personalized or account content, pass reportBaselineText={false} to register the id without sending any text.
Code variants
When you want to write the alternatives yourself, pass them as variants. The first key is the control, and goal is required.
import { Adaptive } from '@sentientui/react';
<Adaptive
id="hero_cta"
goal="signup_click"
variants={{
control: <button className="btn-dark">Start free trial</button>,
variant_a: <button className="btn-blue">Get instant access →</button>,
}}
/>Variant keys are versions, not audiences. Naming a version developer doesn't show it to developers — the optimizer may show any version to any visitor. To show developer to your Developers: declare the persona on your site (Declaring a persona), then pin the version to that audience — Migrate the component in Components and accept “Show each version to the audience it's named after?”, or pin it later from the banner there. Pinned visitors always see that version, and they don't teach the optimizer.
Props — code variants
idstringid in your AdaptiveRoot components list if you want SSR preloading.variantsRecord<string, ReactNode>control, variant_a, short, with_image, etc.). The first key is the control. You can have two or more variants. The optimizer will explore all of them and exploit the winner over time.goalstring | GoalConfigfunnelstring (optional)checkout), shown on the dashboard's Funnels tab. With a weighted_composite goal it also declares the funnel's ordered steps, and the optimizer trains this component on journey progress: small credit for intermediate steps, full credit at completion. A weighted_composite without funnel declares its own funnel, <id>-steps.microSignalGoalsPartial<Record<MicroSignalType, string | { name; weight?; stepIndex? }>> (optional)rage_click to confused_by_hero.clientOnlyboolean (default: false)true, the component renders nothing on the server and waits until the client has hydrated and a provider context is available. Use this only for slots that depend on a browser-only value (e.g. a "welcome back" banner that reads a cookie). When false (the default), the component SSR-renders the preloaded variant — or the first variant when no preloaded assignment exists — which is recommended for above-the-fold content. Do not use clientOnly on CTAs or any component that must always be visible: if there is no provider context (e.g. consent={false} or AdaptiveRoot is not rendered), a clientOnly component renders nothing — not even after hydration.agentDataByVariantRecord<string, unknown> (optional)agentDataunknown (deprecated)agentDataByVariant.variants and children and the component runs as one experiment (@sentientui/react 0.37 and later): your hand-written variants, your original (the children) and dashboard-generated versions compete side by side, under the same scoring and the same automatic pause for a version that is clearly losing. funnel, microSignalGoals, agentData, agentDataByVariant and clientOnly work in that mode too (@sentientui/react 0.40 and later). A component that already has history as a variants-only component won't start the combined experiment until you run Migrate on it in Components — deploying code never switches an experiment by itself. Generated mode was formerly <AdaptiveSlot>, which still works but is deprecated.<AdaptiveText> component
<AdaptiveText> is a lightweight wrapper for text-only variants — headlines, button labels, subheadings, and any copy you want to iterate on without touching code. Variant content is stored on the SentientUI API and editable from the dashboard without a redeploy.
import { AdaptiveText } from '@sentientui/react';
<h1>
<AdaptiveText
id="hero_headline"
default="The fastest way to build adaptive UIs"
component="span"
goal="signup_click"
/>
</h1><AdaptiveText> renders a <span> by default. Pass component="h1", component="p", or any HTML tag to control the element. The winning copy is fetched from the API — update it in the dashboard without redeploying. Pass goal (a name or a goal config, exactly like <Adaptive>) so the optimizer can score the wording.
goal, <AdaptiveText> tracks impressions only — the copy is served and logged but never learns. Add versions in Components (open the component, Add text version). The default prop is the fallback shown during SSR and while the API response is in flight.Who sees it — versions per visitor type, no code
Open a component on Components and Who sees it answers the question in its name: each group of visitors, and the version it is shown there. The rows are led by Everyone — every visitor not confidently placed in another group, which is where most traffic lands and where versions can be written from day one. Every adaptive section has one: regions you wrapped in a generated <Adaptive> (no variants) or created from the dashboard. Auto-fill and “Write every missing version” are on Needs you, beside the approvals switch.
Each row also says where it came from, because a group you told us about and a group we are still guessing at are not the same thing and should never look the same:
| Row | What it means |
|---|---|
| Everyone | Where most visitors sit, and where the work starts on day one. This row is live from your first visitor. |
| Yours | A group your own code tells us about (a declared persona) — a signed-in role, a plan tier. We take your word for it; you know your users. |
| Being checked | A pattern we think we can see forming in your traffic. It does not serve anyone and does not spend anything yet. |
| Earned | A group your traffic has proved: a different version genuinely wins for it, so it now gets its own versions. |
| Starter | Older projects only: a suggested group from the set we used to ship in the box. You did not tell us it exists and we have not proved it does — keep it, rename it or remove it. New projects start with none. |
The order matters. Nothing beyond Everyone and the groups you declare will serve anything until your own visitors justify it.
No square is ever blank — each one says what that group sees right now:
| You see | What it means |
|---|---|
| Original | No version exists for this visitor type yet — they see your page as you built it. |
| Writing… | A version is being written now, usually in under a minute. |
| Waiting | This month’s writing allowance is used up. The version is queued and resumes automatically — the square says when. |
| Ready for review | A version is written and waiting for your approval. Until you approve it, this visitor type keeps seeing your original. |
| +12% / No clear gap / Early | A version is live, with a plain verdict against your original: how much better or worse it converts, “no clear gap yet”, or “early” while there is too little data to compare. |
| Improving… | A version is reliably beating your original, so an improved variation is being written to test against it. The current version keeps serving throughout. |
| Failed | Writing didn’t succeed — for example, the draft failed one of the checks below. Open the square to see why and try again. |
Click any Original square to generate a version for that visitor type, or use Fill the rest to queue every visitor type still on the original. Fill the rest skips visitor types with negligible recent traffic rather than writing versions almost nobody would see.
Auto-fill and approvals
With auto-fill on, when a visitor of a type arrives at a section that has no version yet, SentientUI queues one automatically (the visitor's page never waits — they see your original). New projects start with auto-fill on and approvals on: every version waits on the Review page until you approve it, and nothing written reaches your site before that. Untick “Require my approval before new versions go live” on Review and new versions go live without review — the caption under the Auto-fill switch always says which applies. Every version written, automatically or by you, counts against your plan's monthly writing allowance (Free includes 5 a month).
What the brand lock refuses
Every generated version is validated before it can serve — failed output is stored as rejected with the reason (the square reads “Failed — see why & retry”), never patched into something servable. The rules:
Never free-form HTML. Versions are built only from the closed set of building blocks, with every style choice an enumerated token — no arbitrary markup, CSS, or scripts. No invented offers. A version may re-emphasize prices, claims, and deadlines that already exist on your page — it may never mint a discount, fake urgency, or invent social proof. Links stay on your own domain. Forms stay small and safe: at most 5 labeled fields, one form per version, no password/file/hidden inputs, and the submit goal must be a real goal of your project.
“Why this exists” and “how it's doing”
Every version stores a plain-language rationale — why it was written, and from what — and reports its performance against your original in plain language, from the same card where you can pin it (“Always show this to…”) or regenerate it. A holdout slice of traffic always stays on your original, so “doing better than your original” is measured against your real page, not against a moving target.
get_cell_matrix, get_cell_detail, generate_cell, list_cell_reviews, and review_cell read and operate exactly what the dashboard shows. See the MCP server section below.Components vs full pages
<Adaptive> works at any granularity — a button, a hero section, or an entire page layout. However, the right tool depends on what you are testing.
Use <Adaptive> for isolated components
This is the recommended pattern. Wrap a CTA, pricing block, banner, or any self-contained piece of UI. The component adds a wrapper <div> around its content, which is fine for most layouts and enables automatic impression tracking, goal wiring, and the HTML preview in the dashboard.
<Adaptive
id="hero_cta"
goal="signup_click"
variants={{
control: <button>Start free trial</button>,
variant_a: <button>Get instant access →</button>,
}}
/>Use useAdaptive for full-page or route-level tests
When you want to test entire page layouts, the wrapper <div> that <Adaptive> renders can break your root CSS (flex/grid direct children, body margin, etc.). For those cases, use the useAdaptive hook — you branch your own JSX and spread bind on the page's existing root element, so there is no extra wrapper, and impressions are still recorded for the variant actually served. (useAssignment is deprecated: it selects a variant but records nothing.)
import { useAdaptive } from '@sentientui/react';
function LandingPage() {
const { value: Layout, bind } = useAdaptive('landing_layout', {
variants: { control: StackedLayout, sidebar: SidebarLayout }, // first key = baseline
// Scope the goal to the one element that means "converted". A string goal
// here would listen for clicks on ANY button or link inside the page.
goal: { type: 'click', selector: '[data-cta="signup"]' },
});
return (
<main {...bind}>
<Layout /> {/* renders <button data-cta="signup">…</button> somewhere */}
</main>
);
}goal on a page-sized binding. A string goal like goal="signup" is shorthand for "a click on any button or link inside the bound element" — fine for a single CTA, wrong for a page, where a nav link or a cookie banner would count as the conversion. Pass a selector, or use scroll_depth / form_submit, so only the real outcome rewards the variant.Conversions that finish outside the bound element — an account created after a server round trip, a thank-you page after a redirect — are fired explicitly, and still credited to the served layout: call the fireGoal that useAdaptive returns (or useAdaptiveGoal('landing_layout') from a child), or mark the destination with usePageGoal(name, { componentId: 'landing_layout' }). See the full-page recipe below.
Goal types
The goal prop defines what the optimizer treats as a successful outcome. When the goal fires, the currently shown variant receives a score of 1.0 and the optimizer updates its weights. Each goal fires at most once per variant mount — a second click on the same variant does not double-count.
goal="signup_click" reports under signup_click and can be promoted to a primary goal. goal={{ type: 'click' }} reports under the bare type click, so every inline click goal on the project collapses into one row named click and no goal definition is created for it. Prefer a named string; reach for an object when you need a selector, a threshold or a composite, and expect the generic name.Your goals, declared in code
useGoal(name) declares a goal where it happens and returns the function that records it. The goal shows up on the Goals page as soon as a page using it loads — at an honest 0, before anyone has completed it. Add { primary: true } to make it your main goal: every component that doesn't name a goal of its own learns from it, and your results are measured on it. A goal named on a component — <Adaptive goal="contact_click"> — is declared the same way, as an ordinary goal (@sentientui/react 0.44.2 and later).
'use client';
import { useGoal } from '@sentientui/react';
export function SignupForm() {
const signup = useGoal('signup', { primary: true });
return <form onSubmit={() => signup()}>…</form>;
}
// any other goal — tracked and compared, not the main one:
const pricing = useGoal('viewed_pricing');
// a purchase, with its value, credited to the hero version that was showing:
const purchase = useGoal('purchase', { componentId: 'hero_cta' });
purchase({ value: order.total, externalId: order.id });trackServerGoal.Declare your goal ids once and every goal name the SDK takes autocompletes and rejects typos — a misspelled goal otherwise just records a goal of its own:
// sentient.d.ts
declare module '@sentientui/react' {
interface Register { goal: 'signup' | 'viewed_pricing' | 'purchase' }
}Click — string shorthand
<Adaptive id="cta" goal="signup_click" variants={...} />
// Any click on a <button>, <a>, or role="button" element inside
// the variant fires the goal. The string is recorded as the goal
// label in your analytics. Use any descriptive name.Click — explicit object
<Adaptive
id="cta"
goal={{ type: 'click' }}
variants={...}
/>
// Identical DETECTION to the string shorthand — but not identical
// reporting: this form has no name, so it is recorded as the goal
// "click" rather than one of your own. Use the string unless you
// need a selector.Scroll depth
<Adaptive
id="banner"
goal={{ type: 'scroll_depth', threshold: 0.8 }}
variants={...}
/>
// Fires when at least 80% of the component is visible in the
// viewport. Uses IntersectionObserver — no scroll listeners.
//
// threshold: number 0–1
// 0.5 = half visible
// 1.0 = fully visible (the component has been completely read)
//
// Useful for banners, feature sections, and content you want
// visitors to actually see before counting a conversion.Form submit
<Adaptive
id="signup_form"
goal={{ type: 'form_submit' }}
variants={{
control: <SignupFormA />,
short: <SignupFormB />,
}}
/>
// Fires when a <form> element inside the variant fires a submit
// event — whether triggered by a button click, keyboard Enter, or
// programmatic form.submit(). Fires at most once per variant mount.
//
// Use this instead of goal="click" when your variant contains a form,
// because a click goal only triggers on <button> and <a> elements
// and misses keyboard submissions.Composite — all sub-goals must fire
<Adaptive
id="feature_section"
goal={{
type: 'composite',
all: [
{ type: 'scroll_depth', threshold: 0.8 },
{ type: 'click' },
],
}}
variants={...}
/>
// Both sub-goals must fire (in any order) before the reward is
// recorded. Useful for "read AND clicked" patterns — ensures the
// variant earned the conversion rather than getting lucky clicks
// from visitors who never saw the content.
//
// 'all' accepts click, scroll_depth, and form_submit sub-goals.Composite — read the copy, then submit
<Adaptive
id="pricing_block"
goal={{
type: 'composite',
all: [
{ type: 'scroll_depth', threshold: 0.75 },
{ type: 'form_submit' },
],
}}
variants={{
monthly_first: <PricingWithMonthlyDefault />,
annual_first: <PricingWithAnnualDefault />,
}}
/>
// Reward fires only when the visitor scrolled through most of the
// pricing table AND submitted the trial form — not on accidental
// clicks from visitors who never read the plans.Step credit — funnels in code
weighted_composite is a funnel written in code: its steps become a funnel named after the component (checkout-flow-steps below, or the id you pass as funnel), shown on Goals → Funnels like any other. A visit earns the credit of the furthest step it reached — not the sum of the steps — and finishing always earns full credit. A visitor who reads the pricing section (0.2) but never signs up still generates signal, so the optimizer has something to learn from long before full completions add up.
<Adaptive
id="checkout-flow"
variants={{ a: <CheckoutA />, b: <CheckoutB /> }}
goal={{
type: 'weighted_composite',
steps: [
{ goal: { type: 'scroll_depth', threshold: 0.5 }, name: 'viewed_pricing', weight: 0.2 },
{ goal: { type: 'click' }, name: 'clicked_cta', weight: 0.4 },
{ goal: { type: 'form_submit' }, name: 'signed_up', weight: 1.0 },
],
}}
/>
// Each step fires at most once per mount, and credit doesn't need them in order:
// a visit that only clicks the CTA earns 0.4. Reaching every step earns 1, not 1.6.
// The funnel orders steps by weight, so the highest-weight step is the
// completion — list them in any order.Weighted composite — onboarding wizard in one component
<Adaptive
id="onboarding_wizard"
variants={{ steps_sidebar: <WizardSidebar />, steps_top: <WizardTopNav /> }}
goal={{
type: 'weighted_composite',
steps: [
{ goal: { type: 'click' }, name: 'started_wizard', weight: 0.15 },
{ goal: { type: 'scroll_depth', threshold: 0.6 }, name: 'reached_step_2', weight: 0.45 },
{ goal: { type: 'form_submit' }, name: 'workspace_ready', weight: 1.0 },
],
}}
/>
// Steps fire as the visitor progresses. Reaching step 2 earns 0.45
// before the final form submit — useful when full completion is
// under ~5% of sessions.Use weighted_composite whenever full-funnel completion is rare enough that the optimizer would take weeks to distinguish good variants from bad ones. Use composite (all-or-nothing) when you specifically want the optimizer to score only the variant that completed the full flow. For a journey that spans pages, build the funnel on Goals → Funnels (or ask the goal chat) and put funnel="<id>" on each component that serves it.
Custom goals
The built-in goal types cover interactions inside a single <Adaptive> boundary. For conversions that happen elsewhere — after navigation, in an API route, or on a thank-you page — you have two imperative options. Use useAdaptiveGoal(componentId) (or client.componentGoal()) when the conversion should be credited to a variant — it appears in the per-variant conversion funnel and resolves the served variant for you. Use client.goal() for session-level funnel steps that aren't tied to one component.
For the common case — a conversion that is simply reaching a page (pricing viewed, signup form reached, checkout opened) — use usePageGoal(name, opts?) rather than wiring useAdaptiveGoal into an effect yourself. It records the arrival once (an effect without a latch fires again on every remount, and twice in React's development double-invoke), and it holds the goal until the SDK is running, so a consent gate that opens after the page mounts doesn't lose it. Pass componentId to credit the variant that sent the visitor there; omit it for a session-level step. Prefer it over a click goal on the link: arrival survives the navigation and also counts visitors who arrived from the nav, search or a shared link.
import { usePageGoal } from '@sentientui/react';
export default function PricingPage() {
usePageGoal('pricing_view', { componentId: 'hero_cta' });
return <PricingTable />;
}import { useAdaptiveGoal, useSentient } from '@sentientui/react';
function CheckoutSuccessPage() {
const client = useSentient();
// Resolves the served variant for 'hero_cta' — no variantId/projectId to pass.
const fireHeroGoal = useAdaptiveGoal('hero_cta');
useEffect(() => {
// Bandit reward + per-variant CVR: credit the hero CTA variant this
// session was served (render <Adaptive id="hero_cta"> earlier so it's assigned).
fireHeroGoal('checkout_complete', { reward: 1, metadata: { plan: 'pro' } });
// Optional: also record a session-level funnel step for cross-page Goals analytics.
client?.goal('checkout_complete', { metadata: { plan: 'pro' }, weight: 1, stepIndex: 2 });
}, [client, fireHeroGoal]);
return <ThankYouMessage />;
}useAdaptiveGoal(componentId) returns a fireGoal(goalType, opts?) callback — the equivalent outside React is client.componentGoal(componentId, goalType, opts?). Both emit a goal_achieved event attributed to the served variant (the same signal <Adaptive goal> fires automatically), so you never hand-thread a variantId. client.goal(name, { metadata?, weight?, stepIndex?, value? }) is separate: it POSTs a session-level goal to /v1/goals for funnel charts. For cross-page funnels, define the funnel once (Goals → Funnels, the goal chat, or a funnel prop) and call client.goal(stepName) at each step — step credit comes from the funnel, so a funnel step needs no weight or stepIndex. (The older positional form, client.goal(name, metadata, weight, stepIndex), still works.)
Pass { once: true } as fireGoal's opts when the conversion is a state rather than a repeatable action — e.g. "reached step 3". It records at most once per mounted component, so an effect that re-runs (a remount, React's development double-invoke) never double-counts. Omit it for genuine repeat actions, where each occurrence — each "add to cart" click — is its own conversion.
Goal recipes
End-to-end patterns that combine declarative goal props with imperative useAdaptiveGoal() / client.goal() calls. Copy and adapt to your routes.
Recipe: landing hero → pricing → purchase (cross-page funnel)
The hero uses a simple click goal. Intermediate steps fire on later pages. The thank-you page closes the loop for analytics and optimizer credit.
// app/page.tsx — hero variant test
<Adaptive id="hero_cta" goal="start_trial_click" variants={{ ... }} />
// app/pricing/page.tsx — record mid-funnel intent
'use client';
import { usePageGoal } from '@sentientui/react';
export default function PricingPage() {
// Fires once on arrival, credited to the hero variant that sent them here.
usePageGoal('viewed_pricing', {
componentId: 'hero_cta',
reward: 0.25,
metadata: { source: 'nav' },
});
return <PricingTable />;
}
// app/checkout/success/page.tsx — terminal step + bandit reward
'use client';
import { useEffect } from 'react';
import { useAdaptiveGoal, useSentient } from '@sentientui/react';
export default function SuccessPage() {
const client = useSentient();
// Resolves the hero variant this visitor was served — on any device or
// traffic source — so there is no variantId or segment to pass.
const fireHeroGoal = useAdaptiveGoal('hero_cta');
useEffect(() => {
fireHeroGoal('purchase_complete', { once: true });
// Session-level funnel step for cross-page Goals analytics.
client?.goal('purchase_complete', { weight: 1, stepIndex: 2 });
}, [client, fireHeroGoal]);
return <p>Thanks for your order.</p>;
}Recipe: Stripe webhook → server-side goal
Payment providers confirm on the server. Forward the session ID from checkout metadata and post the goal from your webhook handler with a server key (sk_) — no browser and no Origin header required.
// app/api/webhooks/stripe/route.ts
export async function POST(req: Request) {
const event = await stripe.webhooks.constructEvent(/* ... */);
if (event.type !== 'checkout.session.completed') {
return Response.json({ received: true });
}
const checkout = event.data.object;
const sessionId = checkout.metadata?.sentient_session_id;
if (!sessionId) return Response.json({ received: true });
await fetch('https://api.sentient-ui.com/v1/goals', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
Authorization: `Bearer ${process.env.SENTIENT_SERVER_KEY}`, // sk_… — never ship it to the browser
},
body: JSON.stringify({
sessionId,
goalId: crypto.randomUUID(), // required: dedupes retries of this request
name: 'stripe_checkout_complete',
externalId: checkout.id, // a Stripe redelivery is recorded once
metadata: { amount: checkout.amount_total },
}),
});
return Response.json({ received: true });
}
// When creating the Stripe Checkout session, stash the Sentient session id
// (the SDK's _snt_uid_… cookie):
// import { cookies } from 'next/headers';
// import { readSessionCookie } from '@sentientui/react/server';
// metadata: { sentient_session_id: readSessionCookie(await cookies(), process.env.NEXT_PUBLIC_SENTIENT_API_KEY) }Record a conversion from your server
Some conversions happen where the browser can't see them: a payment confirmed by a webhook, an order saved by a server action. trackServerGoal records one with your secret key (sk_, server-only). When the visitor's own request is the one running, read their session from the cookie:
import { cookies } from 'next/headers';
import { readSessionCookie, trackServerGoal } from '@sentientui/react/server';
const sessionId = readSessionCookie(await cookies(), process.env.NEXT_PUBLIC_SENTIENT_API_KEY!);
await trackServerGoal({
serverKey: process.env.SENTIENT_SECRET_KEY!,
sessionId,
name: 'purchase',
dedupeKey: order.id, // your own id for this conversion
value: order.total,
currency: 'USD',
});When the confirmation arrives later (Stripe, Clerk, a queue), there is no cookie. Read client.getVisitorId() in the browser, send it along with the checkout or sign-up (for example in its metadata), then pass it as sessionId from your webhook handler. It is null until the visitor has agreed to tracking, so nothing is saved for people who haven't.
Simpler still, when your backend knows the user: tell SentientUI who is signed in, then pass the same id as userId. SentientUI credits that user's most recent visit, so the backend never handles a visitor id at all. It needs the secret key, and returns 'skipped_no_visitor' when no visit carries that user id yet.
On Next.js, pass the signed-in user to the root: <AdaptiveRoot userId={user?.id} …>. It signs the id on your server with SENTIENT_SECRET_KEY, so a visitor can't claim to be someone else, and nothing new needs configuring. Elsewhere, compute await signUserId(user.id, process.env.SENTIENT_SECRET_KEY) (from @sentientui/core/server) on your server and call client.identify(user.id, { userHash }) in the browser. Once a project sends one signed identify, server goals by userId only reach signed visits.
await trackServerGoal({
serverKey: process.env.SENTIENT_SECRET_KEY!,
userId: user.id, // the id you passed to identify()
name: 'activated',
dedupeKey: user.id, // activation counts once per user
});Your marketing site and your app can be on different subdomains (example.com and app.example.com): with the same project key on both, the visitor cookie is shared across your domain automatically, so a journey that starts on the landing page and finishes in the app — or in its backend — is one visitor and one funnel. Add both under Settings → Allowed domains. Every subdomain of your domain is trusted with that cookie; if one serves content you don't control, pass cookieDomain={false} (or a narrower domain) to the provider.
Recipe: landing page → sign-up in your app → activation
One funnel from the first visit on your marketing site to an event only your backend sees:
- Use the same publishable key on both sites (
example.comandapp.example.com) and add both under Settings → Allowed domains. The visitor cookie is shared automatically. - In the app's root layout, pass the signed-in user:
<AdaptiveRoot userId={user?.id} …>, withSENTIENT_SECRET_KEYset on the server. - From your backend, when the user activates:
trackServerGoal({ serverKey, userId: user.id, name: 'activated', dedupeKey: user.id }). - Build the funnel on Goals → Funnels (or ask the goal chat):
pricing_view → signed_up → activated, and putfunnel="<id>"on the landing-page components it should optimize.
The call returns 'recorded', 'skipped_no_visitor' or 'failed' and never throws. Sending the same name and dedupeKey for the same visitor again, such as when a webhook is redelivered, counts once. The id is scoped to the visitor's session, so another site using the same order number never collides with yours.
Recipe: full-page layout test with manual goals
When useAdaptive drives an entire page, declare only the in-page signal you trust and fire the real conversion at the exact business-logic boundary — signup handler, modal confirm, etc. Both are credited to the layout the visitor was served, never to whatever they happened to click.
import { useAdaptive } from '@sentientui/react';
function LandingPage() {
const { value: Layout, bind, fireGoal } = useAdaptive('landing_layout', {
variants: { control: ClassicLayout, sidebar_nav: SidebarLayout },
// Partial credit for intent, scoped to the signup button only — clicks on
// the nav, footer or pricing toggle reward nothing.
goal: {
type: 'weighted_composite',
steps: [
{ goal: { type: 'click', selector: '[data-cta="signup"]' }, name: 'signup_click', weight: 0.2 },
],
},
});
async function handleSignup(data: FormData) {
const ok = await createAccount(data);
if (!ok) return;
// Full credit, only once the account exists. Attributed to the served
// layout variant (no variantId to thread through) and recorded in the
// Goals tab. A forced ?sentient_variant= preview records nothing.
fireGoal('account_created');
}
return (
<div {...bind}>
<Layout onSignup={handleSignup} />
</div>
);
}If signup ends on another route instead, drop the handler and put usePageGoal('account_created', { componentId: 'landing_layout' }) on the welcome page: the served variant is read from the assignment cache, so the credit survives the navigation. Credit from different goals on one variant adds up but is capped at one per visit, so a visitor who clicks and then signs up counts once, not 1.2 times.
Recipe: "quality engagement" composite on a feature block
<Adaptive
id="feature_comparison"
goal={{
type: 'composite',
all: [
{ type: 'scroll_depth', threshold: 0.9 },
{ type: 'click' },
],
}}
variants={{
table: <ComparisonTable />,
cards: <ComparisonCards />,
}}
/>
// The bandit only rewards variants where visitors actually read
// the comparison (90% visible) and then clicked a CTA — filtering
// out bounce clicks from skimmers.Layout optimization
Add a sections prop to <AdaptiveRoot> to enable persona-aware section ordering. Instead of individual /v1/assign calls per component, a single POST /v1/decide request returns the optimal section sequence and all component assignments together. The order is locked per session so the page layout is stable across navigations.
// app/layout.tsx
import { AdaptiveRoot } from '@sentientui/react/next';
export default function RootLayout({ children }) {
return (
<html lang="en">
<body>
<AdaptiveRoot
sections={['hero', 'pricing', 'features', 'social_proof']}
apiKey={process.env.NEXT_PUBLIC_SENTIENT_API_KEY!}
>
{children}
</AdaptiveRoot>
</body>
</html>
);
}The sections array defines the default order — what visitors see before their persona is determined, and the fallback when confidence is below threshold (0.3). Always pass this same array as the fallback in your page component.
useLayoutOrder hook
Read the resolved section order on the client. Returns the SSR-preloaded order on first render with no layout shift, or null when sections are not configured or the visitor's persona confidence is below threshold. Always fall back to the default order.
import { useLayoutOrder } from '@sentientui/react';
function Page() {
const order = useLayoutOrder();
// ['pricing', 'hero', 'features', 'social_proof'] | null
const sections: Record<string, React.ReactNode> = {
hero: <HeroSection />,
pricing: <PricingSection />,
features: <FeaturesSection />,
social_proof: <SocialProofSection />,
};
const defaultOrder = ['hero', 'pricing', 'features', 'social_proof'];
return (
<main>
{(order ?? defaultOrder).map((id) => (
<React.Fragment key={id}>{sections[id]}</React.Fragment>
))}
</main>
);
}useLayoutOrder() is exported from @sentientui/react. It works with both AdaptiveRoot (App Router) and AdaptiveProvider (client-only), but SSR preloading — zero layout shift on first paint — requires AdaptiveRoot.Shadow mode
Enable shadow mode from the project settings before going live. The API runs the full personalization algorithm and logs the order it would have served, but always delivers the default order to visitors. Review the per-persona section rankings in Layouts, then click Go live to start serving personalized layouts — it unlocks after 50 shadow decisions, so the rankings rest on real data.
The Layout tab shows decisions and average score per layout order per audience. A higher average score means visitors in that audience converted better under that section sequence.
Note: section ordering is only tested where your traffic can support it. A daily check works out how long a conclusive layout test would take on your traffic; while that is more than a year, layout testing pauses and the page is served in the order you wrote it — the Findings report says so, with the arithmetic. Variants are still assigned and learned from day one using device and traffic-source segmentation either way.
Telling us what a section is
Sections are classified from their content, so most need nothing beyond a data-sentient-id. A band with little signal-bearing copy — an “About us” block, a contact form — reads as generic, and a generic section is ordered the same for every persona. Declare only the ones the classifier gets wrong with sectionTypes, keyed by data-sentient-id. Any section with a data-sentient-id can appear, reorderable or not. Also accepted by AdaptiveProvider.
<AdaptiveRoot
sections={['hero', 'about', 'pricing', 'contact']}
sectionTypes={{ about: 'trust', contact: 'cta' }}
apiKey={process.env.NEXT_PUBLIC_SENTIENT_API_KEY!}
>
{children}
</AdaptiveRoot>Accepted types: pricing, hero, social_proof, cta, features, faq, comparison, trust, navigation, generic.
AdaptiveRoot — sections and sectionTypes props
sectionsstring[] (optional)AdaptiveRoot calls POST /v1/decide instead of individual /v1/assign calls, and useLayoutOrder() returns the persona-specific order on first render. IDs can be any string — they are used as keys in useLayoutOrder() and tracked in Layouts.sectionTypesPartial<Record<string, SemanticType>> (optional)data-sentient-id: { about: 'trust', contact: 'cta' }. Sections are classified from their content, so declare only the ones it gets wrong — a band with little signal-bearing copy reads generic and is ordered the same for every persona. Also accepted by AdaptiveProvider.Personas
Layout ordering and component assignment are driven by personas. Each visit is served as exactly one, in this order: a persona your app declares (the role you already know — admin, evaluator, member), a running retargeting group, a discovered audience the visitor confidently belongs to, a campaign or arrival type, else Everyone. A declared persona is ground truth from your own code, so it always wins and is served at full confidence from the first request.
Declaring a persona
Each project has a persona vocabulary — the set of audience keys it optimizes and reports on, managed in the dashboard under Audiences. Add the roles your app already distinguishes, then pass the session's role at init:
// Core SDK — declared once at init, every decision inherits it
init({ apiKey: 'pk_…', persona: 'admin' });
// React — prop on the provider/root (SSR paths forward it too)
<AdaptiveProvider apiKey="pk_…" persona={user.role}>
// Snippet — string, or a function evaluated at init
window.sentient = {
apiKey: 'pk_…',
persona: () => document.body.dataset.role ?? null,
};Keys are lowercase slugs (letters, digits, _, -, max 32 chars). Keep them low-cardinality role labels — never a user id or email. The vocabulary is capped at 12 personas because every persona divides each experiment cell's traffic: fewer personas learn faster.
A declared value that is not in the vocabulary is deliberately ignored — the session runs on the inferred path instead, and the dashboard surfaces the unrecognized value in Audiences so you can add it with one click. That means a typo never corrupts your data, and a persona you add starts working retroactively for new decisions without a code change.
The persona is fixed for the visit once declared (decisions are locked per visit — changing it mid-session is ignored). Renaming a persona in the dashboard keeps the old key working as an alias, so existing code and CSS hooks (html[data-sentient-persona=…]) stay intact.
Behaviour groups (reporting only)
A new project starts with no personas at all — every visitor resolves to unknown (Everyone), and Sentient tests and learns against all of your traffic pooled together from the first request. That is the honest starting point: we have not met your visitors yet, so we do not assert that they divide into groups.
A persona comes to exist one of a few ways. You declare one — a role your own app already knows, like admin or trial — and it is ground truth from the first request, no evidence gate. One is discovered: a segment proposed from where visitors spend attention, which only starts serving once it clears the interaction gate (see below). Or it comes from a campaign or retargeting group you run. Nothing else puts a visitor in a persona — we never guess someone into a declared one.
Separately, a nightly job groups visitors whose behavioral portraits look alike (urgency, attention, price focus, …) into behaviour groups — “Behaviour group 2: ready to act quickly”. They are reporting only: nothing is served to a behaviour group, it never becomes a persona, and it is never shown under one of your personas' names. A visitor who merely behaves like your admins is not an admin. The job runs only for a project that declares personas; projects without them see device/source-based variant learning from the start.
Until 2026-09-13 new projects were seeded with four generic behavioral personas. They were removed: a taxonomy shipped in the box is a claim about your visitors made before seeing any of them, and on real traffic almost every session landed in unknown anyway.
In the dashboard, Audiences shows the behaviour groups and their profiles, and who was served as which persona.
Discovered audiences
Beyond the personas you declare, SentientUI proposes discovered audiences: a weekly job clusters sessions by where they actually spend attention (share of dwell per section type, with device and traffic-source context) and names the segments from that behavior — “pricing-first mobile visitors”, not personality adjectives. The number of segments comes from your data; a small site legitimately resolves to two.
Candidates appear read-only under Audiences and change nothing about serving. Each segment must first earn it by showing that a different version wins for that segment than for everyone else — not merely that it converts better or worse overall, which no amount of separate serving can act on. That is judged with the same multiplicity-corrected machinery as the variants page. Only when every segment passes can you explicitly promote the set to serving; promotion retires the previous vocabulary (keys you map keep resolving as aliases, so CSS hooks survive), and you can roll back at any time — nothing is deleted.
identify() user id). Treat those identifiers as personal data where GDPR/ePrivacy apply — gate with consent. See the Privacy page for the inventory.Cross-session identity
By default, each browser session is anonymous. Call client.identify(userId) once your user is authenticated to link their behavioral portrait to a stable identity. Future sessions from the same user ID — on any device — resume from the same portrait.
import { useSentient } from '@sentientui/react';
function App() {
const client = useSentient();
const { user } = useAuth(); // your auth provider
useEffect(() => {
if (user?.id) {
// Links this browser session to the user's portrait.
// Safe to call on every mount — no-ops if already identified.
client?.identify(user.id);
}
}, [user?.id, client]);
return <YourApp />;
}Identified visitor profiles are more reliable — the optimizer has more signal per user, audience grouping is more accurate, and the cross-session continuity means returning visitors see consistent variants immediately without a re-exploration period. The userId you pass is stored as provided (for cross-session linking) and is not shown in the dashboard visitor UI.
identify() after the user has authenticated — not on every render. Calling it with different IDs for the same session will create separate portrait entries. For guest-to-authenticated transitions, the anonymous session portrait is carried forward automatically when identify() is first called.Excluding your team and test sites
Visits marked internal still see your versions — so you can check them on staging — but never count in any report (People, conversions, the shares on Audiences, funnels) and never teach the optimizer. Reports list them as Your team / test sites. Set it up in the dashboard under Settings → Internal traffic, four ways:
- Internal sites — switch on any allowed domain (staging, preview,
localhost) and every visit from it is internal. Only allowed domains can be chosen. - Team emails & domains — add
@example.comfor a whole team orname@example.comfor one person. They match visitors your site identifies with their email (below). - Browser link — open
https://your-site/?sentient_internal=<token>once in any browser you test from;?sentient_internal=offstops it. Rotating the link un-marks every browser. - Code flag — where your code already knows the visitor is on your team:
// Next.js App Router (AdaptiveProvider takes the same prop)
<AdaptiveRoot
apiKey={process.env.NEXT_PUBLIC_SENTIENT_API_KEY!}
internal={user?.email?.endsWith('@example.com') ?? false} // the email never leaves your site
>
// @sentientui/core
init({ apiKey: 'pk_…', internal: true });
// Script tag — a boolean, or a function read once at start-up
window.sentient = { apiKey: 'pk_…', internal: () => window.myApp?.user?.isStaff === true };For Team emails & domains, identify signed-in visitors with their email. The SDK sends a SHA-256 of the trimmed, lowercased address and its domain — never the address itself — and exact rules are stored as the same hash and shown masked:
const client = useSentient(); // or the client from init()
client?.identify(user.id, { email: user.email });
window.SentientSnippet.identify(user.id, { email: user.email }); // script tagContext types
The context prop is deprecated and unused — nothing in the SDK or API reads it. The project's type is set in the dashboard. Existing code that passes it keeps working; new code can omit it.
useAssignment hook
Deprecated — use useAdaptive (Rung 2 in the adaptive ladder), which selects the variant and wires impressions and goals; useAssignment only selects and is kept for backward compatibility.
SSR — Pages Router
For Next.js Pages Router or any custom SSR setup, use loadAdaptiveAssignments to fetch variant assignments on the server and pass them to the provider as initialAssignments. This helper picks the visitor's session cookie out of the cookies you pass it — you don't need to know its name.
// pages/_app.tsx
import { AdaptiveProvider } from '@sentientui/react';
export default function App({ Component, pageProps }) {
return (
<AdaptiveProvider
apiKey={process.env.NEXT_PUBLIC_SENTIENT_API_KEY}
initialAssignments={pageProps.initialAssignments}
ssrSessionId={pageProps.ssrSessionId}
>
<Component {...pageProps} />
</AdaptiveProvider>
);
}
// pages/index.tsx
import { loadAdaptiveAssignments } from '@sentientui/react/server';
export async function getServerSideProps({ req }) {
// Returns { assignments, sessionId } — pass the two fields separately.
const { assignments, sessionId } = await loadAdaptiveAssignments(
[
{ id: 'hero_cta', variantIds: ['control', 'variant_a'] },
{ id: 'pricing', variantIds: ['monthly', 'annual_first'] },
],
{
// Pages Router's req.cookies is a plain object; the helper reads cookies via get(name).
cookies: { get: (name) => (req.cookies[name] ? { value: req.cookies[name] } : undefined) },
apiKey: process.env.NEXT_PUBLIC_SENTIENT_API_KEY,
baseUrl: 'https://api.sentient-ui.com/v1',
origin: process.env.SENTIENT_APP_ORIGIN, // must be in allowed origins
},
);
return { props: { initialAssignments: assignments, ssrSessionId: sessionId } };
}Pass ssrSessionId too. Without it the browser starts a different session than the one the server assigned, so the preload silently does nothing and events attach to the wrong session.
Consent / GDPR
The SDK writes a first-party cookie (_snt_uid_<key>, 365 days) and sends events to the API. If your product requires explicit consent before setting cookies or tracking behaviour, pass consentFrom (your consent platform) or use the consent prop.
const [consented, setConsented] = useState(false);
<AdaptiveProvider
apiKey={process.env.NEXT_PUBLIC_SENTIENT_API_KEY}
consent={consented} // false = SDK not initialised
>
<CookieBanner onAccept={() => setConsented(true)} />
{children}
</AdaptiveProvider>When consent={false}: no SDK is initialised, no cookies are written, no events are sent, and <Adaptive> components without clientOnly render the first variant. Components with clientOnly={true} render nothing — the provider context is required for them to hydrate. Avoid clientOnly on any component that must remain visible to non-consenting visitors. Flipping consent to true initialises the SDK and begins tracking from that point.
Let the SDK watch your banner — consentFrom
Rather than flipping consent yourself, tell the SDK where your consent decision lives. It reads the source on mount, re-reads it whenever your event fires, and starts the moment it grants — no reload, and no glue code in your app. Keep whatever banner or CMP you already have.
<AdaptiveProvider
apiKey={process.env.NEXT_PUBLIC_SENTIENT_API_KEY!}
consentFrom={{ cookie: 'cookie_consent', value: 'accepted', event: 'consent-decided' }}
>
{children}
</AdaptiveProvider>Nothing is requested and no cookie is written until the source grants. The event's payload is never trusted — the source is re-read each time it fires — so a “declined” decision correctly leaves the SDK gated, and any CMP's event works.
Consent platforms: Cookiebot, OneTrust, CookieYes, TCF, Consent Mode, Shopify
If you use one of these, name it. The SDK reads that platform's own API, listens to its own events (accept and withdraw), and — with <AdaptiveRoot> — reads its own cookie on the server, so a visitor who already consented is rendered server-side with no layout shift.
consentFrom="cookiebot" // Statistics category
consentFrom="onetrust" // Performance group (C0002)
consentFrom="cookieyes" // Analytics category
consentFrom="tcf" // any IAB TCF v2.2 CMP (Usercentrics, Didomi, Quantcast…) — purposes 1, 5, 6 and 8
consentFrom="google-consent-mode" // analytics_storage — any CMP that drives Consent Mode v2
consentFrom="shopify" // Shopify's Customer Privacy API (snippet 0.32+ / react 0.37+; the snippet's default on Shopify)
// Choose a different category, group, purposes, region or vendor:
consentFrom={{ cmp: 'cookiebot', category: 'marketing' }}
consentFrom={{ cmp: 'onetrust', group: 'C0004' }}
consentFrom={{ cmp: 'tcf', purposes: [1, 8] }} // only if your CMP never offers 5 and 6
consentFrom={{ cmp: 'tcf', vendorId: 1234 }} // also require consent for a GVL vendor
consentFrom={{ cmp: 'google-consent-mode', region: 'ES' }} // resolve region-scoped defaultsTCF needs purposes 1, 5, 6 and 8 (storage, a content profile, personalised content, measurement; 8 may rest on legitimate interest). A CMP that doesn't offer 5 and 6 leaves every visitor gated. Configure those purposes in your CMP, or pass the ones you do collect as purposes. Google Consent Mode: without region, a region-scoped denial (region: ['DE', …]) keeps every visitor gated until an update — pass the visitor's country from your CDN to resolve it exactly.
A refusal deletes; a pending answer only waits. When the platform records a “no”, the SDK deletes the visitor ID and everything it stored, even if the no was given on a page without SentientUI. While the banner is loading, showing, or reopened by a visitor who already said yes, tracking pauses and the visitor keeps their ID. For your own cookie ({ cookie, value }), any other value counts as a refusal. With TCF only a refusal of purpose 1 (storage) deletes; a missing profiling purpose, or any answer under purposeOneTreatment, only keeps tracking off.
The same option works in the no-code snippet: window.sentient = { apiKey: '…', consentFrom: 'cookiebot' }. For any other platform, pass a predicate and its event (listened for on both window and document):
consentFrom={{
check: () => window.myCmp?.analytics === true,
event: 'mycmp:consent-changed',
// Optional: true once the visitor actually said no (not merely "not answered"),
// so a refusal also deletes what SentientUI stored. Without it, false only pauses.
refused: () => window.myCmp?.answered === true && window.myCmp.analytics === false,
}}The same watcher can gate your other consent-bound scripts (an ad pixel, a chat widget) on the same platform, so there is one source of truth. It is exported from @sentientui/react and available on the snippet's page API:
// React / Next.js
import { consentWatcher } from '@sentientui/react';
// No-code snippet
const consentWatcher = window.SentientSnippet.consentWatcher;
const marketing = consentWatcher({ cmp: 'cookiebot', category: 'marketing' });
const apply = () => { if (marketing.read() === true) loadPixel(); };
apply();
const stop = marketing.subscribe(apply); // fires on accept AND withdrawConsent with AdaptiveRoot (App Router)
<AdaptiveRoot> is a Server Component, so its consent prop cannot change without a server round trip. Do not hide it behind a conditional render and call router.refresh() on accept: the refresh has to complete before tracking starts, and visitors who accept and leave within a second or two are never counted. Render it unconditionally and pass consentFrom — that is the whole integration:
// app/page.tsx — Server Component
<AdaptiveRoot
apiKey={process.env.NEXT_PUBLIC_SENTIENT_API_KEY!}
consentFrom="cookiebot" // or a cookie: { cookie: 'cookie_consent', value: 'accepted', event: 'consent-decided' }
>
{children}
</AdaptiveRoot><AdaptiveRoot> is a Server Component, so it reads the consent cookie — yours, or the platform's own (Cookiebot, OneTrust, CookieYes, the TCF string) — from the request itself; you do not need to call cookies(). Google Consent Mode has no cookie, so with it the first paint is always gated and the browser decides. A visitor who has already consented therefore gets SSR variant assignment with zero layout shift on first paint, while everyone else is gated: no /v1/decide call and no session is minted until they accept in the browser.
<AdaptiveRoot> accepts only the cookie form: a check() function cannot cross the server→client boundary and would throw at render. For a JS-API CMP predicate, render <AdaptiveProvider> from a client component instead. Pass consent explicitly to override the cookie read entirely — the escape hatch for apps that track consent somewhere else.
_snt_uid_<key> cookie is a first-party visitor identifier (random UUID). Under GDPR / UK GDPR, online identifiers linked to behavioral history can still be personal data — gate the SDK with consent where required. See the Privacy page for the full data inventory, retention, and deletion endpoints.Do Not Track
The SDK honours the browser's Do Not Track (DNT) signal automatically — no integration required. When a visitor has DNT enabled, the SDK sets no cookies and sends no tracking data, behaving exactly as consent={false}. If preConsentBehavior is 'statistical_winner', it still serves the currently favoured variant (at least 100 visits; the baseline until then) via the read-only GET /v1/winner endpoint, which stores nothing about the visitor.
DNT is treated as a global opt-out: it overrides consent={true}, and grantConsent() will not re-enable tracking while it is active. DNT is not a substitute for your consent gate — most browsers no longer send it, so you still need the consent prop for EU / California visitors. To make your own consent management authoritative over the browser signal, set respectDoNotTrack={false}.
Forwarding to your own analytics
Pass onAssignment to the provider to be notified once per component the first time a variant is resolved in that session. Use this to send the assignment to Mixpanel, PostHog, Segment, or any other tool without wrapping every <Adaptive> manually.
<AdaptiveProvider
apiKey={process.env.NEXT_PUBLIC_SENTIENT_API_KEY}
onAssignment={(componentId, variantId) => {
// Called once per component per session when the variant is first resolved.
mixpanel.register({ [`variant_${componentId}`]: variantId });
posthog.capture('$feature_flag_called', { flag: componentId, variant: variantId });
analytics.track('Variant Assigned', { componentId, variantId });
}}
>
{children}
</AdaptiveProvider>onAssignment fires at most once per component ID per page load, even if the component re-renders. It does not fire for dev overrides — see Local overrides below.Local overrides (development)
Force a specific variant without touching the optimizer — useful for QA, visual testing, and building new variants before they go live.
URL parameter
Append sentient_variant=componentId:variantId to any page URL. Repeat for multiple components. Works in any environment where the URL is accessible.
# Force a single component
https://yourapp.com/pricing?sentient_variant=hero_cta:variant_a
# Force multiple components at once (repeat the param)
https://yourapp.com/pricing?sentient_variant=hero_cta:variant_a&sentient_variant=pricing:annual_firstGlobal object
Set window.__sentient_overrides before the SDK initialises. Useful for Storybook, Playwright, or any test harness where you control the page environment.
// In a test setup file or Storybook decorator:
window.__sentient_overrides = {
hero_cta: 'variant_a',
pricing: 'annual_first',
};Testing
Use @sentientui/react/testing to make adaptive UI deterministic in your own tests. By default it serves the control variant and default layout and sends no events, so existing tests keep passing; pass a scenario to force specifics.
Component tests (Jest / Vitest / RTL)
renderWithSentient renders under a test provider that never initialises a client — every <Adaptive> renders its control variant with zero network.
import { renderWithSentient } from '@sentientui/react/testing/react';
import { screen } from '@testing-library/react';
test('force a variant + layout', () => {
renderWithSentient(<MyPage />, {
variants: { hero_cta: 'accent' },
layout: ['pricing', 'hero'],
});
expect(screen.getByText('…')).toBeInTheDocument();
});Mock the API + assert goals
setupSentientServer is an MSW-backed mock backend. Control API responses (including injected errors), and assert which goals fired.
import { setupSentientServer } from '@sentientui/react/testing/node';
import { getSentientEvents, hasFiredGoal } from '@sentientui/react/testing';
const s = setupSentientServer();
afterAll(() => s.server.close());
test('signup goal fires', async () => {
s.use({ variants: { hero_cta: 'accent' }, api: { '/v1/assign': 'error' } });
// …render + trigger the interaction…
expect(hasFiredGoal(getSentientEvents(), 'signup')).toBe(true);
});E2E (Playwright / Cypress)
Use mockSentient to force variants/layout and stub the API in one call — it also captures posted events so you can assert goals.
import { mockSentient } from '@sentientui/react/testing';
test('checkout page, admin persona', async ({ page }) => {
const s = await mockSentient(page, {
variants: { hero_cta: 'accent' },
persona: 'admin',
});
await page.goto('/');
// …drive the flow…
expect(s.events().some((e) => e.goalType === 'signup')).toBe(true);
});Cypress is the same shape via mockSentientCypress(cy, scenario) in a beforeEach. Prefer mockSentient in CI — it intercepts the network, so it writes nothing at all.
The URL param (see Local overrides above) is handy for a quick local pin with no import, but it only forces the variant — a live client still creates a session and fires events:
await page.goto('/?sentient_variant=hero_cta:control&sentient_variant=pricing:monthly');navigator.webdriver) is excluded from the optimizer and from your billing quota — so the URL param won't skew results or exhaust your limit. It does still create automation session rows; mockSentient avoids even those. Never point a non-browser live client at the real API.Agent API
SentientUI serves structured variant content to AI agents — LLMs and orchestration frameworks that need to read the layout currently favoured for a visitor without rendering a browser. This is useful for AI-driven email generation, chat personalisation, agent workflows, and any non-browser surface that should respect the same decisions as your web UI.
Annotate variants with machine-readable content using the agentDataByVariant prop:
<Adaptive
id="pricing_cta"
goal="trial_started"
variants={{
control: <button>Start free trial</button>,
value_led: <button>Start free — no card required</button>,
}}
agentDataByVariant={{
control: { label: 'Start free trial', tone: 'neutral' },
value_led: { label: 'Start free — no card required', tone: 'reassuring' },
}}
/>Then call GET /v1/agent/layout from your AI system to get the resolved variant content for a specific visitor:
// From your backend or AI agent — use your server (sk_) key
const res = await fetch(
'https://api.sentient-ui.com/v1/agent/layout?visitor_id=<uuid>',
{ headers: { Authorization: 'Bearer sk_your_key' } }
);
const { persona, confidence, blocks } = await res.json();
// blocks: [{ block: 'pricing_cta', variant: 'value_led', content: { label: '...', tone: '...' }, evidence_state: '...' }]visitor_idquery param — UUID_snt_uid_… cookie. The API resolves the persona and returns the currently favoured variants for that visitor, each with itsevidence_state — favoured is not proven; check it before calling anything a winner. Pass user_id instead if you identified the visitor with client.identify().personastring | nulladmin), else a discovered group they confidently belong to. null when neither applies (they are Everyone) or the visitor isn't found. A visitor who only behaves like your admins is never reported as admin.confidencenumber | null1 for a declared persona, the group assignment's confidence for a discovered one. null when persona is null.blocksArray<{ block, variant, content, evidence_state }><Adaptive> component that has agent data defined. content is the agentDataByVariant entry for the currently favoured variant — or, for a component that combines variants with its original, the version the visitor named by visitor_id was served, falling back to the original's data.sk_), not public keys (pk_). Generate one in Project settings → API key → Server key — available on every plan, one key per project. Every call is logged — the all-time agent-call count appears above the list in Components.MCP server
@sentientui/mcp exposes your project data and management actions as tools to AI assistants via the Model Context Protocol — in IDEs (Claude Code, Cursor, VS Code, Codex) and in web/app assistants (claude.ai, ChatGPT). Ask “Are any variants paused?” or “What changed in conversion rate this week?” without leaving the assistant.
Connect by URL (recommended). No key to paste — you sign in with your SentientUI account. This is the only way to connect web/app assistants like claude.ai and ChatGPT.
https://api.sentient-ui.com/mcpIn claude.ai or ChatGPT, add a custom connector with that URL and sign in when prompted. In Claude Code: claude mcp add --transport http sentientui https://api.sentient-ui.com/mcp. For stdio-only clients such as Codex: npx mcp-remote https://api.sentient-ui.com/mcp.
Or run locally with a server key — for offline or programmatic use. The server key is the same sk_ key as the agent API — generate one in Project settings → API key → Server key (every plan; the key is scoped to that one project). Restart your IDE after saving.
// .mcp.json in your project root (Claude Code)
// ~/.cursor/mcp.json (Cursor)
{
"mcpServers": {
"sentientui": {
"command": "npx",
"args": ["-y", "@sentientui/mcp"],
"env": { "SENTIENTUI_API_KEY": "sk_your_key_here" }
}
}
}Read tools: list_projects, get_project_stats, list_components, get_variant_performance, get_variant_brief, get_test_brief, get_goal_funnel, list_goals, list_funnels, get_funnel_report, list_guardrail_events, get_persona_breakdown, get_stage_breakdown, get_known_people, get_main_funnel, get_page_groups, get_plan, get_test, get_page_elements, get_needs_you, get_layout_stats, get_insights, get_cell_matrix, get_cell_detail, list_cell_reviews, get_agent_traffic, get_traffic_breakdown, get_internal_traffic_rules, get_site_areas, get_agent_legibility, get_integration_guide, get_agent_access, list_campaigns, get_retargeting_report, get_audiences, get_site_styles, get_region_history. Write tools, which an assistant should confirm with you before calling: create_project, add_origin, define_goal, create_variant, update_variant, delete_variant_draft, pause_variant, resume_variant, retire_variant, restore_variant, refresh_insights, generate_cell, review_cell, manage_generation, manage_approvals, manage_tests, manage_goals, manage_campaigns, manage_settings. accept_insight, dismiss_insight and save_insight (inside manage_settings) are always allowed: the Project settings switch does not govern them.
The cell tools mirror the Who sees what grid: read which visitor type sees which version (with traffic share and auto-fill status), read one version's story — its stored rationale and a plain-language verdict vs your original — queue generation of a new version, and, when review mode is on, approve or reject it, exactly as the dashboard would.
npx @sentientui/mcp without setting SENTIENTUI_API_KEY — a read-only demo token is provisioned automatically with 10 calls/month. It points at an empty sandbox project, so it shows the tools rather than populated data.Run Sentient from your agent
Everything below can be done from an AI agent connected to the MCP server — Claude Code, Cursor, Codex, claude.ai or ChatGPT — without opening the dashboard. Ask in plain words; the agent picks the tools. It asks you before every change, and a project owner decides which kinds of change agents may make at all (Settings → Agent access; an agent can read the switches with get_agent_access but never flip them).
Three things stay in the dashboard on purpose, because a person has to be the one who does them:
- creating your account;
- connecting a GitHub repo (Settings → GitHub, for sites built from code; GitHub asks the repo owner to approve the app);
- the agent-access switches above.
1. Connect
claude mcp add --transport http sentientui https://api.sentient-ui.com/mcpSign in once when your assistant asks. Other assistants connect with the same URL — see MCP server.
2. Set up a project
“Create a SentientUI project for acme.com and install it in this repo.”
create_projectcreates it and returns the public key (pk_…) the site uses.add_originallows each domain the site runs on — production, and your staging or preview domains.get_integration_guidegives the agent the exact install for your framework, which it then writes into your code. On Next.js the root layout gets<AdaptiveProvider>;<AdaptiveRoot>belongs only on pages that need the chosen version in their first HTML, because it makes every page under it render on each request.get_project_statsconfirms events are arriving.
3. Say what success means
“Our main goal is a paid subscription. People go pricing → sign-up → subscribe.”
define_goalcreates each goal your site sends (a page visit, a click, a form,useGoalin the browser, ortrackServerGoalfrom your server). A step nothing sends never fills.manage_goals set_goal_rolewith{ role: "primary" }makes one of them the main goal — what every test and the Overview headline count.manage_goals update_funnelcreates or updates the journey, andset_main_funnelmakes it the main funnel. Its last step must be the main goal.get_page_groupssuggests named groups of your pages;manage_goals set_page_groupssaves them, each placed at a step of the funnel.- People who converted before you installed:
manage_settings import_known_peoplewith your own user ids. Never names, emails, phone numbers or addresses — they are refused. get_main_funnelshows the result: people at each step, and where they stop.
4. Get new versions written
“Write a new version of the pricing button for people coming from our spring campaign.”
get_cell_matrixshows which audience sees which version of each component.generate_cellasks for one new version (one audience, one component);manage_generation generate_allfills every empty square.- With approvals on, a finished version waits:
list_cell_reviews, thenreview_cellto approve or reject it. - Components written in your code:
get_variant_briefsays what to write next, from the evidence; the agent writes it in your code.create_variantadds a text-only version without code.
5. Send a change to your code
“Make the hero button say ‘Start free’ and send it to our developers.”
Connect your repo once (sites built from code; a person does this): Settings → GitHub → Install the GitHub app, pick your site's repo on GitHub, and GitHub brings you back to choose the project. If it does not (the app was already installed), paste the app's installation link in Settings → GitHub → Already installed?. The app can read and write code and pull requests, and read your checks; nothing else.
get_page_elementslists what Sentient found on your pages, each with an id. Pick one with visible text or an id: a whole form cannot be found in code, so pick its button.manage_generation open_prwith that id (and your goal) wraps it in<Adaptive>with your original first, checks the change compiles in an isolated sandbox, and opens a pull request — usually within ten minutes. The dashboard's Ask Sentient does the same with an Open PR button.get_needs_youfollows it, as its card on Needs you does: sent, checks passed, approved by a developer (a merge counts), and live once the change is seen on your site. Nothing merges without your developers.- At most five pull requests per project a day.
6. Test, keep, repeat
“What should we test next?” · “Start it with the shorter version.” · “Keep the winner.”
get_planshows what is being tested, what Sentient proposes next — each a place and a reason — and what was learned.manage_tests start_teststarts one with one or two versions. From then on that component's visitors are split evenly at random between what is live and the new versions, until the test ends by itself — usually in a few weeks, never more than eight.get_testfollows it. It never shows a percentage: each new version gets a status word (clearly ahead, clearly behind, not enough people yet, too early to tell).- A clear winner waits for you:
manage_approvals keep_winnermakes it what everyone outside the comparison group sees, ormanage_tests decline_winnerturns it down. Either way, Sentient goes back to choosing. manage_tests propose_test,skip_testandstop_testcover the rest.
7. See whether it is working
“Is Sentient helping?”
get_known_people→liftBeforeGateis the tested answer: people with Sentient against people on your original site.get_main_funnelfor the funnel,get_insightsfor what changed,get_needs_youfor anything waiting on you.
How it works
Each <Adaptive> component runs its own optimizer (Thompson sampling). The optimizer operates per segment — a combination of the visitor's device class and traffic source.
| Dimension | Values |
|---|---|
| Device class | mobile, tablet, desktop |
| Traffic source | direct, search, social, referral |
This means mobile visitors from search may end up favouring a different variant than desktop visitors arriving directly. The optimizer learns per segment — no manual cohort setup required. Favoured is not the same as proven: whether a version actually helped is decided by the holdout comparison below, not by how much traffic the optimizer gives it.
Assignment flow
1. Visitor arrives → session created (or resumed from cookie)
2. AdaptiveRoot (or the <Adaptive> itself, after mount) calls POST /v1/assign
→ API looks up segment weights for this (component, segment) pair
→ Thompson Sampling: sample Beta(alpha, beta) per variant, serve the argmax
→ returns variantId
3. Component renders the assigned variant
4. SDK sends a variant_assigned event (impression)
5. When the goal fires → SDK sends goal_achieved event
6. When the visit closes, the API credits the variant: alpha for a conversion,
beta for a visit without one (bot sessions are not counted)
7. Over time: uncertainty shrinks and traffic shifts toward the versions doing
better — the holdout comparison is what says whether they helpedHow we measure
The optimizer moving traffic is not evidence on its own — a version can be favoured and still not beat your original. These are the checks behind every lift number SentientUI shows:
- A held-out slice. Once a project has an adaptive component, 10% of visitors by default (you set the rate) always see your original, and stay in that group across visits. Lift is measured against them, not against the losing versions.
- A test that allows looking early. Lift significance uses an always-valid sequential test, so checking the result every day does not manufacture a win.
- People only. Sessions scored as bots or automated agents are kept out of conversion rates, learning and your bill.
- Guardrails. A version doing clearly worse than your original is paused automatically, and you are emailed.
- Refunds count. On revenue goals, a refunded order is taken back off the score instead of flattering the total.
- Check our work. The serving record logs what each visitor was shown and the odds it was shown with; download it as CSV and recompute the result in your own tools.
The learning progress bar in the dashboard tracks views toward a configurable target (default 500). Below that threshold the algorithm is still actively exploring. Past it, check the component's evidence against your control before promoting a winner manually — or let the optimizer keep converging on its own.
Events are batched in memory and flushed every 5 seconds, or immediately when the page becomes hidden. No data is lost on tab close — the SDK uses fetch with keepalive: true for unload-safe delivery.

