SentientUI

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 adapt

Without 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.

Not using React? The @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/react

You 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).

The key starts with 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_here
That's it. The SDK points to the SentientUI API automatically.

Setup — 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>
  );
}
Your pages stay static and cached. The provider reads nothing from the request, so Next.js keeps prerendering every route under it. Versions are chosen in the browser: a first visit shows your original, then the chosen version after one round trip; a return visit starts from the last version served.

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>
  );
}
Keep <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.
Only declare ids the wrapped pages actually render. A declared id is decided on every request <AdaptiveRoot> wraps, whether or not the component is on the page, and each of those counts as a view that can never convert.
AdaptiveRoot must be a Server Component. Do not add '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)
Code-variant <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)
Generated <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.
apiKeystring
Your pk_… 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)
Unused — the project's type is set in the dashboard. Safe to omit.
consentboolean (default: true)
Set to 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)
Honour the browser's Do Not Track signal. When enabled and the visitor has DNT on, the SDK sets no cookies and sends no tracking data — even if 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)
The origin of your app, e.g. 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)
DOM graph scanning — on by default. The SDK captures your page structure, auto-detects what each section is (pricing, hero, social proof, …), and syncs it to power audience profiles and the DOM Graph page. Loaded on demand so the base bundle stays lean. Pass false to turn it off.
captureAgentsboolean (default: true)
Log JS-less AI-assistant fetches (GPTBot, ChatGPT-User, Claude-User, PerplexityBot, …) to your agent analytics. Because <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)
Behavioral engagement capture — on by default. Records how long each page section is actually on screen and how far visitors scroll, which is what lets Sentient build audience profiles without any tagging. Never runs for a Do-Not-Track, Global Privacy Control, or consent-gated visitor. Pass false to turn it off.
noncestring
CSP nonce for the inline persona script (and the optional agent JSON-LD). Only needed if you run a strict Content-Security-Policy — pass the same nonce you set on the header, e.g. from Next.js middleware or headers(). 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.

  1. Install the app, open it in your Shopify admin, paste the project's pk_ and sk_ keys, and save. The purchase goal, checkout funnel and refund netting are set up on save.
  2. In Online Store → Themes → Customize → App embeds, switch SentientUI on and save the theme.
  3. 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.

Rule of thumb: to let SentientUI write versions for you, wrap the section in <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
Unique identifier for this section within your project. Must start with a letter or digit, then letters, digits, _ or -, up to 128 characters.
childrenReactNode
Your original content. Serves as-is whenever no version applies — holdout, unknown visitor types, no version yet, or any error.
goalstring | GoalConfig (optional)
Optional goal attached to the container (click, scroll depth, composite — see Goal types below). Form versions fire their own submit goal regardless.
onFormSubmit(values: Record<string, string>) => void (optional)
Receives the field values when a form version submits. Without it, this section is never offered forms, and a form version that somehow arrives is refused whole — the children render instead. Values go only to your handler; SentientUI never stores them.
classNamestring (optional)
Class for the wrapping <div>.
reportBaselineTextboolean (default: true)
Sends the region's rendered text on first registration so generated versions are grounded in what they replace. Set 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

idstring
Unique identifier for this component within your project. Use the same string everywhere this component appears. Must match the id in your AdaptiveRoot components list if you want SSR preloading.
variantsRecord<string, ReactNode>
A plain object mapping variant IDs to React content. Keys are your own strings — use anything descriptive (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 | GoalConfig
What counts as a conversion for this component. See Goal types below. Required.
funnelstring (optional)
Stable id of the funnel this component serves (e.g. 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)
When a passive micro-signal fires on this component, also record a named goal — e.g. map rage_click to confused_by_hero.
clientOnlyboolean (default: false)
When 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)
Machine-readable content per variant for AI agents — only the assigned variant's entry is sent. Read once at mount, so pass the final value on first render. A new or changed value is stored once visitors on a few different networks have reported it, so a forged request cannot rewrite it — expect it to reach agents after some real traffic, not on the first page view. See Agent API.
agentDataunknown (deprecated)
One value for whichever variant is served, stored the same way. Prefer agentDataByVariant.
Pass 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.

Without a 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:

RowWhat it means
EveryoneWhere most visitors sit, and where the work starts on day one. This row is live from your first visitor.
YoursA 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 checkedA pattern we think we can see forming in your traffic. It does not serve anyone and does not spend anything yet.
EarnedA group your traffic has proved: a different version genuinely wins for it, so it now gets its own versions.
StarterOlder 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 seeWhat it means
OriginalNo 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.
WaitingThis month’s writing allowance is used up. The version is queued and resumes automatically — the square says when.
Ready for reviewA version is written and waiting for your approval. Until you approve it, this visitor type keeps seeing your original.
+12% / No clear gap / EarlyA 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.
FailedWriting 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.

The same grid is available to AI assistants through the MCP server — 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>
  );
}
Be deliberate about the 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.

A string goal is the goal's name; an object config has none. 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 });
When a code change takes effect. The first main goal is set by the first page load that declares it — localhost included. After that, a different main goal from your code takes over once real visitors on a few different networks have loaded the new version, so nobody can change your main goal from their browser's console. Local, LAN, tunnel and preview-deploy hosts never change an existing one. If someone picks a different main goal in the dashboard, that sticks until your code names a new one. Mark one goal as primary; every change, from code or the dashboard, is in Settings → Activity. Conversions that happen on your server go through 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.

Not sure what to track? On Starter and above, enable Observation Mode (management API) to pause optimizer updates while the SDK collects behavioral signals for 500 sessions. After that, the Goals page surfaces "Suggested conversion moments". You confirm or dismiss each one; confirming one gives you a ready-to-copy snippet to wire it into your app. See pricing.

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:

  1. Use the same publishable key on both sites (example.com and app.example.com) and add both under Settings → Allowed domains. The visitor cookie is shared automatically.
  2. In the app's root layout, pass the signed-in user: <AdaptiveRoot userId={user?.id} …>, with SENTIENT_SECRET_KEY set on the server.
  3. From your backend, when the user activates: trackServerGoal({ serverKey, userId: user.id, name: 'activated', dedupeKey: user.id }).
  4. Build the funnel on Goals → Funnels (or ask the goal chat): pricing_view → signed_up → activated, and put funnel="<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)
Declare page section IDs in their default order. When provided, 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)
What each section is, keyed by 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.

Personas are derived from behavioral signals tied to a pseudonymous session id (and optional 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.

Call 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.com for a whole team or name@example.com for 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=off stops 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 tag
It applies from when you turn it on. Earlier visits can't be separated: before this setting existed we didn't record which site a visit came from. A visit marked internal after it already taught the optimizer (a late identify, a rule added later) drops out of every report straight away but is not un-learned. There is no report filter or IP rule; for full separation, give staging its own project and key.

Context 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.

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.

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.

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 defaults

TCF 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 withdraw

<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.

The _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_first

Global 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',
};
Overrides are client-only and log a console message in non-production environments so you can confirm which component is being overridden. Overrides bypass the optimizer entirely — no events are recorded and the variant weights are not affected.

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');
Automation traffic (E2E drivers set 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
The visitor's session ID from the _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 | null
The audience this visitor counts as — the same one Audiences counts them in: a persona your site declared for them (e.g. admin), 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 | null
How sure that is (0–1): 1 for a declared persona, the group assignment's confidence for a discovered one. null when persona is null.
blocksArray<{ block, variant, content, evidence_state }>
One entry per <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.
The agent layout endpoint uses server keys (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/mcp

In 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.

No account yet? Run 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/mcp

Sign 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_project creates it and returns the public key (pk_…) the site uses.
  • add_origin allows each domain the site runs on — production, and your staging or preview domains.
  • get_integration_guide gives 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_stats confirms events are arriving.

3. Say what success means

“Our main goal is a paid subscription. People go pricing → sign-up → subscribe.”

  • define_goal creates each goal your site sends (a page visit, a click, a form, useGoal in the browser, or trackServerGoal from your server). A step nothing sends never fills.
  • manage_goals set_goal_role with { role: "primary" } makes one of them the main goal — what every test and the Overview headline count.
  • manage_goals update_funnel creates or updates the journey, and set_main_funnel makes it the main funnel. Its last step must be the main goal.
  • get_page_groups suggests named groups of your pages; manage_goals set_page_groups saves them, each placed at a step of the funnel.
  • People who converted before you installed: manage_settings import_known_people with your own user ids. Never names, emails, phone numbers or addresses — they are refused.
  • get_main_funnel shows 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_matrix shows which audience sees which version of each component.
  • generate_cell asks for one new version (one audience, one component); manage_generation generate_all fills every empty square.
  • With approvals on, a finished version waits: list_cell_reviews, then review_cell to approve or reject it.
  • Components written in your code: get_variant_brief says what to write next, from the evidence; the agent writes it in your code. create_variant adds 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_elements lists 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_pr with 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_you follows 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_plan shows what is being tested, what Sentient proposes next — each a place and a reason — and what was learned.
  • manage_tests start_test starts 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_test follows 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_winner makes it what everyone outside the comparison group sees, or manage_tests decline_winner turns it down. Either way, Sentient goes back to choosing.
  • manage_tests propose_test, skip_test and stop_test cover the rest.

7. See whether it is working

“Is Sentient helping?”

  • get_known_people → liftBeforeGate is the tested answer: people with Sentient against people on your original site.
  • get_main_funnel for the funnel, get_insights for what changed, get_needs_you for 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.

DimensionValues
Device classmobile, tablet, desktop
Traffic sourcedirect, 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 helped

How 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.