For AI agents: the complete documentation index is available at /apps-plugin/docs/llms.txt, the full documentation bundle is available at /apps-plugin/docs/llms-full.txt, and this page is available as Markdown at /apps-plugin/docs/js-api/basic/system/getAppAuthorizeSetting.md.

getAppAuthorizeSetting

获取豆包客户端的系统授权设置。

调用只读取当前系统授权状态,不会申请权限或触发系统授权弹窗。原有状态字段固定返回 authorized、denied 或 not determined,精细授权字段用于区分部分、只读、只写、前后台等能力。

扫码预览

扫码预览 getAppAuthorizeSetting

支持版本

前端库版本不低于 0.0.40。

支持平台

平台支持情况
Android支持
iOS支持
PC不支持
HarmonyOS不支持

支持场景

场景支持情况
页面支持
卡片支持

使用说明

  • 本接口查询豆包客户端的系统权限,不等同于查询当前应用插件的 scope 授权。
  • iOS:SDK 首次完成通知设置异步预热前,或应用重新激活后的刷新尚未完成时,四个通知字段可能仍为旧值或 not determined。
  • iOS:healthDataAuthorizationDetail 使用异步缓存;首次预热或应用重新激活刷新完成前可能返回 UNKNOWN。Apple 不公开精确读取授权,DENIED/GRANTED 为轻量查询推断。

调用方式

同步 API

getAppAuthorizeSetting(params?: object): GetAppAuthorizeSettingResult

入参

无。

调用示例

import { getAppAuthorizeSetting } from '@doubao-dev/framework/api';

const result = getAppAuthorizeSetting();
const detail = result.phoneCalendarAuthorizationDetail;
const canWriteCalendar =
  detail === 'full' ||
  detail === 'write only' ||
  (detail == null && result.phoneCalendarAuthorized === 'authorized');
console.log(canWriteCalendar);
console.log(result.healthDataAuthorizationDetail?.readStatus);

返回值

名称类型必返说明
albumAuthorizationDetailAlbumAuthorizationDetail | null否相册精细授权状态;旧客户端或无法可靠映射时不返回该字段或返回 null。

继承 BasicAuthorizationDetail 的全部取值,并增加:
  • limited:只能访问用户选择的部分照片;支持 iOS 和 Android 14 及以上版本。
  • add only:只能向相册添加照片,不能读取相册内容;仅 iOS 支持。
albumAuthorizedAppAuthorizeStatus是相册授权状态;Android 固定返回 not determined
bluetoothAuthorizationDetailBluetoothAuthorizationDetail | null否蓝牙精细授权状态;旧客户端或无法可靠映射时不返回该字段或返回 null。

继承 BasicAuthorizationDetail 的全部取值,并增加:
  • partial:只获得部分已声明的蓝牙子权限;仅 Android 支持。
bluetoothAuthorizedAppAuthorizeStatus是蓝牙授权状态
cameraAuthorizationDetailBasicAuthorizationDetail | null否摄像头精细授权状态,取值与 BasicAuthorizationDetail 一致;旧客户端或无法可靠映射时不返回该字段或返回 `null`。
cameraAuthorizedAppAuthorizeStatus是摄像头授权状态
healthDataAuthorizationDetailHealthDataAuthorizationDetail | null否HealthKit 逐类型读取授权状态;仅 iOS 新版本客户端返回。

Apple 不提供读取权限的精确查询接口。`status` 为 1 或 2 时采用轻量查询推断,
“已授权但没有数据”和“拒绝读取”仍可能无法可靠区分;业务应以实际读取结果为准。
healthDataAuthorizationDetail.readStatusHealthDataAuthorizationItem[]否iOS SDK 支持的全部健康类型及其读取状态。
healthDataAuthorizationDetail.readStatus[].statusHealthDataAuthorizationStatus否当前类型的读取权限状态码。
healthDataAuthorizationDetail.readStatus[].typeHealthDataType否健康数据类型。
locationAuthorizationDetailLocationAuthorizationDetail | null否定位精细授权状态;旧客户端或无法可靠映射时不返回该字段或返回 null。

继承 UnauthorizedDetail 的全部取值;获得权限时返回:
  • foreground approximate:仅应用在前台时可以获取模糊定位。
  • foreground precise:仅应用在前台时可以获取精确定位。
  • background approximate:应用在前台或后台时均可以获取模糊定位。
  • background precise:应用在前台或后台时均可以获取精确定位。
locationAuthorizedAppAuthorizeStatus是定位授权状态
locationReducedAccuracyboolean是是否只能使用模糊定位;仅在 iOS 且定位已授权时具有精度含义,Android 固定返回 false
microphoneAuthorizationDetailBasicAuthorizationDetail | null否麦克风精细授权状态,取值与 BasicAuthorizationDetail 一致;旧客户端或无法可靠映射时不返回该字段或返回 `null`。
microphoneAuthorizedAppAuthorizeStatus是麦克风授权状态
notificationAlertAuthorizedAppAuthorizeStatus是通知提醒授权状态;Android 固定返回 not determined
notificationAuthorizationDetailNotificationAuthorizationDetail | null否通知精细授权状态;旧客户端或无法可靠映射时不返回该字段或返回 null。

继承 BasicAuthorizationDetail 的全部取值,并增加:
  • provisional:iOS 临时静默授权;不会弹出授权框,通知只进入通知中心。
notificationAuthorizedAppAuthorizeStatus是通知总授权状态
notificationBadgeAuthorizedAppAuthorizeStatus是通知角标授权状态;Android 固定返回 not determined
notificationSoundAuthorizedAppAuthorizeStatus是通知声音授权状态;Android 固定返回 not determined
phoneCalendarAuthorizationDetailPhoneCalendarAuthorizationDetail | null否系统日历精细授权状态;旧客户端或无法可靠映射时不返回该字段或返回 null。

继承 BasicAuthorizationDetail 的全部取值,并增加:
  • read only:只能读取日历,不能新增、修改或删除日程;仅 Android 支持。
  • write only:只能新增日程,不能读取现有日历数据。
phoneCalendarAuthorizedAppAuthorizeStatus是系统日历授权状态

返回示例

{
  "albumAuthorized": "authorized",
  "bluetoothAuthorized": "denied",
  "cameraAuthorized": "authorized",
  "locationAuthorized": "authorized",
  "locationReducedAccuracy": false,
  "microphoneAuthorized": "authorized",
  "notificationAuthorized": "authorized",
  "notificationAlertAuthorized": "authorized",
  "notificationBadgeAuthorized": "denied",
  "notificationSoundAuthorized": "authorized",
  "phoneCalendarAuthorized": "denied",
  "albumAuthorizationDetail": "limited",
  "bluetoothAuthorizationDetail": "full",
  "cameraAuthorizationDetail": "full",
  "locationAuthorizationDetail": "foreground precise",
  "microphoneAuthorizationDetail": "full",
  "notificationAuthorizationDetail": "provisional",
  "phoneCalendarAuthorizationDetail": "write only",
  "healthDataAuthorizationDetail": {
    "readStatus": [
      { "type": "heart_rate", "status": 2 },
      { "type": "step_count", "status": 0 }
    ]
  }
}

平台差异

  • Android:albumAuthorized 和通知分项固定返回 not determined,locationReducedAccuracy 固定返回 false 且不表示实际定位精度
  • Android:bluetoothAuthorized、cameraAuthorized、locationAuthorized、microphoneAuthorized、notificationAuthorized 和 phoneCalendarAuthorized 不区分尚未申请和已经拒绝,两种情况均返回 denied
  • Android:locationAuthorized 在粗略或精确定位任一权限已授权时返回 authorized;phoneCalendarAuthorized 仅在读、写日历权限均授权时返回 authorized
  • Android:精细字段区分 Android 14 部分相册、日历读写、定位前后台和精度,以及蓝牙部分子权限
  • iOS:相册 limited 映射为 authorized,通知 provisional 和 ephemeral 映射为 authorized
  • iOS:精细字段区分相册 limited/add only、日历 write only、定位前后台和精度,以及通知 provisional;ephemeral 暂不映射
  • iOS:healthDataAuthorizationDetail 返回 SDK 支持的全部健康类型,调用方可按自己申请读取权限时使用的 types 过滤;它不等同于 Apple 提供的精确读取授权结果