资源工坊

开放网页组件 ​

概述 ​

WPS 365 开放平台提供多种网页组件，助力企业快速集成自身系统，与 WPS 能力无缝连接，轻松复用如：agentspace聊天组件、成员信息卡片、人员选择器、分享面板等功能模块，以更低成本构建高效协同的办公体验。

通过在你的网页中引入 WPS 365 开放网页组件 ，可在你的网页中直接使用 WPS 提供的功能。

适用范围 ​

  • 暂时只支持 企业自建应用，后续会支持三方ISV应用。

提醒

由于网页组件，期望是在web端发起授信请求，而 接口签名设计是利用AK/SK进行安全加固手段。前端场景无法使用 接口签名KSO-1(见下图2)

1762323973604

1762328216631

权限配置 ​

组件权限 ​

每个组件，都有独立的权限scope，比如使用agentspace_chat组件，如下图所示。

**注意：**选择权限后，需要申请发布版本后生效，由企业管理员审核版本通过后，列表会显示 已开通 。

1762324705893

可信域名 ​

请填写您需要集成开放组件的业务系统域名。 1762325488352

鉴权流程 ​

以下流程，都基于已创建开放平台应用。

1. 获取 access_token ​

不同的 token 代表了不同的使用者的身份，access_token 分为 用户授权、应用授权 两种方式，不同的开放组件，支持的授权方式不同，组件支持的鉴权类型，请参考每个组件具体介绍。

2. 申请js_ticket ​

js_ticket必须放在服务端进行，防止ticket泄露。

名称类型必填描述
Authorizationstring是值格式 ："Bearer  access_token"
示例："Bearer eyJhbGciOiJxxx.eyJhaWQiOjI4NTc2MTIwNCwiYXRwIjo.yK3HHSDDs"
  • XIDL定义：
curl
GET /openapi/oauth2/jsapi_ticket
header: {
    Authorization: "Bearer access_token"
}

200: {
    "code": 0,
    "msg": "",
    "data": {
        "ticket": "jsYWQ91qMICxQwNrc08blEvCuh3g6PQL1nApgJREkxyidr7/KeAJ2D1LwB3MgtX4ge+yn7nkkH93ZVuC6oh8ZXPgc4d/dPHljsQYatOGzrw=", // (不返回给前端)
        "tag": "bc58134ebe5de56b88a825c8607e8a3b",  // 用于标记ticket，需要返回给前端
        "expires_at": 1732942687 // 过期时间戳
    }
}

3. 生成Signature ​

此步骤，需在开发者业务服务端实现, 通过下列方式生成签名。

再将过程中用于签名的timestamp、nonceStr、tag、url ，以及生成的signature返回给前端。

signature拼接规则

noncestr=${nonce}&ticket=${jsapi_ticket}&timestamp=${timestamp}&url=${url}

• noncestr 为随机字符串。e.g. 1q9w0n6wc71

• ticket 上一步骤申请js_ticket /openapi/oauth2/jsapi_ticket 中的返回的ticket参数

• timestamp 时间戳（秒）。取当前时间即可

• url 当前集成wps 组件的页面url。不要包括#、?后面的参数。

nodejs 示例

typescript
import { createHmac } from 'crypto'

const genSignature = function (
  jsapi_ticket: string,
  nonce: string,
  timestamp: number,
  url: string,
) {
  const signature = createHmac('sha256', app_secret)
    .update(`noncestr=${nonce}&ticket=${jsapi_ticket}&timestamp=${timestamp}&url=${url}`)
    .digest('hex')

  console.log('signature', signature)
  return signature
}

4. 配置鉴权 ​

此步骤，在开发者的业务系统中实现

javascript
// 1. 由于服务端返回 { app_id, signature, noncestr, timestamp, tag, url }
// 2. 可以监听授权错误场景，建议开发者自行处理失败的场景，当然也可使用OpenSDK.config({...}).catch()方式捕获授权失败
OpenSDK.addEventListener(OpenSDK.Events.AuthError, (err) => {
  console.error('AuthError', err)
})
// 3. OpenSDK 鉴权
await OpenSDK.config({
  signature, // 签名
  appId: app_id, // 应用 appId
  timestamp, // 时间戳（秒）
  nonceStr: noncestr, // 随机字符串
  scopes,
  tag,
  url,
})

TIP

在OpenSDK.config接口中使用的nonceStr、timestamp、url需要确保与生成signature时使用的值保持一致，否则无法鉴权通过

调用组件，以及组件参数，请参考每个组件的接入文档。

常见错误 ​

h5_addrs is not configured: 未配置h5安全域名

referer_url is not in the whitelist: 安全域名校验失败，检查应用的安全域名配置。

ValueInvalidError: 接口参数错误

ticket not found: js_tikect 不存在或已过期

signature mismatch: 签名验证失败

get app info failed: 无法获取应用信息

token is not a jsapi_access_token: 传入的 token 不是 jsapi_token