# 播放器 SDK API 概要设计

## 概述

该设计为概要设计，包含了 IOS/Android/Web 提供的一些基本能力以及接口大致的原型，这些设计中没有考虑到各平台不同的差异，各平台应该根据各平台的特点加以细化。

本文档假设调用时生成使用一个名为 player 对象，以下会以该对象为主，设计相关的接口，在文档中的格式表现为 `player.[接口]([参数]:[参数类型]) => 返回类型`

## 控制接口

### player.setUrl(url: String) => null

设置播放器播放的 url，该 url 为普通的 url，应支持 http/https/file 协议

### player.setPoster(url: String) => null

设置播放器在未播放时显示的图片，url 是图片的地址，应支持 http/https/file 协议

### player.setAppId(appId: String) => null

设置 播放器的 AppId，这个 id 是 xstore 点播提供的 AppId，通过该 id 和 videoId 则可

### player.setFileId(fileId: String) => null

设置视频的文件id，该 id 是播放视频的文件的 id，

### player.setPlayableVideoDuration(sec: long) => null

设置视频允许播放的时长，单位为秒。请加载视频以及播放时以此为节点。

### player.showCommentInput(show: boolean) => null

显示评论输入框，应包含输入框和发送按钮。这个输入框的内容可以通过事件 `player.onCommentTextSent()` 的事件中获取

### player.setStartAd(url: String) => null

设置一个片头广告URL，在调用视频`player.play()`方法之后，会先播放广告之后在播放正片。

### player.setStartAdVideoId(id: String) => null

设置片头广告的 video id，该 id 是 xstore 点播提供的视频id，请通过该 id 取得实际的视频 url。

### player.setEndAd(url: String) => null

设置一个片尾广告，在播放视频之后播放。

### player.setEndAdVideoId(id: String) => null

设置片尾广告的 video id，该 id 是 xstore 点播提供的视频id，请通过该 id 取得实际的视频 url。

### player.setPausedAd(url: String) => null

传入一张图片 URL，在视频暂停时在播放器中间显示。

### player.load() => null

设置 url 完成之后，在未播放之前，调用此方法可以预加载视频

### player.play() => null

播放视频，如果有广告则先播放广告

### player.play(ignoreAd: boolean) => null

播放视频，如果视频没有调用 load() 方法加载，则先加载视频再播放，ignoreStartAd == true时 会跳过片头广告直接播放视频

### player.pause() => null

暂停视频

### player.stop() => null

停止视频的播放，将 seek 指针指向最后。

### player.seekTo(msec:long) => long

设置快进/快退的时间点，msec 是微秒，如传入的参数小于0，退到 0s，如果大于视频的总时长，到最后，返回值返回实际到达的毫秒数。

### player.getDuration() => long

返回视频的时长

### player.getCurrentPosition() => long

返回当前视频播放的位置，时间单位为毫秒

### player.getBufferedRange() => {"from": long, "to": long}

返回当前视频预加载缓存的时间范围，

### player.getBufferedEnd() => long

返回当前视频预加载的时间的结束时间点。

### player.getBufferedPercentage() => float

返回加载的百分比，该值应该大于0，小于1，精确到小数点后 2 位

### player.setVolume(volume: float) => null

设置音量 该值应该大于0，小于1，精确到小数点后 2 位

### player.mute() => null

设置静音。同时记录当前音量，当使用 resumeVolume 时设置回静音前音量。

### player.resumeVolume() => null

从静音状态返回

### player.isMuted() => boolean

返回当前视频是否静音

### player.enterfullScreen() => null

设置全屏播放

### player.existFullScreen() => null

退出全屏播放

### player.setSpeed(speed: float) => null

设置播放的速度

### player.isPlaying() => boolean

视频正在播放

### player.isPaused() => boolean

视频是否暂停

### player.isStop() => boolean

视频是否停止

### player.isStartAdPlaying() => boolean

片头广告是否正在播放中

### player.isEndAdPlaying() => boolean

片尾广告是否在播放中

### player.isPausedAdShow() => boolean

暂停广告是否显示

### player.setFloatingComments(floatingTextArray: array) => null

设置弹幕，弹幕为一个对象，包含了各所有弹幕列表，每一条弹幕应该包含弹幕的内容、弹幕出现的时间点以及弹幕的格式。具体弹幕的对象类似：

```json
{
        "text": "弹幕内容",
        "style": {
            "color": "auto",
            "fontSize": "auto",
            "opacity": 1
        },
        "speed": 1
    }
```

### player.addFloatingComments(floatingTexy: array) => null

将列表中的弹幕增加到当前弹幕列表中进行展示。

### player.stopStartAd() => null

立刻停止播放片头广告

### player.stopEndAd() => null

立刻停止播放片尾广告

### player.hidePausedAd() => null

隐藏正在显示的暂停广告费

## 事件接口

以下接口的参数均为一个 function(JS)/Interface(Java/IOS)，当在指定事件时触发。这些接口会传入一个 Event 类，Event 类在每个平台可能不甚一致，例如在 JS 平台，Event 应该符合 [W3C标准](www.w3.org/TR/DOM-Level-2-Events/events.html#Events-EventTarget)，而在 Android 平台，则可能会传入一个 View 对象。请具体的平台按照实际的情况进行设计

这里描述的时间只是必须支持的时间类型，各平台可能会有更详细的事件设置，例如在 js 中，由于准备播放器使用的是异步的实现，因此还会有类似`player.ready()`的时间。

### player.onLoadStart(eventListener: function) => null

当内容开始加载时触发

### player.onPlay(eventListener: function) => null

在播放时触发，包括暂停了之后播放点击播放，因此，该事件对象中应包含播放时的开始时间点。

### player.onPlayMain(eventListener: function) => null

播放正片时触发的事件。

### player.onPause(eventListener: function) => null

在暂停时触发，传入到时间监听器的事件对象应包含当前暂停的时间信息。

### player.onSeekedTo(eventListener: function) => null

当调用 Seek 方法（包括在界面上点击到指定时间后）触发的事件。

### player.onStop(eventListener: function) => null

当视频播放结束时触发，发生调用了`player.stop()`方法以及视频自然播放停止时触发。

### player.onStopMain(eventListener: function) => null

当正片播放完时触发事件。

### player.onEnterFullScreen(eventListener: function) => null

当进入全屏时触发事件

### player.onExistFullScreen(eventListener: function) => null

当退出全屏时触发时间

### player.onError(eventListener: function) => null

在播放发生错误时触发，例如传入了不支持格式的视频后调用 `player.load()` 或者 `player.play()` 播放错误的时候。

## 弹幕

关于弹幕输入框，在某些版本，例如 Web 版本中不嵌入到播放器中了，仅提供显示，但需要给予一定的例子使得用户有快速开发的能力。

移动端由于需要嵌入相关的按钮和弹窗等需要和播放器本身耦合的比较深，由移动端小组单独设计。

## 用户信息收集

请定时向服务器接口提供以下数据信息：

```javascript
// 以下参数所有的字段均允许为空
{
    "terminal": {
        "platform": "", // 播放器所属平台，包括 设备商/机器版本/操作系统版本，例如 HUAWEI/P20/Android O, 浏览器的话请使用 user-agent
        "app": "", // APP 名字或者 浏览器的 host
        "network": "WIFI/Mobile", // 当前网络环境数据，WEB端取不到则不发送
        "userHash": "", // 在 APP 安装，WEB 端首次使用播放器时，生成一个uuid记录到本地（APP存储到硬盘，浏览器存储到cookies中，cookies 的过期时间请设置为1个月
        "time": "" // 获取设备终端时间
    },
    "event": "", // 上报的时机，包含 START/MAIN_START/INTERVAL/MAIN_END/END
    "video": {
        "videoUrl": ""， // 当前视频的 url
        "startAddUrl": "", // 片头广告 url
        "endAddUrl": "", // 片尾广告 url
        "pauseAddUrl": "", // 暂停广告 url
        "videoId": "", // 视频 id
        "startAdVideoId": "", // 片头广告 id
        "endAdVideoId": "", // 片尾广告 id
        "currentPosition": "", // 当前用户播放的时间点
        "currentStatus": "", // Playing/Pause/Stop/StartAd/EndAd
        "volume": "", // 当前音量
        "speed": "", // 当前的倍速
        "bufferedTimeRange": {
            "from": "", // 当前缓存的数据，开始的时间点
            "end": "" // 当前缓存的数据，结束的时间点
        },
        "playableVideoDuration": "" // 播放器可以播放的视频时间
    }
}
```