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/open/login/loginWithDoubaoWidget.md.

loginWithDoubaoWidget

在 Widget 中拉起平台登录和隐私协议授权交互。

使用限制

WARNING

Android、iOS:Android 仅区分 0(隐私流程)与非 0(登录流程),iOS 按当前隐私授权状态路由、仅记录 loginType 不据其分流,两次弹窗与合并弹窗语义均未生效;调用方无法通过 loginType 精确控制弹窗形态。

支持版本

前端库版本不低于 0.0.19。

支持平台

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

支持场景

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

接入准备

前置条件

  • Android:当前豆包账号需已绑定手机号
  • iOS:当前豆包账号需已绑定手机号

使用说明

此 API 只处理 loginType 对应的平台交互,不会返回 login() 的一次性 login_code, 也不会替业务方创建应用插件登录态或完成 MCP Token 交换。

当前豆包账号未绑定手机号时,调用会报错。业务方应捕获错误并降级到自定义登录流程。

业务方仍需按实际场景完成服务端账号登录;MCP 授权登录还需在业务服务端生成三方短期兑换 code, 并通过 postLoginResult 回传最终登录结果。

  • 调用会主动拉起授权登录弹窗,请在用户明确触发登录的交互场景中调用;请勿在无用户操作的后台逻辑中调用。调用报错时,业务方应降级到自定义登录流程。

调用方式

异步 API

loginWithDoubaoWidget(params: LoginWithWidgetRequest): Promise<LoginWithWidgetResult>

入参

名称类型必填默认值约束说明
loginTypeLoginType是--Widget 中需要拉起的平台登录和隐私协议授权组合。Android、iOS:Android 仅区分 0(隐私流程)与非 0(登录流程),iOS 按当前隐私授权状态路由、仅记录 loginType 不据其分流,两次弹窗与合并弹窗语义均未生效。

调用示例

import { LoginType, loginWithDoubaoWidget } from '@doubao-dev/framework/api';

try {
  const { result } = await loginWithDoubaoWidget({
    loginType: LoginType.LoginWithPrivacy
  });

  if (!result) {
    // 用户未完成授权登录,停止后续登录流程。
  }
} catch {
  // 当前账号未绑定手机号或发生其他错误时,降级到业务自定义登录流程。
  await startCustomLoginFlow();
}

成功返回

名称类型必返说明
resultboolean是所选平台交互是否成功完成。

`true` 仅表示 `loginType` 指定的登录或隐私协议授权交互已完成,
不代表三方业务账号登录或 MCP 授权已经完成。

返回示例

{
  "result": true
}

错误处理

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

失败示例

{
  "errNo": 112,
  "errMsg": "invalid result"
}

错误码

errNoerrMsg平台触发条件处理建议
112invalid resultAndroid状态查询成功但返回关键数据缺失(如手机掩码)手机掩码缺失时降级到自定义登录流程;其他情况可稍后重试,持续失败时反馈服务端响应异常。

通用错误码

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

平台差异

  • Android:状态查询成功但关键数据缺失返回 112;其他失败统一返回 102。
  • iOS:失败统一返回 102。