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

# authorize

提前向用户发起指定 scope 的授权；scope.healthData 仅用于选择 iOS HealthKit 系统授权路径。

## 扫码预览

![扫码预览 authorize](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%252Fauthorize%252Findex)

## 使用限制

> \[!WARNING]
> **Android、iOS**：传入 scope.payment 时被判为非法 scope 并直接失败；依赖 scope.payment 发起授权的调用无法成功。

## 支持版本

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

## 支持平台

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

## 接入准备

### 权限要求

<table>
<thead>
<tr><th>类型</th><th>标识</th><th>是否必须</th><th>平台</th><th>说明</th></tr>
</thead>
<tbody>
<tr><td>应用权限</td><td><code>非 scope.healthData 的 scope</code></td><td>必须</td><td>Android、iOS</td><td>按传入 scope 发起对应的应用授权。</td></tr>
<tr><td>应用权限</td><td><code>scope.healthData</code></td><td>否</td><td>iOS</td><td>不校验 manifest，也不查询或更新服务端应用插件的 scope 状态。</td></tr>
<tr><td>系统权限</td><td>HealthKit read</td><td>必须</td><td>iOS</td><td>scope.healthData 会申请 options.types 对应的系统读取权限。</td></tr>
</tbody>
</table>

### 授权行为

- **Android**：非健康 scope 会发起应用插件及相应系统授权；当前不支持 scope.healthData。
- **iOS**：非健康 scope 会发起应用插件及相应系统授权；scope.healthData 仅可能展示 HealthKit 系统授权框。

### 前置条件

- **Android**：非健康 scope 需要在应用权限声明中配置；当前不支持 scope.healthData
- **iOS**：非健康 scope 需要在应用权限声明中配置；scope.healthData 不需要 manifest 声明

## 使用说明

- **Android**：非健康 scope 的授权状态可通过 `getSetting` 查询；当前不支持 scope.healthData。
- **iOS**：非健康 scope 的授权状态可通过 `getSetting` 查询；scope.healthData 的逐类型系统状态通过 `getAppAuthorizeSetting` 查询。
- **iOS**：HealthKit 授权成功表示系统授权流程已完成；Apple 不向应用公开每个读取类型是否被用户拒绝。

## 调用方式

### 异步 API

```typescript
authorize(params: AuthorizeRequest): Promise<object>
```

## 入参

<table>
<thead>
<tr><th>名称</th><th>类型</th><th>必填</th><th>默认值</th><th>约束</th><th>说明</th></tr>
</thead>
<tbody>
<tr><td><code>options</code></td><td><code>HealthDataAuthorizeOptions</code></td><td>否</td><td><code>-</code></td><td>-</td><td>权限扩展参数；仅 scope.healthData 生效，用于传入 HealthKit 读取类型，其他 scope 会忽略该字段。</td></tr>
<tr><td><code>options.types</code></td><td><code>HealthDataType[]</code></td><td>否</td><td>-</td><td>-</td><td>健康数据类型列表；用于申请对应的 HealthKit 读取权限。</td></tr>
<tr><td><code>scope</code></td><td><code>Scope</code></td><td>是</td><td>-</td><td>-</td><td>授权范围。Android、iOS：传入 scope.payment 时被判为非法 scope 并直接失败。</td></tr>
</tbody>
</table>

## 调用示例

```typescript
import { authorize } from '@doubao-dev/framework/api';

await authorize({ scope: 'scope.userLocation' });
await authorize({
  scope: 'scope.healthData',
  options: { types: ['heart_rate', 'step_count'] }
});
```

## 成功返回

无返回字段。

## 错误处理

错误对象和通用错误码见 [通用错误处理](/apps-plugin/docs/js-api/common-errors.md#错误返回)。

### 失败示例

```json
{
  "errNo": 107,
  "errMsg": "user permission denied"
}
```

### 错误码

<table>
<thead>
<tr><th>errNo</th><th>errMsg</th><th>平台</th><th>触发条件</th><th>处理建议</th></tr>
</thead>
<tbody>
<tr><td><code>104</code></td><td><code>invalid parameter</code></td><td>Android、iOS</td><td>传入的 scope 为空或不受支持（如 scope.payment）</td><td>检查并传入受支持的 scope 后重试。</td></tr>
<tr><td><code>104</code></td><td><code>invalid parameter</code></td><td>iOS</td><td>scope.healthData 未传 options.types、列表为空或包含不支持类型</td><td>传入非空且受支持的健康数据类型列表。</td></tr>
<tr><td><code>106</code></td><td><code>system permission denied</code></td><td>Android、iOS</td><td>对应能力的系统权限被拒绝</td><td>引导用户在系统设置中开启对应权限后重试。</td></tr>
<tr><td><code>107</code></td><td><code>user permission denied</code></td><td>Android、iOS</td><td>用户拒绝了本次应用授权</td><td>说明能力用途后再次调用 `authorize` 重新发起授权。</td></tr>
<tr><td><code>114</code></td><td><code>operation cancelled</code></td><td>Android、iOS</td><td>用户取消了授权弹窗</td><td>用户需要时可再次调用 `authorize` 重新发起授权。</td></tr>
<tr><td><code>301</code></td><td><code>network request cancelled</code></td><td>iOS</td><td>授权过程中的网络请求被取消</td><td>确认应用和网络状态后重试。</td></tr>
<tr><td><code>302</code></td><td><code>connection timed out</code></td><td>iOS</td><td>授权过程中的网络连接超时</td><td>检查网络连接后重试。</td></tr>
<tr><td><code>303</code></td><td><code>no network connection</code></td><td>iOS</td><td>当前无可用网络连接</td><td>恢复网络连接后重试。</td></tr>
<tr><td><code>305</code></td><td><code>network failure</code></td><td>Android、iOS</td><td>授权过程中发生其他网络错误</td><td>检查网络连接，稍后重试。</td></tr>
<tr><td><code>112</code></td><td><code>invalid result</code></td><td>iOS</td><td>授权服务返回的数据无法解析</td><td>稍后重试；持续失败时反馈服务端响应异常。</td></tr>
</tbody>
</table>

#### 通用错误码

<table>
<thead>
<tr><th>errNo</th><th>errMsg</th><th>说明</th><th>平台</th></tr>
</thead>
<tbody>
<tr><td><code>102</code></td><td><code>internal error</code></td><td>内部错误</td><td>Android、iOS</td></tr>
</tbody>
</table>

## 平台差异

- **iOS**：网络类失败会细分为 301/302/303/305，并可能返回 112；Android 的网络类失败统一返回 305。
