Permission Handling

When integrating Kivicube on the Web, the three permission areas that matter most are:

• camera
• motion and orientation (gyroscope)
• media autoplay restrictions

iframe Permission Declaration

When the plugin opens the iframe, it automatically writes a set of allow capabilities including:

• xr-spatial-tracking
• camera
• microphone
• autoplay
• fullscreen
• gyroscope
• accelerometer

So in most cases you do not need to build that string manually. Just make sure you do not overwrite it.

Camera Permission

When It Is Needed

• Image AR
• Basic AR/Gyroscope
• any scene that depends on the real camera feed

What Happens When the User Rejects It

The plugin emits an error event with a marked payload:

iframe.addEventListener('error', (event) => {
  if (event.detail?.isUserDeniedCamera) {
    showCameraPermissionGuide();
  }
});

Compatibility Failure

If the current browser cannot open the camera at all, you may also receive an incompatibility event.

Motion and Orientation Permission

This mainly affects scenes that enable the gyroscope.

What Happens When the User Rejects It

iframe.addEventListener('error', (event) => {
  if (event.detail?.isUserDeniedGyroscope) {
    showGyroscopeGuide();
  }
});

Extra Collection Property

Collections support:

hideGyroscopePermission: true

This hides the default gyroscope permission prompt, which is useful on devices where that feature is no longer needed, such as iOS.

Media Autoplay Restrictions

Even if camera permission is granted, video and audio playback can still be limited by browser autoplay policies.

The most common triggers are:

• forcing the Start Now Button to stay hidden
• trying to play media outside a user gesture
• stricter policies on iOS or in-app WebViews

Recommended Permission Fallback Strategy

1. listen for error
2. listen for incompatibility
3. provide separate host-layer guidance for camera and gyroscope permissions
4. prepare a degraded path when media playback fails

Recommended Example

iframe.addEventListener('error', (event) => {
  const detail = event.detail || {};

  if (detail.isUserDeniedCamera) {
    showToast('Please allow camera access and try again.');
    return;
  }

  if (detail.isUserDeniedGyroscope) {
    showToast('Please allow motion and orientation access and try again.');
    return;
  }

  showToast(detail.message || 'The experience is temporarily unavailable.');
});

iframe.addEventListener('incompatibility', () => {
  showUnsupportedDialog();
});