权限处置

Web 接入 Kivicube 时，最需要关注的权限主要有三类：

• 摄像头
• 动作与方向（陀螺仪）
• 媒体自动播放相关限制

iframe 权限声明

当前插件在打开 iframe 时，会自动写入一组 allow 能力，包括：

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

因此通常不需要你手动再拼写这段字符串；只是不要把它覆盖掉即可。

摄像头权限

何时需要

• 图像 AR
• 云识别
• 任何依赖真实相机画面的场景

拒绝后的表现

插件会通过 error 事件抛出带标记的数据：

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

兼容性失败

如果当前浏览器本身就不能打开摄像头，还可能收到 incompatibility 事件。

动作与方向权限

这主要影响开启陀螺仪的场景。

拒绝后的表现

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

合辑额外属性

合辑支持：

hideGyroscopePermission: true

它可以隐藏默认的陀螺仪授权提示弹窗，适合确认不再需要此功能的设备，比如iOS。

媒体自动播放限制

即便拿到了摄像头权限，视频和音频仍可能受浏览器自动播放策略影响。

最常见的触发因素有：

• 强制隐藏立即体验按钮
• 媒体播放没有在用户手势事件下执行
• iOS / App 内 WebView 开启更严格的策略

建议的权限兜底方案

1. 监听 error
2. 监听 incompatibility
3. 对摄像头和陀螺仪分别给出宿主层说明
4. 对媒体播放失败准备降级方案

一段推荐示例

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

  if (detail.isUserDeniedCamera) {
    showToast('请允许摄像头权限后重试');
    return;
  }

  if (detail.isUserDeniedGyroscope) {
    showToast('请允许动作与方向权限后重试');
    return;
  }

  showToast(detail.message || '体验暂时不可用');
});

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