JS 接入指南

我的收藏

本文介绍如何进行 JS 接入。您也可以下载 JS 代码示例。

前提条件

抖音 App 10.4.0 以上版本才能使用 JS SDK。

操作步骤

第一步：申请网站应用

如还未申请过网站应用，请先申请网站应用。网站应用申请审核通过后，可以获得该应用所属的 Client Key 和 Client Secret。具体操作，请参见创建移动应用或网站应用。

第二步：申请 JSBridge 能力

在网站应用列表里选择对应的应用，点击展开页面左侧的「能力管理」，找到 JSBridge 选项卡，申请所需的 JSBridge 能力。

第三步：填写 JSBridge 安全域名

在该应用管理中心的基础信息选项卡，修改 JSBridge 安全域名。

安全域名用于初始化验证签名过程，只有在安全域名内的页面才能通过签名验证。

第四步：引入 JS SDK 文件

在页面中引入 JS 文件（支持模块加载。请升级到最新版 1.0.10，否则无法兼容抖音极速版）。

注意：低版本抖音是无法调起半屏授权的，所以请先判断抖音版本号，在符合要求的版本上面再使用该功能。

•

openConfig 验签上线抖音版本为 10.4.0

•

showOpenAuth 上线时间抖音版本为为10.8.0。

第五步：通过 config 方法验证签名

const sdk = window.DouyinOpenJSBridge;
const timestamp = String(parseInt(Date.now() / 1000)); // 类型为 String
const nonceStr = ""; // 生成签名用的随机字符串
const url = location.href;

sdk.config({
  params: {
    client_key: clientKey, // clientKey在你的网页应用申请通过后得到
    signature: calcSig(timestamp, nonceStr, url), // 服务端计算的签名，该签名被抖音开放平台验证通过后方可调用jsb方法
    timestamp, // 时间戳
    nonce_str: nonceStr,
    url, // 为应用申请的 JSB 安全域名下的链接，需要携带协议。e.g. https://jsb.security.domain/page.html
  },
});

警告
url参数的值必须是当前页面的url，如果填入的url不相符，可能导致鉴权失败或后续调用showOpenAuth接口失败。

验证签名的详细信息请参见验证签名。

第六步：通过 ready 方法处理成功验证

sdk.ready(() => {
  // Config Ready回调
});

第七步：通过 error 方法处理失败验证

sdk.error((res) => {
  // Config error回调，res示例：{ status_code: 5, status_msg: '错误信息' }
});

第八步：调用申请通过的 JSBridge 能力

// 授权JSB
sdk.showOpenAuth({
  params: {
    ... // JSB方法参数
  },
  success: res => {
    // 成功回调
  },
  error: res => {
    // 失败回调
  }
});
// 其他JSB方法
sdk.bridge.call('jsbName',{ // JSB方法名，如 music
  params: {
    ... // JSB方法参数
  },
  success: res => {
   // 成功回调，必需
  },
  error: res => {
  // 失败回调，必需
  }
});

常见问题

error 方法错误码

错误码	描述
4	服务器内部错误，例如网络错误
5	参数不合法
3073	请求参数为空
16386	host不合法
16387	js ticket不合法
16388	签名不正确

Host 不合法

确认页面所在域名，是否与应用配置的 JSB 安全域名一致。JSB 安全域名可在「抖音开放平台首页」>「右上角控制台」>「我的应用」>「网站应用」>「设置」> 「应用信息」>「JSBridge 安全域名」中进行配置和修改。

签名不正确

下载 React 示例代码，查看签名算法文档，确认是按照配置与示例进行签名生成。

常见的签名不正确的原因有：

•

timestamp 类型为 String。

•

sdk.config 用的 URL 必须是调用 JS 接口页面的完整 URL（但是不包括#及后面部分）。