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/authorize.md.

authorize

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

扫码预览

扫码预览 authorize

使用限制

WARNING

Android、iOS:传入 scope.payment 时被判为非法 scope 并直接失败;依赖 scope.payment 发起授权的调用无法成功。

支持版本

前端库版本不低于 0.0.18。

支持平台

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

支持场景

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

接入准备

权限要求

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

授权行为

  • 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

authorize(params: AuthorizeRequest): Promise<object>

入参

名称类型必填默认值约束说明
optionsHealthDataAuthorizeOptions否--权限扩展参数;仅 scope.healthData 生效,用于传入 HealthKit 读取类型,其他 scope 会忽略该字段。
options.typesHealthDataType[]否--健康数据类型列表;用于申请对应的 HealthKit 读取权限。
scopeScope是--授权范围。Android、iOS:传入 scope.payment 时被判为非法 scope 并直接失败。

调用示例

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

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

成功返回

无返回字段。

错误处理

错误对象和通用错误码见 通用错误处理。

失败示例

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

错误码

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

通用错误码

errNoerrMsg说明平台
102internal error内部错误Android、iOS

平台差异

  • iOS:网络类失败会细分为 301/302/303/305,并可能返回 112;Android 的网络类失败统一返回 305。