> 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.

# getAppAuthorizeSetting

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

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

## 扫码预览

![扫码预览 getAppAuthorizeSetting](https://api.qrserver.com/v1/create-qr-code/?size=200x200\&data=doubao%3A%2F%2Fdoubao_apps%3Fapp_id%3Ddb_1McM5Ni%26path%3D%252Fpages%252Fapi%252Fbasic%252Fget-app-authorize-setting%252Findex)

## 支持版本

前端库版本不低于 `0.0.40`。

## 支持平台

<table>
<thead>
<tr><th>平台</th><th>支持情况</th></tr>
</thead>
<tbody>
<tr><td>Android</td><td>支持</td></tr>
<tr><td>iOS</td><td>支持</td></tr>
<tr><td>PC</td><td>不支持</td></tr>
<tr><td>HarmonyOS</td><td>不支持</td></tr>
</tbody>
</table>

## 支持场景

<table>
<thead>
<tr><th>场景</th><th>支持情况</th></tr>
</thead>
<tbody>
<tr><td>页面</td><td>支持</td></tr>
<tr><td>卡片</td><td>支持</td></tr>
</tbody>
</table>

## 使用说明

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

## 调用方式

### 同步 API

```typescript
getAppAuthorizeSetting(params?: object): GetAppAuthorizeSettingResult
```

## 入参

无。

## 调用示例

```typescript
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);
```

## 返回值

<table>
<thead>
<tr><th>名称</th><th>类型</th><th>必返</th><th>说明</th></tr>
</thead>
<tbody>
<tr><td><code>albumAuthorizationDetail</code></td><td><code>AlbumAuthorizationDetail | null</code></td><td>否</td><td>相册精细授权状态；旧客户端或无法可靠映射时不返回该字段或返回 `null`。<br><br>继承 BasicAuthorizationDetail 的全部取值，并增加：<br>- `limited`：只能访问用户选择的部分照片；支持 iOS 和 Android 14 及以上版本。<br>- `add only`：只能向相册添加照片，不能读取相册内容；仅 iOS 支持。</td></tr>
<tr><td><code>albumAuthorized</code></td><td><code>AppAuthorizeStatus</code></td><td>是</td><td>相册授权状态；Android 固定返回 not determined</td></tr>
<tr><td><code>bluetoothAuthorizationDetail</code></td><td><code>BluetoothAuthorizationDetail | null</code></td><td>否</td><td>蓝牙精细授权状态；旧客户端或无法可靠映射时不返回该字段或返回 `null`。<br><br>继承 BasicAuthorizationDetail 的全部取值，并增加：<br>- `partial`：只获得部分已声明的蓝牙子权限；仅 Android 支持。</td></tr>
<tr><td><code>bluetoothAuthorized</code></td><td><code>AppAuthorizeStatus</code></td><td>是</td><td>蓝牙授权状态</td></tr>
<tr><td><code>cameraAuthorizationDetail</code></td><td><code>BasicAuthorizationDetail | null</code></td><td>否</td><td>摄像头精细授权状态，取值与 BasicAuthorizationDetail 一致；旧客户端或无法可靠映射时不返回该字段或返回 `null`。</td></tr>
<tr><td><code>cameraAuthorized</code></td><td><code>AppAuthorizeStatus</code></td><td>是</td><td>摄像头授权状态</td></tr>
<tr><td><code>healthDataAuthorizationDetail</code></td><td><code>HealthDataAuthorizationDetail | null</code></td><td>否</td><td>HealthKit 逐类型读取授权状态；仅 iOS 新版本客户端返回。<br><br>Apple 不提供读取权限的精确查询接口。`status` 为 1 或 2 时采用轻量查询推断，<br>“已授权但没有数据”和“拒绝读取”仍可能无法可靠区分；业务应以实际读取结果为准。</td></tr>
<tr><td><code>healthDataAuthorizationDetail.readStatus</code></td><td><code>HealthDataAuthorizationItem[]</code></td><td>否</td><td>iOS SDK 支持的全部健康类型及其读取状态。</td></tr>
<tr><td><code>healthDataAuthorizationDetail.readStatus[].status</code></td><td><code>HealthDataAuthorizationStatus</code></td><td>否</td><td>当前类型的读取权限状态码。</td></tr>
<tr><td><code>healthDataAuthorizationDetail.readStatus[].type</code></td><td><code>HealthDataType</code></td><td>否</td><td>健康数据类型。</td></tr>
<tr><td><code>locationAuthorizationDetail</code></td><td><code>LocationAuthorizationDetail | null</code></td><td>否</td><td>定位精细授权状态；旧客户端或无法可靠映射时不返回该字段或返回 `null`。<br><br>继承 UnauthorizedDetail 的全部取值；获得权限时返回：<br>- `foreground approximate`：仅应用在前台时可以获取模糊定位。<br>- `foreground precise`：仅应用在前台时可以获取精确定位。<br>- `background approximate`：应用在前台或后台时均可以获取模糊定位。<br>- `background precise`：应用在前台或后台时均可以获取精确定位。</td></tr>
<tr><td><code>locationAuthorized</code></td><td><code>AppAuthorizeStatus</code></td><td>是</td><td>定位授权状态</td></tr>
<tr><td><code>locationReducedAccuracy</code></td><td><code>boolean</code></td><td>是</td><td>是否只能使用模糊定位；仅在 iOS 且定位已授权时具有精度含义，Android 固定返回 false</td></tr>
<tr><td><code>microphoneAuthorizationDetail</code></td><td><code>BasicAuthorizationDetail | null</code></td><td>否</td><td>麦克风精细授权状态，取值与 BasicAuthorizationDetail 一致；旧客户端或无法可靠映射时不返回该字段或返回 `null`。</td></tr>
<tr><td><code>microphoneAuthorized</code></td><td><code>AppAuthorizeStatus</code></td><td>是</td><td>麦克风授权状态</td></tr>
<tr><td><code>notificationAlertAuthorized</code></td><td><code>AppAuthorizeStatus</code></td><td>是</td><td>通知提醒授权状态；Android 固定返回 not determined</td></tr>
<tr><td><code>notificationAuthorizationDetail</code></td><td><code>NotificationAuthorizationDetail | null</code></td><td>否</td><td>通知精细授权状态；旧客户端或无法可靠映射时不返回该字段或返回 `null`。<br><br>继承 BasicAuthorizationDetail 的全部取值，并增加：<br>- `provisional`：iOS 临时静默授权；不会弹出授权框，通知只进入通知中心。</td></tr>
<tr><td><code>notificationAuthorized</code></td><td><code>AppAuthorizeStatus</code></td><td>是</td><td>通知总授权状态</td></tr>
<tr><td><code>notificationBadgeAuthorized</code></td><td><code>AppAuthorizeStatus</code></td><td>是</td><td>通知角标授权状态；Android 固定返回 not determined</td></tr>
<tr><td><code>notificationSoundAuthorized</code></td><td><code>AppAuthorizeStatus</code></td><td>是</td><td>通知声音授权状态；Android 固定返回 not determined</td></tr>
<tr><td><code>phoneCalendarAuthorizationDetail</code></td><td><code>PhoneCalendarAuthorizationDetail | null</code></td><td>否</td><td>系统日历精细授权状态；旧客户端或无法可靠映射时不返回该字段或返回 `null`。<br><br>继承 BasicAuthorizationDetail 的全部取值，并增加：<br>- `read only`：只能读取日历，不能新增、修改或删除日程；仅 Android 支持。<br>- `write only`：只能新增日程，不能读取现有日历数据。</td></tr>
<tr><td><code>phoneCalendarAuthorized</code></td><td><code>AppAuthorizeStatus</code></td><td>是</td><td>系统日历授权状态</td></tr>
</tbody>
</table>

### 返回示例

```json
{
  "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 提供的精确读取授权结果
