Session.tryOn Contract 2.0.0 · package sha256
a857eca95b35921109faf997094bb4192f12527d9d0fcd4be7e97f06425bad6e· generated fromconfigurator-runtime.d.tsbyservices/onsite-scripter/scripts/build-contract-docs.mjs; edit the source, not this file.
Method of Session · inherited by testing.FakeSession · labs, @experimental · since 2.0.0 · called as session.tryOn · optional: reach it through has()
tryOn?(options?: TryOnOptions): Promise<TryOnReport>;Opens try-on. Call it inside the shopper's tap, before any await: a returning shopper's camera
starts in this call, and without the tap's activation it resolves reason: 'needs-tap'.
Resolves when try-on closes or fails to open, like navigator.share(); a call while one is
open returns that call's Promise. mode: 'handoff', used only after
supports('tryOn.mode.handoff'), hands the product to a phone instead: Holostep's screen
shows a QR code of a link and the same link to copy; it starts no camera here, so it needs no
tap, and resolves launched: true with handoffUrl once the screen closed.
Errors: a failure resolves launched: false with its reason; only invalid input
(HoloInputError) and an aborted signal (AbortError) reject.
Experimental, so optional in this declaration: reach it through has(session, 'tryOn').
| Option | Type | Default | What it does |
|---|---|---|---|
mode |
'auto' | 'here' | 'handoff' |
'auto' | 'auto' picks for this device, which is 'here'; 'here' this page; 'handoff' a phone: Holostep's hand-off screen shows a QR code of returnUrl (or this page's… |
overlayRoot |
HTMLElement |
undefined (a layer over the whole page, which makes the page under it inert while it shows, removed when try-on closes) | Your element for try-on's screens, as ActivateAROptions.overlayRoot is AR's: a positioned element the size of the try-on view; the camera picture and… |
returnUrl |
string |
undefined (this page's address) | The link the hand-off's QR code carries, for 'handoff': an http(s) URL, absolute or read against this page (anything else rejects HoloInputError). |
signal |
AbortSignal |
undefined | Aborting closes try-on and rejects the call with AbortError. |
ui |
'default' | 'headless' |
'default' | 'default' shows Holostep's screens; 'headless' (not offered yet) resolves 'unsupported'. |
signal) This call is none of the kinds of call: it has its own abort rule, its options say (SignalOption.signal, the kinds of call).
Aborting closes try-on and rejects the call with AbortError. (
TryOnOptions.signal)
Imports: values (has, validate, the Holo*Error classes, the pure helpers) from @holostep-configurators/runtime-client, types from @holostep-configurators/runtime-client/contract, /math and /testing names from those entries; boot from the runtime module the root's loadRuntimeAtFloor resolves to. A type your page defines is your app's: declare it there, never import it from the package.
Compiled under the contract's strict settings (examples/declaration/05-Session.tryOn.ts):
import { has } from '@holostep-configurators/runtime-client';
import type { Session } from '@holostep-configurators/runtime-client/contract';
declare const session: Session;
declare const signal: AbortSignal;
declare function toast(text: string): void;
// In the Try-on button's click handler (the shopper's gesture):
if (has(session, 'tryOn')) {
const report = await session.tryOn({ signal });
if (!report.launched && report.reason === 'camera-denied') toast('Allow the camera to try it on.');
}| Rule | Result |
|---|---|
| 1. Neutral name | pass: tryOn names no product |
| 2. A precedent | pass: model-viewer canActivateAR and activateAR() (row G66); XRSession.end() (row G66); Navigator.share() (resolves when the share UI closes) (row G66) |
| 3. Two apps, or labs | labs (@experimental at a stable path, reached through has() or supports()): it graduates when a second app uses it; apps today: configurator-template, tryon-template |
| 4. The cheaper fix first | decided per need in Appendix B: rows G66 at tier labs (a member only where no rule, data, asset or app code serves the need) |