@sentientui/react 0.41.0 → 0.42.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +36 -0
- package/dist/index.d.cts +74 -12
- package/dist/index.d.ts +74 -12
- package/dist/index.js +2 -2
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +2 -2
- package/dist/index.mjs.map +1 -1
- package/dist/testing/react.js +1 -1
- package/dist/testing/react.js.map +1 -1
- package/dist/testing/react.mjs +1 -1
- package/dist/testing/react.mjs.map +1 -1
- package/package.json +3 -3
- package/dist/server.d.cts +0 -116
- package/dist/server.d.ts +0 -116
package/README.md
CHANGED
|
@@ -310,6 +310,7 @@ One canonical path per situation — the others are for the cases these can't re
|
|
|
310
310
|
|
|
311
311
|
| You want to record… | Use | Credits |
|
|
312
312
|
|---|---|---|
|
|
313
|
+
| your main goal, or any conversion you record yourself (a signup, a purchase) | `useGoal(name, { primary?, componentId? })` | the session, or that component's version |
|
|
313
314
|
| a click, submit or scroll inside an adaptive region | the `goal` prop on `<Adaptive>` | the version that region showed |
|
|
314
315
|
| a visitor reaching a page or route (pricing, checkout) | `usePageGoal(name, { componentId? })` | that component's version, or the session |
|
|
315
316
|
| an event you fire yourself, tied to a region (a phone call, a custom widget) | `useAdaptiveGoal(componentId)` | the version that region showed |
|
|
@@ -537,6 +538,41 @@ The served variant is resolved from the SDK's assignment cache (the same one `<A
|
|
|
537
538
|
`opts.once` records the goal at most once per mounted component, however many times you call it — use it for conversions that are a *state* rather than an action ("reached step 3", an effect that may re-run). Leave it off for genuine repeat actions: each click of "add to cart" is its own conversion.
|
|
538
539
|
`opts` accepts `reward` (0–1, default 1) and `metadata`. This replaces hand-rolled helpers that call `client.track({ eventType: 'goal_achieved', componentId, variantId, … })` — you no longer need to pass or track the variant yourself.
|
|
539
540
|
|
|
541
|
+
### `useGoal(name, opts?)`
|
|
542
|
+
|
|
543
|
+
Declares a goal where it happens and returns the function that records it. Declaring is what makes the goal show up in the dashboard straight away — at an honest 0, before anyone has completed it.
|
|
544
|
+
|
|
545
|
+
```tsx
|
|
546
|
+
'use client';
|
|
547
|
+
import { useGoal } from '@sentientui/react';
|
|
548
|
+
|
|
549
|
+
export function SignupForm() {
|
|
550
|
+
const signup = useGoal('signup', { primary: true }); // your main goal
|
|
551
|
+
return <form onSubmit={() => signup()}>…</form>;
|
|
552
|
+
}
|
|
553
|
+
|
|
554
|
+
const purchase = useGoal('purchase', { componentId: 'hero_cta' });
|
|
555
|
+
purchase({ value: order.total, externalId: order.id, once: true });
|
|
556
|
+
```
|
|
557
|
+
|
|
558
|
+
- **`primary: true`** makes it the project's main goal: every component that doesn't name a goal of its own learns from it, and results are measured on it. Mark one goal; a second `primary` on the same page is ignored with a console warning.
|
|
559
|
+
- **When a change takes effect.** The first main goal is set by the first page load that declares it — localhost included. A *different* main goal from code takes over once real visitors on a few different networks have loaded the new version (the public key is in your page source, so one request can't change it). Local, LAN, tunnel and preview-deploy hosts never replace an existing main goal. A main goal picked in the dashboard sticks until your code names a different one. Every change is in the project's activity log.
|
|
560
|
+
- **`componentId`** also credits the version currently served for that component, like `useAdaptiveGoal`.
|
|
561
|
+
- The returned function takes the same per-conversion options as `fireGoal`: `value`, `currency`, `externalId`, `metadata`, `once`.
|
|
562
|
+
|
|
563
|
+
#### Typed goal names
|
|
564
|
+
|
|
565
|
+
Declare your goal ids once and every goal name the SDK takes — `useGoal`, `usePageGoal`, `useAdaptiveGoal`'s fire function, the `goal` prop — autocompletes and rejects typos. A misspelled goal isn't a runtime error: it quietly records a goal of its own, and a misspelled main goal reads 0% forever.
|
|
566
|
+
|
|
567
|
+
```ts
|
|
568
|
+
// anywhere in your app, e.g. sentient.d.ts
|
|
569
|
+
declare module '@sentientui/react' {
|
|
570
|
+
interface Register { goal: 'signup' | 'viewed_pricing' | 'purchase' }
|
|
571
|
+
}
|
|
572
|
+
```
|
|
573
|
+
|
|
574
|
+
Without it, any string works as before.
|
|
575
|
+
|
|
540
576
|
### `usePageGoal(goalName, opts?)`
|
|
541
577
|
|
|
542
578
|
Records a conversion **once, when a page or route is reached** — the funnel steps that are a destination rather than a click: landing on `/pricing`, reaching a signup form, opening checkout.
|
package/dist/index.d.cts
CHANGED
|
@@ -268,6 +268,28 @@ declare function useLayoutOrder(): string[] | null;
|
|
|
268
268
|
/** Internal: configured API base URL (devtools fetches /v1/explain against this, never a relative URL). */
|
|
269
269
|
declare function useAdaptiveApiBaseUrl(): string;
|
|
270
270
|
|
|
271
|
+
/**
|
|
272
|
+
* Your app's goal ids, for autocomplete and typo checks. Declare them once,
|
|
273
|
+
* anywhere in your app's TypeScript:
|
|
274
|
+
*
|
|
275
|
+
* declare module '@sentientui/react' {
|
|
276
|
+
* interface Register { goal: 'signup' | 'viewed_pricing' | 'purchase' }
|
|
277
|
+
* }
|
|
278
|
+
*
|
|
279
|
+
* Every goal name the SDK takes — `useGoal`, `usePageGoal`, the fire function
|
|
280
|
+
* from `useAdaptiveGoal`, the `goal` prop on `<Adaptive>` and the other
|
|
281
|
+
* components — then accepts only those. A misspelled goal is not an error at
|
|
282
|
+
* runtime: it records a goal of its own that never matches the one you meant,
|
|
283
|
+
* and a misspelled main goal reads 0% forever. Without the declaration every
|
|
284
|
+
* name is a plain string, as before.
|
|
285
|
+
*/
|
|
286
|
+
interface Register {
|
|
287
|
+
}
|
|
288
|
+
/** A goal id: the union declared on `Register['goal']`, else any string. */
|
|
289
|
+
type GoalName = Register extends {
|
|
290
|
+
goal: infer G extends string;
|
|
291
|
+
} ? G : string;
|
|
292
|
+
|
|
271
293
|
/**
|
|
272
294
|
* The element `<Adaptive>` renders around its content (audit S17: it was
|
|
273
295
|
* always a `<div>`, which is invalid inside a `<ul>`, a `<p>` or a table row
|
|
@@ -296,7 +318,7 @@ type CompositeGoal = {
|
|
|
296
318
|
};
|
|
297
319
|
type WeightedStep = {
|
|
298
320
|
goal: GoalConfig;
|
|
299
|
-
name:
|
|
321
|
+
name: GoalName;
|
|
300
322
|
weight: number;
|
|
301
323
|
};
|
|
302
324
|
type WeightedCompositeGoal = {
|
|
@@ -306,8 +328,8 @@ type WeightedCompositeGoal = {
|
|
|
306
328
|
type GoalConfig = ScrollDepthGoal | ClickGoal | FormSubmitGoal | CompositeGoal | WeightedCompositeGoal;
|
|
307
329
|
|
|
308
330
|
/** Maps a detected micro-signal to a named session goal (`client.goal`). */
|
|
309
|
-
type MicroSignalGoalConfig =
|
|
310
|
-
name:
|
|
331
|
+
type MicroSignalGoalConfig = GoalName | {
|
|
332
|
+
name: GoalName;
|
|
311
333
|
weight?: number;
|
|
312
334
|
stepIndex?: number;
|
|
313
335
|
};
|
|
@@ -326,7 +348,7 @@ type AdaptiveSlotProps = {
|
|
|
326
348
|
onFormSubmit?: (values: Record<string, string>) => void;
|
|
327
349
|
/** Optional goal attached to the container (click/scroll/composite), same
|
|
328
350
|
* shape as AdaptiveGroup's. Form arms fire their own submitGoal regardless. */
|
|
329
|
-
goal?:
|
|
351
|
+
goal?: GoalName | GoalConfig;
|
|
330
352
|
className?: string;
|
|
331
353
|
/** Wrapper element. @default 'div' */
|
|
332
354
|
as?: AdaptiveElement;
|
|
@@ -370,7 +392,7 @@ type AdaptiveVariantsProps = {
|
|
|
370
392
|
* versions compete in one experiment (spec 2026-09-23 §7). Without
|
|
371
393
|
* children, `variants` keeps the variants-only experiment it always had. */
|
|
372
394
|
children?: ReactNode;
|
|
373
|
-
goal:
|
|
395
|
+
goal: GoalName | GoalConfig;
|
|
374
396
|
/**
|
|
375
397
|
* Funnel this component serves (stable funnel id, e.g. "checkout" —
|
|
376
398
|
* shown on the dashboard's Funnels tab). Declares membership to the server;
|
|
@@ -447,7 +469,7 @@ type AdaptiveTextProps = {
|
|
|
447
469
|
* learns. Provide a goal (a name string or a GoalConfig) to make the optimizer
|
|
448
470
|
* attribute conversions to the winning wording, exactly like `<Adaptive>`.
|
|
449
471
|
*/
|
|
450
|
-
goal?:
|
|
472
|
+
goal?: GoalName | GoalConfig;
|
|
451
473
|
};
|
|
452
474
|
/**
|
|
453
475
|
* Dashboard-managed copy for a single element. The variants are **text only** —
|
|
@@ -517,7 +539,7 @@ interface FireGoalOptions extends ComponentGoalOptions {
|
|
|
517
539
|
*/
|
|
518
540
|
once?: boolean;
|
|
519
541
|
}
|
|
520
|
-
type FireGoal = (goalType:
|
|
542
|
+
type FireGoal = (goalType: GoalName, opts?: FireGoalOptions) => void;
|
|
521
543
|
/**
|
|
522
544
|
* Returns a `fireGoal(goalType, opts?)` callback that records a conversion
|
|
523
545
|
* attributed to the variant currently served for `componentId` — so it shows
|
|
@@ -581,7 +603,47 @@ interface PageGoalOptions extends ComponentGoalOptions {
|
|
|
581
603
|
* // Session-level only — no component to attribute it to.
|
|
582
604
|
* usePageGoal('docs_view');
|
|
583
605
|
*/
|
|
584
|
-
declare function usePageGoal(goalName:
|
|
606
|
+
declare function usePageGoal(goalName: GoalName, opts?: PageGoalOptions): void;
|
|
607
|
+
|
|
608
|
+
interface UseGoalOptions {
|
|
609
|
+
/**
|
|
610
|
+
* Make this the project's main goal — the one experiments optimize and
|
|
611
|
+
* results are measured on. Change which hook carries it and deploy to change
|
|
612
|
+
* the main goal; no dashboard visit needed.
|
|
613
|
+
*
|
|
614
|
+
* It moves the main goal only when the declared goal CHANGES, so a main goal
|
|
615
|
+
* picked in the dashboard sticks until your code declares a different one.
|
|
616
|
+
* From localhost it only sets a main goal when the project has none. Every
|
|
617
|
+
* change is in the project's activity log. Declare it in ONE place: two
|
|
618
|
+
* different `primary` goals on a page are a mistake, and only the first counts.
|
|
619
|
+
*/
|
|
620
|
+
primary?: boolean;
|
|
621
|
+
/**
|
|
622
|
+
* Also credit the conversion to the version currently served for this
|
|
623
|
+
* component (same as `useAdaptiveGoal(componentId)`). Omit for a goal that
|
|
624
|
+
* belongs to the visit, not to one component.
|
|
625
|
+
*/
|
|
626
|
+
componentId?: string;
|
|
627
|
+
}
|
|
628
|
+
/** Records the goal. Options are per conversion: a value, an order id, `once`. */
|
|
629
|
+
type FireNamedGoal = (opts?: FireGoalOptions) => void;
|
|
630
|
+
/**
|
|
631
|
+
* A goal your site records — declared where it happens, and fired from there.
|
|
632
|
+
*
|
|
633
|
+
* Declaring it is what makes it show in the dashboard straight away, at an
|
|
634
|
+
* honest 0, before anyone has completed it. `primary: true` makes it the
|
|
635
|
+
* project's main goal. The returned function records one conversion.
|
|
636
|
+
*
|
|
637
|
+
* @example
|
|
638
|
+
* const signup = useGoal('signup', { primary: true });
|
|
639
|
+
* <form onSubmit={() => signup()}>…</form>
|
|
640
|
+
*
|
|
641
|
+
* @example
|
|
642
|
+
* // A revenue goal, credited to the hero version that was showing.
|
|
643
|
+
* const purchase = useGoal('purchase', { componentId: 'hero_cta' });
|
|
644
|
+
* purchase({ value: order.total, externalId: order.id });
|
|
645
|
+
*/
|
|
646
|
+
declare function useGoal(name: GoalName, options?: UseGoalOptions): FireNamedGoal;
|
|
585
647
|
|
|
586
648
|
type SentientPersonaScriptProps = {
|
|
587
649
|
/** Publishable API key — selects the localStorage snapshot in the fallback path. */
|
|
@@ -634,7 +696,7 @@ type SentientPersonaScriptProps = {
|
|
|
634
696
|
declare function SentientPersonaScript(props: SentientPersonaScriptProps): JSX.Element | null;
|
|
635
697
|
|
|
636
698
|
type UseAdaptiveTokensOptions = {
|
|
637
|
-
goal?:
|
|
699
|
+
goal?: GoalName | GoalConfig;
|
|
638
700
|
/** Funnel this slot serves (stable funnel id, e.g. "checkout") — same
|
|
639
701
|
* declaration semantics as <Adaptive funnel="...">. */
|
|
640
702
|
funnel?: string;
|
|
@@ -688,7 +750,7 @@ type UseAdaptiveResult<T> = {
|
|
|
688
750
|
*/
|
|
689
751
|
declare function useAdaptive<T>(id: string, config: {
|
|
690
752
|
variants: Record<string, T>;
|
|
691
|
-
goal:
|
|
753
|
+
goal: GoalName | GoalConfig;
|
|
692
754
|
/** Funnel this component serves (stable funnel id, e.g. "checkout") —
|
|
693
755
|
* same declaration semantics as <Adaptive funnel="...">. */
|
|
694
756
|
funnel?: string;
|
|
@@ -734,7 +796,7 @@ type AdaptiveGroupProps = {
|
|
|
734
796
|
/** Explicit baseline arrangement id (defaults to the first declared). */
|
|
735
797
|
baseline?: string;
|
|
736
798
|
/** Optional slot-scoped goal — credited via componentGoal(group id). */
|
|
737
|
-
goal?:
|
|
799
|
+
goal?: GoalName | GoalConfig;
|
|
738
800
|
/** Funnel this group serves (stable funnel id, e.g. "checkout") — same
|
|
739
801
|
* declaration semantics as <Adaptive funnel="...">. */
|
|
740
802
|
funnel?: string;
|
|
@@ -837,4 +899,4 @@ declare function renderBlocks(node: BlockNode, opts: RenderBlocksOptions): JSX.E
|
|
|
837
899
|
*/
|
|
838
900
|
declare function renderCompose(compose: ComposeArm, opts: RenderBlocksOptions): JSX.Element | null;
|
|
839
901
|
|
|
840
|
-
export { Adaptive, type AdaptiveElement, type AdaptiveGeneratedProps, AdaptiveGroup, type AdaptiveGroupProps, type AdaptivePersona, type AdaptiveProps, AdaptiveProvider, type AdaptiveProviderProps, AdaptiveSlot, type AdaptiveSlotProps, AdaptiveText, type AdaptiveTextProps, type AdaptiveVariantsProps, type AgentBlock, type AgentFeed, type AssignmentState, type ClickGoal, type ComponentWeights, type CompositeGoal, type FireGoal, type FormSubmitGoal, type GoalConfig, type MicroSignalGoalConfig, type MicroSignalGoals, type PageGoalOptions, type RenderBlocksOptions, type ScrollDepthGoal, SentientPersonaScript, type SentientPersonaScriptProps, type SsrFallback, type UseAdaptiveBind, type UseAdaptiveResult, type UseAdaptiveTokensOptions, type UseAdaptiveTokensResult, type VariantWeight, type WeightedCompositeGoal, type WeightedStep, buildAgentFeed, defineAgentContent, getAgentContent, renderAgentJsonLd, renderAgentJsonLdBody, renderAgentMarkdown, renderBlocks, renderCompose, useAdaptive, useAdaptiveApiBaseUrl, useAdaptiveGoal, useAdaptivePersona, useAdaptiveTokens, useAssignment, useInitialAssignments, useLayoutOrder, usePageGoal, useSentient, useSessionSegment };
|
|
902
|
+
export { Adaptive, type AdaptiveElement, type AdaptiveGeneratedProps, AdaptiveGroup, type AdaptiveGroupProps, type AdaptivePersona, type AdaptiveProps, AdaptiveProvider, type AdaptiveProviderProps, AdaptiveSlot, type AdaptiveSlotProps, AdaptiveText, type AdaptiveTextProps, type AdaptiveVariantsProps, type AgentBlock, type AgentFeed, type AssignmentState, type ClickGoal, type ComponentWeights, type CompositeGoal, type FireGoal, type FireNamedGoal, type FormSubmitGoal, type GoalConfig, type GoalName, type MicroSignalGoalConfig, type MicroSignalGoals, type PageGoalOptions, type Register, type RenderBlocksOptions, type ScrollDepthGoal, SentientPersonaScript, type SentientPersonaScriptProps, type SsrFallback, type UseAdaptiveBind, type UseAdaptiveResult, type UseAdaptiveTokensOptions, type UseAdaptiveTokensResult, type UseGoalOptions, type VariantWeight, type WeightedCompositeGoal, type WeightedStep, buildAgentFeed, defineAgentContent, getAgentContent, renderAgentJsonLd, renderAgentJsonLdBody, renderAgentMarkdown, renderBlocks, renderCompose, useAdaptive, useAdaptiveApiBaseUrl, useAdaptiveGoal, useAdaptivePersona, useAdaptiveTokens, useAssignment, useGoal, useInitialAssignments, useLayoutOrder, usePageGoal, useSentient, useSessionSegment };
|
package/dist/index.d.ts
CHANGED
|
@@ -268,6 +268,28 @@ declare function useLayoutOrder(): string[] | null;
|
|
|
268
268
|
/** Internal: configured API base URL (devtools fetches /v1/explain against this, never a relative URL). */
|
|
269
269
|
declare function useAdaptiveApiBaseUrl(): string;
|
|
270
270
|
|
|
271
|
+
/**
|
|
272
|
+
* Your app's goal ids, for autocomplete and typo checks. Declare them once,
|
|
273
|
+
* anywhere in your app's TypeScript:
|
|
274
|
+
*
|
|
275
|
+
* declare module '@sentientui/react' {
|
|
276
|
+
* interface Register { goal: 'signup' | 'viewed_pricing' | 'purchase' }
|
|
277
|
+
* }
|
|
278
|
+
*
|
|
279
|
+
* Every goal name the SDK takes — `useGoal`, `usePageGoal`, the fire function
|
|
280
|
+
* from `useAdaptiveGoal`, the `goal` prop on `<Adaptive>` and the other
|
|
281
|
+
* components — then accepts only those. A misspelled goal is not an error at
|
|
282
|
+
* runtime: it records a goal of its own that never matches the one you meant,
|
|
283
|
+
* and a misspelled main goal reads 0% forever. Without the declaration every
|
|
284
|
+
* name is a plain string, as before.
|
|
285
|
+
*/
|
|
286
|
+
interface Register {
|
|
287
|
+
}
|
|
288
|
+
/** A goal id: the union declared on `Register['goal']`, else any string. */
|
|
289
|
+
type GoalName = Register extends {
|
|
290
|
+
goal: infer G extends string;
|
|
291
|
+
} ? G : string;
|
|
292
|
+
|
|
271
293
|
/**
|
|
272
294
|
* The element `<Adaptive>` renders around its content (audit S17: it was
|
|
273
295
|
* always a `<div>`, which is invalid inside a `<ul>`, a `<p>` or a table row
|
|
@@ -296,7 +318,7 @@ type CompositeGoal = {
|
|
|
296
318
|
};
|
|
297
319
|
type WeightedStep = {
|
|
298
320
|
goal: GoalConfig;
|
|
299
|
-
name:
|
|
321
|
+
name: GoalName;
|
|
300
322
|
weight: number;
|
|
301
323
|
};
|
|
302
324
|
type WeightedCompositeGoal = {
|
|
@@ -306,8 +328,8 @@ type WeightedCompositeGoal = {
|
|
|
306
328
|
type GoalConfig = ScrollDepthGoal | ClickGoal | FormSubmitGoal | CompositeGoal | WeightedCompositeGoal;
|
|
307
329
|
|
|
308
330
|
/** Maps a detected micro-signal to a named session goal (`client.goal`). */
|
|
309
|
-
type MicroSignalGoalConfig =
|
|
310
|
-
name:
|
|
331
|
+
type MicroSignalGoalConfig = GoalName | {
|
|
332
|
+
name: GoalName;
|
|
311
333
|
weight?: number;
|
|
312
334
|
stepIndex?: number;
|
|
313
335
|
};
|
|
@@ -326,7 +348,7 @@ type AdaptiveSlotProps = {
|
|
|
326
348
|
onFormSubmit?: (values: Record<string, string>) => void;
|
|
327
349
|
/** Optional goal attached to the container (click/scroll/composite), same
|
|
328
350
|
* shape as AdaptiveGroup's. Form arms fire their own submitGoal regardless. */
|
|
329
|
-
goal?:
|
|
351
|
+
goal?: GoalName | GoalConfig;
|
|
330
352
|
className?: string;
|
|
331
353
|
/** Wrapper element. @default 'div' */
|
|
332
354
|
as?: AdaptiveElement;
|
|
@@ -370,7 +392,7 @@ type AdaptiveVariantsProps = {
|
|
|
370
392
|
* versions compete in one experiment (spec 2026-09-23 §7). Without
|
|
371
393
|
* children, `variants` keeps the variants-only experiment it always had. */
|
|
372
394
|
children?: ReactNode;
|
|
373
|
-
goal:
|
|
395
|
+
goal: GoalName | GoalConfig;
|
|
374
396
|
/**
|
|
375
397
|
* Funnel this component serves (stable funnel id, e.g. "checkout" —
|
|
376
398
|
* shown on the dashboard's Funnels tab). Declares membership to the server;
|
|
@@ -447,7 +469,7 @@ type AdaptiveTextProps = {
|
|
|
447
469
|
* learns. Provide a goal (a name string or a GoalConfig) to make the optimizer
|
|
448
470
|
* attribute conversions to the winning wording, exactly like `<Adaptive>`.
|
|
449
471
|
*/
|
|
450
|
-
goal?:
|
|
472
|
+
goal?: GoalName | GoalConfig;
|
|
451
473
|
};
|
|
452
474
|
/**
|
|
453
475
|
* Dashboard-managed copy for a single element. The variants are **text only** —
|
|
@@ -517,7 +539,7 @@ interface FireGoalOptions extends ComponentGoalOptions {
|
|
|
517
539
|
*/
|
|
518
540
|
once?: boolean;
|
|
519
541
|
}
|
|
520
|
-
type FireGoal = (goalType:
|
|
542
|
+
type FireGoal = (goalType: GoalName, opts?: FireGoalOptions) => void;
|
|
521
543
|
/**
|
|
522
544
|
* Returns a `fireGoal(goalType, opts?)` callback that records a conversion
|
|
523
545
|
* attributed to the variant currently served for `componentId` — so it shows
|
|
@@ -581,7 +603,47 @@ interface PageGoalOptions extends ComponentGoalOptions {
|
|
|
581
603
|
* // Session-level only — no component to attribute it to.
|
|
582
604
|
* usePageGoal('docs_view');
|
|
583
605
|
*/
|
|
584
|
-
declare function usePageGoal(goalName:
|
|
606
|
+
declare function usePageGoal(goalName: GoalName, opts?: PageGoalOptions): void;
|
|
607
|
+
|
|
608
|
+
interface UseGoalOptions {
|
|
609
|
+
/**
|
|
610
|
+
* Make this the project's main goal — the one experiments optimize and
|
|
611
|
+
* results are measured on. Change which hook carries it and deploy to change
|
|
612
|
+
* the main goal; no dashboard visit needed.
|
|
613
|
+
*
|
|
614
|
+
* It moves the main goal only when the declared goal CHANGES, so a main goal
|
|
615
|
+
* picked in the dashboard sticks until your code declares a different one.
|
|
616
|
+
* From localhost it only sets a main goal when the project has none. Every
|
|
617
|
+
* change is in the project's activity log. Declare it in ONE place: two
|
|
618
|
+
* different `primary` goals on a page are a mistake, and only the first counts.
|
|
619
|
+
*/
|
|
620
|
+
primary?: boolean;
|
|
621
|
+
/**
|
|
622
|
+
* Also credit the conversion to the version currently served for this
|
|
623
|
+
* component (same as `useAdaptiveGoal(componentId)`). Omit for a goal that
|
|
624
|
+
* belongs to the visit, not to one component.
|
|
625
|
+
*/
|
|
626
|
+
componentId?: string;
|
|
627
|
+
}
|
|
628
|
+
/** Records the goal. Options are per conversion: a value, an order id, `once`. */
|
|
629
|
+
type FireNamedGoal = (opts?: FireGoalOptions) => void;
|
|
630
|
+
/**
|
|
631
|
+
* A goal your site records — declared where it happens, and fired from there.
|
|
632
|
+
*
|
|
633
|
+
* Declaring it is what makes it show in the dashboard straight away, at an
|
|
634
|
+
* honest 0, before anyone has completed it. `primary: true` makes it the
|
|
635
|
+
* project's main goal. The returned function records one conversion.
|
|
636
|
+
*
|
|
637
|
+
* @example
|
|
638
|
+
* const signup = useGoal('signup', { primary: true });
|
|
639
|
+
* <form onSubmit={() => signup()}>…</form>
|
|
640
|
+
*
|
|
641
|
+
* @example
|
|
642
|
+
* // A revenue goal, credited to the hero version that was showing.
|
|
643
|
+
* const purchase = useGoal('purchase', { componentId: 'hero_cta' });
|
|
644
|
+
* purchase({ value: order.total, externalId: order.id });
|
|
645
|
+
*/
|
|
646
|
+
declare function useGoal(name: GoalName, options?: UseGoalOptions): FireNamedGoal;
|
|
585
647
|
|
|
586
648
|
type SentientPersonaScriptProps = {
|
|
587
649
|
/** Publishable API key — selects the localStorage snapshot in the fallback path. */
|
|
@@ -634,7 +696,7 @@ type SentientPersonaScriptProps = {
|
|
|
634
696
|
declare function SentientPersonaScript(props: SentientPersonaScriptProps): JSX.Element | null;
|
|
635
697
|
|
|
636
698
|
type UseAdaptiveTokensOptions = {
|
|
637
|
-
goal?:
|
|
699
|
+
goal?: GoalName | GoalConfig;
|
|
638
700
|
/** Funnel this slot serves (stable funnel id, e.g. "checkout") — same
|
|
639
701
|
* declaration semantics as <Adaptive funnel="...">. */
|
|
640
702
|
funnel?: string;
|
|
@@ -688,7 +750,7 @@ type UseAdaptiveResult<T> = {
|
|
|
688
750
|
*/
|
|
689
751
|
declare function useAdaptive<T>(id: string, config: {
|
|
690
752
|
variants: Record<string, T>;
|
|
691
|
-
goal:
|
|
753
|
+
goal: GoalName | GoalConfig;
|
|
692
754
|
/** Funnel this component serves (stable funnel id, e.g. "checkout") —
|
|
693
755
|
* same declaration semantics as <Adaptive funnel="...">. */
|
|
694
756
|
funnel?: string;
|
|
@@ -734,7 +796,7 @@ type AdaptiveGroupProps = {
|
|
|
734
796
|
/** Explicit baseline arrangement id (defaults to the first declared). */
|
|
735
797
|
baseline?: string;
|
|
736
798
|
/** Optional slot-scoped goal — credited via componentGoal(group id). */
|
|
737
|
-
goal?:
|
|
799
|
+
goal?: GoalName | GoalConfig;
|
|
738
800
|
/** Funnel this group serves (stable funnel id, e.g. "checkout") — same
|
|
739
801
|
* declaration semantics as <Adaptive funnel="...">. */
|
|
740
802
|
funnel?: string;
|
|
@@ -837,4 +899,4 @@ declare function renderBlocks(node: BlockNode, opts: RenderBlocksOptions): JSX.E
|
|
|
837
899
|
*/
|
|
838
900
|
declare function renderCompose(compose: ComposeArm, opts: RenderBlocksOptions): JSX.Element | null;
|
|
839
901
|
|
|
840
|
-
export { Adaptive, type AdaptiveElement, type AdaptiveGeneratedProps, AdaptiveGroup, type AdaptiveGroupProps, type AdaptivePersona, type AdaptiveProps, AdaptiveProvider, type AdaptiveProviderProps, AdaptiveSlot, type AdaptiveSlotProps, AdaptiveText, type AdaptiveTextProps, type AdaptiveVariantsProps, type AgentBlock, type AgentFeed, type AssignmentState, type ClickGoal, type ComponentWeights, type CompositeGoal, type FireGoal, type FormSubmitGoal, type GoalConfig, type MicroSignalGoalConfig, type MicroSignalGoals, type PageGoalOptions, type RenderBlocksOptions, type ScrollDepthGoal, SentientPersonaScript, type SentientPersonaScriptProps, type SsrFallback, type UseAdaptiveBind, type UseAdaptiveResult, type UseAdaptiveTokensOptions, type UseAdaptiveTokensResult, type VariantWeight, type WeightedCompositeGoal, type WeightedStep, buildAgentFeed, defineAgentContent, getAgentContent, renderAgentJsonLd, renderAgentJsonLdBody, renderAgentMarkdown, renderBlocks, renderCompose, useAdaptive, useAdaptiveApiBaseUrl, useAdaptiveGoal, useAdaptivePersona, useAdaptiveTokens, useAssignment, useInitialAssignments, useLayoutOrder, usePageGoal, useSentient, useSessionSegment };
|
|
902
|
+
export { Adaptive, type AdaptiveElement, type AdaptiveGeneratedProps, AdaptiveGroup, type AdaptiveGroupProps, type AdaptivePersona, type AdaptiveProps, AdaptiveProvider, type AdaptiveProviderProps, AdaptiveSlot, type AdaptiveSlotProps, AdaptiveText, type AdaptiveTextProps, type AdaptiveVariantsProps, type AgentBlock, type AgentFeed, type AssignmentState, type ClickGoal, type ComponentWeights, type CompositeGoal, type FireGoal, type FireNamedGoal, type FormSubmitGoal, type GoalConfig, type GoalName, type MicroSignalGoalConfig, type MicroSignalGoals, type PageGoalOptions, type Register, type RenderBlocksOptions, type ScrollDepthGoal, SentientPersonaScript, type SentientPersonaScriptProps, type SsrFallback, type UseAdaptiveBind, type UseAdaptiveResult, type UseAdaptiveTokensOptions, type UseAdaptiveTokensResult, type UseGoalOptions, type VariantWeight, type WeightedCompositeGoal, type WeightedStep, buildAgentFeed, defineAgentContent, getAgentContent, renderAgentJsonLd, renderAgentJsonLdBody, renderAgentMarkdown, renderBlocks, renderCompose, useAdaptive, useAdaptiveApiBaseUrl, useAdaptiveGoal, useAdaptivePersona, useAdaptiveTokens, useAssignment, useGoal, useInitialAssignments, useLayoutOrder, usePageGoal, useSentient, useSessionSegment };
|