JS-SDK认证接入说明

概述

研学开放平台目前支持以JS-SDK的方式集成第三方应用。开发者通过集成开放平台JS-SDK，调用SDK相应的方法来实现双方的认证授权。

以获取开放平台用户信息为例，业务流程如下：

时序流程如下：

JS-SDK 简介

开放平台JS-SDK 是知网研学开放平台面向开发者提供的网页开发工具包，旨在帮助开发者快速集成平台功能，提高开发效率。通过使用JS-SDK开发者可以轻松地调用开放平台提供的各种接口，从而实现如：用户登录、数据流转、图片上传等功能。

本说明文档详细介绍了 JS-SDK 2.0.0的接入步骤、基础接口及使用方法，帮助开发者顺利完成平台对接和功能开发。以下内容将从JS-SDK 的引入、配置、功能调用等方面进行详细讲解，确保开发者能够快速上手并解决常见问题。

JS-SDK 鉴权

步骤一：引入 JS-SDK

在需要调用 JS 接口的页面中引入开放平台提供的JS-SDK。

<script type= "text/javascript" src="http://openx--cnki--net--https.cnki.mdjsf.utuvpn.utuedu.com:9000/sdk/openx-jssdk-2.0.0.js"></script>

步骤二：通过 config 接口注入权限验证配置

let openxSDK;
const check = async() => {
    try {
        // 向开发者的后台服务发起请求以获取签名信息
        const res = await fetch('/****/sign', {
            method: 'GET',
            headers: {
                'Content-Type': 'application/x-www-form-urlencoded'
            },
            body: JSON.stringify({
                url: window.location.href// 签名用的 URL 必须是调用 JS 接口页面的完整地址，并且与申请 appid 时填写的主站域名一致。
            })
        })
        const res = await res.json()
        if (res.code === 0) {
            const { appid, noncestr, signature, timestamp } = res.data
            openxSDK = openx.config({
                appid, // 开放平台申请的 appid
                timestamp, // 必填，生成签名的时间戳
                noncestr, // 必填，生成签名的随机串
                signature// 必填，签名
            })
            await openxSDK.ready() // 通过 ready 接口处理成功验证
            console.log('权限配置成功，SDK 已准备就绪')
        } else {
            console.error('签名验证失败', res)
        }
    } catch (error) {
        console.error('获取签名信息失败', error)
    }
}
check(); // 执行签名验证

注意事项：开发者需要在后端自行实现签名算法，以确保签名的安全性和合法性。 签名算法详见开发文档：知网研学开放平台文档-研学开放平台JS-SDK签名算法 (opens new window)

步骤三：通过 ready 接口处理成功验证

    await openxSDK.ready();
    console.log('SDK 已经成功初始化，可以进行后续操作');

授权认证

在开放平台创建好应用后，如果希望获取知网用户信息，则可以为应用配置授权认证流程。

授权流程：

流程说明：

• 上图中1由接入方前端发起。
• 上图中4接入方需要在服务端实现现有用户体系与知网用户的绑定操作。

方法描述

openx.login() 方法用于发起用户的授权登录，该方法会根据传入的 openId 参数，获取并返回用户信息。如果未传入 openId ，SDK 将使用默认的登录流程进行授权。

示例：

    const res = await openxSDK.login(openId)
    console.log(res)
    /*{
        "openId": "041e3ecb33ee431b876e95999cfeb5c8",
        "nickName": "知网研学用户9722d1",
        "userName": "charlie"
    }*/

注意事项

1. 如果传入的 openId 在开放平台中未注册或不存在，将会重新发起授权流程。

权益认证

权益消耗

reduceRights 接口用于消耗用户在平台上的权益。开发者可以调用此接口来实现用户权益的扣减操作。

示例代码：

const res=await openxSDK.reduceRights();
if (res.code===200) {
    console.log('权益消耗成功');
}

开放能力

1. 图片上传

开发者可以通过 uploadImage 接口将图片上传到开放平台，适用于需要上传用户图片资料等场景。

示例代码：

const res=await openxSDK.uploadImage();
if (res.code===200) {
    console.log('图片上传成功，图片 URL:', res.content);
} else {
    console.error('图片上传失败', res);
}

2. 数据埋点

开放平台统一了埋点规则，确保所有页面在事件追踪时使用相同的格式和参数。这样一来，开发者可以遵循一致的规则进行埋点，使数据采集和分析更加简便。

示例代码：

// 发送给开放平台埋点系统 异步任务，无须关注回调结果
openxSDK.updateTrack({
    event_id: 'click_button', // 埋点事件 id
    event_target: 'submit_button', // 埋点事件目标
    event_secondary_id: 'secondary_action', // 次级事件 id
    event_secondary_target: 'secondary_target'// 次级事件目标
});