ynkszx-pc-study-player 0.0.1

package/README.md

@@ -0,0 +1,396 @@
+# 介绍
+
+- `ynkszx-pc-study-player`用于点播课的实时学时监管。
+- **如果您需要的是的无内置播放器的 SDK，请先安装好插件后再看文档最后的“无内置播放器 SDK”。**
+
+## 运行环境：
+
+- 主流的浏览器环境（edge、谷歌、火狐、safari 等），不支持在**IE 浏览器**中使用
+- 不支持在移动端的浏览器上使用，可能会出现交互异常
+- 支持 Vue、React 等主流框架，也可直接运行在原生 js 的项目上
+
+## 内置验证规则
+
+- 小程序扫码人脸验证
+- 验证码验证
+- 活体验证
+- 滑块验证
+- 身份证后四位验证
+
+# 安装
+
+## CDN
+
+如果您的项目中没有使用模块化开发，请直接看`cdn使用`。
+
+## npm
+
+```shell
+npm i ynkszx-pc-study-player
+```
+
+## yarn
+
+```shell
+yarn add ynkszx-pc-study-player
+```
+
+## pnpm
+
+```shell
+pnpm add ynkszx-pc-study-player
+```
+
+# 使用
+
+**注意：请确保 dom 加载完成后再实例化插件！！！**
+
+## 模块化
+
+以下是`typescript`使用示例，`javascript`请自行删除类型定义即可
+
+```typescript
+import { StudyPlayer, type Option } from "ynkszx-pc-study-player";
+
+// 引入样式
+import "ynkszx-pc-study-player/style";
+
+const options: Option = {
+  // 参数见下方Option说明
+};
+const player = new StudyPlayer(options); // 具体参数看下方说明
+```
+
+## cdn 使用
+
+版本号可以自行更改，**请保证使用的是最新的版本，最新版修复了一些问题**。
+
+```html
+<link
+  rel="stylesheet"
+  href="https://unpkg.com/ynkszx-pc-study-player@latest/dist/style.css"
+/>
+<script src="https://unpkg.com/ynkszx-pc-study-player@latest/dist/index.js"></script>
+<script>
+  const player = new Study.StudyPlayer(Option);
+</script>
+```
+
+# 参数详解
+
+## Option
+
+类型定义如下：
+
+```typescript
+interface Option {
+  id: string;
+  color?: string;
+  baseUrl: string;
+  appId: string;
+  params: Params;
+  videoUrl: string;
+}
+```
+
+各字段描述如下：
+
+| 字段     | 类型   | 描述                                                                                 | 是否必传 |
+| -------- | ------ | ------------------------------------------------------------------------------------ | -------- |
+| id       | String | 容器盒子的 id，该元素必须手动设置宽高，**请确保该在该 dom 渲染完成后再去实例化插件** | 是       |
+| color    | String | 主题颜色，支持 css 的颜色值                                                          | 否       |
+| baseUrl  | String | 服务器接口地址，如：http://loacalhost:3000                                           | 是       |
+| appId    | String | 用于接口鉴权的 id，对接的时候会提供                                                  | 是       |
+| params   | Object | 见下方 params 描述                                                                   | 是       |
+| videoUrl | String | 视频播放地址，注意后缀不能省略，如`.mp4`、`.m3u8`                                    | 是       |
+
+## params
+
+类型定义如下：
+
+```typescript
+interface Params {
+  appKey: string;
+  courseCode: number | string;
+  courseName: string;
+  duration: number;
+  durationAll: number;
+  sectionCode: number | string;
+  sectionName: string;
+  trainPostCode: string | number;
+  trainPostName: string;
+  trainTypeEnum: "SEND_JXJY" | "SEND_GQPX";
+  idCard: string;
+  studentName: string;
+  studyId?: number | string;
+}
+```
+
+各字段描述如下：
+
+| 字段          | 类型             | 描述                                  | 是否必传 |
+| ------------- | ---------------- | ------------------------------------- | -------- |
+| appKey        | String           | 学时监管的 appkey，授权使用，对接提供 | 是       |
+| courseCode    | String \| Number | 课程 id                               | 是       |
+| courseName    | String           | 课程名称                              | 是       |
+| duration      | Number           | 当前视频时长                          | 是       |
+| durationAll   | Number           | 该岗位的需修学时                      | 是       |
+| sectionCode   | String \| Number | 课程小节 id                           | 是       |
+| sectionName   | String           | 课程小节名称                          | 是       |
+| trainPostCode | String \| Number | 培训岗位 code                         | 是       |
+| trainPostName | String           | 培训岗位名称                          | 是       |
+| trainTypeEnum | String           | 培训类型（值只能是下面两个）          | 是       |
+|               | 'SEND_JXJY'      | 继续教育                              |          |
+|               | 'SEND_GQPX'      | 岗前培训                              |          |
+| idCard        | String           | 学员身份证                            | 是       |
+| studentName   | String           | 学员姓名                              | 是       |
+| studyId       | Number \| String | 学员 id                               | 是       |
+
+# 方法
+
+## destroy
+
+此方法用于销毁播放器。销毁后设置为`null`释放内存：
+
+```ts
+player?.destory();
+player = null;
+```
+
+# 事件
+
+使用示例：
+
+```typescript
+import { StudyPlayer, Event } from "ynkszx-pc-study-player";
+// cdn引用的Event直接使用Sdk.Event
+const player = new StudyPlayer(Option);
+player.on(Event.PLAY, () => {
+  console.log("player");
+});
+```
+
+Event 参数说明：
+
+| 事件名称 | 描述             |
+| -------- | ---------------- |
+| PLAY     | 视频播放触发     |
+| PAUSE    | 视频暂停触发     |
+| END      | 视频播放结束触发 |
+| ERROR    | 视频播放错误触发 |
+
+`Event.ERROR`说明：
+
+```typescript
+player.on(Event.ERROR, (code: number) => {
+  console.log(code);
+});
+```
+
+| code | 描述                   |
+| ---- | ---------------------- |
+| 1001 | 资源请求被用户终止     |
+| 1002 | 媒体请求网路错误       |
+| 1003 | 媒体解码出错           |
+| 1004 | 媒体资源格式不支持播放 |
+| 1005 | 解封装过程出错         |
+| 1006 | 重封转出错             |
+| 1007 | hls 解析错误           |
+| 1008 | MSE 出错               |
+
+# 无内置播放器 SDK
+
+`无内置播放器SDK`只提供了一些方法，界面需要自行开发。
+
+## 基础使用
+
+### 模块化使用
+
+以下是`typescript`使用示例，`javascript`请自行删除类型定义即可：
+
+```ts
+import { StudySDK, type Params } from "ynkszx-pc-study-player";
+
+const sdk = new StudySDK({
+  baseUrl: "xxx",  //服务器接口地址，如：http://loacalhost:3000
+  appId: 'xxx',  // 用于接口鉴权的id，对接的时候会提供
+});
+
+const paramas: Params = {
+  // params参数见上面Params
+};
+sdk.init(params);
+...
+```
+
+### CDN 使用
+
+```js
+<script src="https://unpkg.com/ynkszx-pc-study-player@latest/dist/index.js"></script>
+<script>
+  const sdk = new Study.StudySDK({
+    baseUrl: "xxx",
+    appId: 'xxx',
+  });
+  const paramas = {
+    // params参数见上面Params
+  };
+  sdk.init(params);
+</script>
+```
+
+## 方法说明
+
+**所有方法都是返回`Promise`，对接的时候需要自行判断 api 是否返回状态是`resolve`状态。**
+
+### init
+
+初始化播放
+
+```js
+sdk.init(params);
+```
+
+**`params`字段描述见上。**
+
+**返回值**：
+
+```js
+{
+    progress: "视频观看记录，单位（秒）",
+    studyInfoId: "学习id",
+    ruleType: "验证规则类型，("FACE", "人脸"),("LIVINGBODY", "活体"),("SLIDER", "滑块"),("IDCARD", "身份证"),("NUMBER", "数字")"，
+    initVerify： "是否需要首验证 0否1是",
+    validateId: '验证id'
+    effectiveTm: "验证有效时间(秒)",
+    sdkId: "唯一值"
+}
+```
+
+### play
+
+视频播放的时候调用
+
+```js
+sdk.play({
+    studyInfoId: "xxx", // 学习Id，由init接口返回的，必传
+    countHours： 1111, // 视频当前进度，必传，单位(秒)，
+})
+```
+
+### pause
+
+视频暂停的时候调用
+
+```js
+sdk.pause() {
+   studyInfoId: "xxx", // 学习Id，由init接口返回的，必传
+   countHours： 1111, // 视频当前进度，必传，单位(秒)
+}
+```
+
+### end
+
+视频播放结束调用
+
+```js
+sdk.end({
+   studyInfoId: "xxx", // 学习Id，由init接口返回的，必传
+   countHours： 1111, // 视频当前进度，必传，单位(秒)
+})
+```
+
+### progress
+
+视频播放进度同步，建议每隔 30 秒调用一次
+
+```js
+sdk.progress({
+   studyInfoId: "xxx", // 学习Id，由init接口返回的，必传
+   countHours： 1111, // 视频当前进度，必传,单位（秒）
+   sdkId: 'xxxx' // 唯一值，由init接口返回，必传
+})
+```
+
+返回值：
+
+```js
+{
+    validateId: '验证id',
+    ruleType: '验证类型，("FACE", "人脸"),("LIVINGBODY", "活体"),("SLIDER", "滑块验证"),("IDCARD", "身份证后四位校验"),("NUMBER", "数字验证")',
+    isValidate: "是否要弹框验证（0否1是）",
+    effectiveTm: '验证有效时间(秒)'
+}
+```
+
+### getVerifyInfo
+
+获取验证详情，校验方式为**数字**的时候调用，验证码换一张也调用该接口
+
+```js
+sdk.getVerifyInfo({
+  validateId: "xxxx", // 验证id，由progress返回，必传
+});
+```
+
+返回值：base64 格式的图片
+
+### getVerifyInfoRefresh
+
+倒计时结束验证超时后，重新获取验证方式
+
+```js
+sdk.getVerifyInfoRefresh({
+  validateId: "验证id，由progress返回，必传",
+});
+```
+
+返回值：
+
+```js
+{
+  validateId: '验证id',
+  effectiveTm: '超时时间',
+  ruleType: "验证类型，同上"，
+}
+```
+
+### verify
+
+校验验证，验证类型为滑块、身份证、数字的时候调用该接口校验，校验通过后即可继续播放。
+
+```js
+sdk.verify({
+  validateId: "验证id，由progress返回，必传",
+  ruleValue: "验证值，滑块验证直接传TURE，必传",
+});
+```
+
+### getFaceVerifyInfo
+
+获取验证详情，校验方式为滑人脸、活体验证的时候调用
+
+```js
+sdk.getFaceVerifyInfo({
+  validateId: "验证id，由progress返回，必传",
+});
+```
+
+返回值：
+
+```js
+{
+  qrCode: "base64格式的小程序码图片";
+}
+```
+
+### verifyFace
+
+查询人脸或活体小程序的验证结果，**该接口需要轮训使用**，建议 2 秒执行 1 次。
+
+```js
+sdk.verifyFace({
+    validateId: "验证id，由progress返回，必传",
+    ruleType: "验证类型，("FACE", "人脸"),("LIVINGBODY", "活体")，必传"
+})
+```