Start Now Button

By default, once assets finish downloading, Kivicube shows a "Start Now" button and waits for the user to click before entering the scene.

Why This Button Exists by Default

It is not just a UI element. It also helps with browser media policy:

• it makes the browser treat camera access as user-initiated, which improves success rate
• it provides a user gesture to unlock later audio and video playback
• it avoids jumping directly into the experience as soon as assets finish downloading, which can feel abrupt
• it gives the host layer time to show explanations or permission guidance

Force Hide It

You can force-hide it with the hideStart property:

await kivicubeIframePlugin.openKivicubeScene(iframe, {
  sceneId,
  hideStart: true,
});

Or directly in HTML:

<iframe id="kivicubeScene" scene-id="..." hide-start></iframe>

Impact After Hiding It

• the page background may turn black or white because the camera fails to open
• after asset download finishes, the flow jumps directly into scene loading and AR without showing the button
• if the scene contains video or audio, the browser may block playback
• the plugin prints reminder logs internally to warn that this option may break media autoplay

Safer Alternatives

Compared with directly using hideStart, it is usually better to:

1. keep the platform's default start flow
2. or provide a custom host-layer "Start Now" button
3. let the flow continue only after the user clicks

If your feature depends on a button click to work reliably, a host-layer button coordinated with the default flow is safer than forcing auto-entry.

Good Cases for Hiding It

• pure Web3D experiences with no audio/video autoplay requirements
• very short flows where removing one click matters a lot

Cases Where Hiding Is Not Recommended

• experiences with lots of video or audio that need autoplay
• flows where users should explicitly grant permission or read guidance first

Customize the Start Now Button

If you want to keep the native Kivicube Start Now Button and its default behavior, but align it with your host page UI, the advanced Scene / Collection APIs provide:

getStartButtonRect(): Promise<DOMRect | undefined>
setStartButtonRect(rect: Partial<CSSStyleDeclaration>): Promise<void>

• getStartButtonRect() returns the real getBoundingClientRect() result of the button inside the iframe.
• setStartButtonRect(rect) merges the given object into the button's inline style. Common fields include position, left, top, right, bottom, width, height, and transform.

How to Get the API

On a scene page, get SceneApi from the ready event:

let api = null;

iframe.addEventListener('ready', (event) => {
  api = event.detail.api;
});

On a collection page, get CollectionApi from ready:

let api = null;

iframe.addEventListener('ready', (event) => {
  api = event.detail.api;
});

When to Call These Methods

• these two methods are only meaningful when the Start Now Button actually exists
• if hideStart: true is enabled, there is usually no button left to read or adjust
• a safer time to call them is after downloadAssetEnd, or once you are sure the button is visible
• if called too early, getStartButtonRect() may return undefined and setStartButtonRect() may have no effect

Example: Read the Button Area and Overlay a Host-Layer Button

let api = null;

iframe.addEventListener('ready', (event) => {
  api = event.detail.api;
});

iframe.addEventListener('downloadAssetEnd', async () => {
  const rect = await api.getStartButtonRect();
  if (!rect) {
    return;
  }

  Object.assign(hostStartButton.style, {
    display: 'block',
    position: 'fixed',
    left: `${rect.left}px`,
    top: `${rect.top}px`,
    width: `${rect.width}px`,
    height: `${rect.height}px`,
    pointerEvents: 'none',
  });
});

This lets you place your own visual button on top of the same position while allowing the click to pass through to the real button inside the iframe, preserving the original user gesture.

Example: Move and Resize the Button Inside the iframe Directly

await api.setStartButtonRect({
  position: 'absolute',
  left: '24px',
  bottom: '32px',
  width: 'calc(100% - 48px)',
  height: '52px',
});

It is recommended to pass CSS strings with units such as 24px, 52px, or calc(...). Values such as 0 can also be passed directly as numbers.

Common Patterns

1. Overlay a custom button in the host page at the same position, and use CSS pointer-events: none so clicks still hit the real button inside the iframe.
2. Cut out a clickable hole in the host layout so users click the iframe's real button directly while keeping the iframe's default style.
3. Move the button inside the iframe with setStartButtonRect() and align it with host-layer titles, hints, and brand decoration.