微信觀看小程式SDK 3.10

DEMO 位址

demo 下載位址

產品介紹

概述

polyv小程式SDK為微信小程式提供了直播播放、點播播放、文件繪製等功能。且提供了一套元件，供用戶靈活組合自己的業務邏輯。

配置微信直播權限

SDK 播放直播使用了微信 live-player 和連麥 live-pusher，需要先通過類目審核（詳見微信觀看小程式 SDK 類目申請資質要求），再在小程式管理後台，「開發」-「介面設定」中自助開通對應元件權限。

功能特性

閱讀對象

本文為技術文件，需要閱讀者：

• 具備基本的小程式開發能力
• 準備接入Polyv影片雲或已接入的客戶
• 對Polyv影片雲使用方法有基礎的了解

使用步驟

開發準備

取得Access Key

登入保利威直播後台 - 雲直播 - 開發設定 - 身分認證

微信介面白名單設定

request合法域名
https://miniapp.agoraio.cn
https://uni-webcollector.agora.io
https://router.polyv.net
https://api.polyv.net
https://prtas.videocc.net
https://rtas.videocc.net
https://hls.videocc.net
https://player.polyv.net
https://livestatic.videocc.net
https://livejson.polyv.net
https://live.polyv.net
https://doc-2.polyv.net
https://doc.polyv.net
https://img.videocc.net
https://liveimages.videocc.net

使用连麦功能需加上以下域名：
https://uap-ap-web-1.agora.io
https://uap-ap-web-2.agoraio.cn
https://uap-ap-web-3.agora.io
https://uap-ap-web-4.agoraio.cn
https://report-ad.agoralab.co
https://rest-argus-ad.agoralab.co
https://uni-webcollector.agora.io

https://cloud.tencent.com
https://yun.tim.qq.com
https://webim.tim.qq.com

socket合法域名
wss://chat.polyv.net
wss://miniapp.agoraio.cn

SDK 使用方法

SDK 使用 TypeScript 程式碼，因此需要下載最新的開發者工具才能支援。原生支援 TypeScript

SDK 提供了自訂元件，Polyv 提供一套完整的業務邏輯，供使用者開箱即用。同時也提供了 player 播放元件、ppt 文件元件、chatroom 聊天室元件等，供使用者靈活組合自己的業務邏輯。

在使用之前需要在app.js的onLaunch中呼叫setApp方法

方法一（推薦）：傳入 verifyUrl 驗證介面

import plv from '*/sdk/core/index';
onLaunch() {
    plv.setApp({
        apiId: '',
        verifyUrl: ''
    });
}

verifyUrl 驗證介面規則

（1）小程式請求 verifyUrl 介面時，會帶上下列參數（參數數量/參數名稱不固定）。需將所有除 sign 以外的參數依字母順序排列後，配合 appSecret 按規則進行 MD5 加密，並回傳給小程式。

請求參數說明

回應參數說明

verifyUrl 介接 PHP 程式碼範例：

<?php
$appSecretKey = 'Your appSecretKey';
$sign = $_GET['sign'];
$appId = $_GET['appId'];
$timestamp = $_GET['timestamp'];

// 获取url query并转换成数组
parse_str($_SERVER["QUERY_STRING"], $params);

// 获取除sign外的其他参数的拼接字符串
$concated = sort_param($params);

// STEP 1
// 计算接口请求是否合法
$outPutData = '';

$verifyUrlSign = strtoupper(md5("plyMinApp".$concated."plyMinApp"));
if ($sign != $verifyUrlSign) {
  $outPutData = '{"code": 200, "message" : "invalid sign", "status": "error", "data": ""}';
  echo($outPutData);
  return;
}

// STEP 2
// 输出正确sign返回给小程序
$outPutSign = strtoupper(md5($appSecretKey.$concated.$appSecretKey));
$outPutData = '{"code": 200, "message" : "", "status": "success", "data": {"sign": "'.$outPutSign.'"}}';
echo($outPutData);


/**
 * 将参数按照ASCKII升序 key + value + key + value ... +value 拼接
 * @return [type] [description]
 */
function sort_param($params){

  ksort($params);

  $sort_result = "";

  foreach ($params as $key => $val) {
    if(!is_null($val) && $key != 'sign'){
      $sort_result=$sort_result.$key.$val;
    }
  }
  return $sort_result;
}

?>

(2)verifyUrl 驗證

校驗 sign 規則：

1.concated 的值為將參數 appId、timestamp 及其他參數按照 ASCII 升序以 key + value + key + value ... + value 的方式拼接。

2.verifyUrlSign 取值 plyMinApp${concated}plyMinApp字串拼接後的大寫 MD5 值

$verifyUrlSign = strtoupper(md5("plyMinApp".$concated."plyMinApp"));

成功範例

{
    "code":200,
    "status":"success",
    "message":"",
    "data":{
        "sign":"3DDE7222C4264F225931053A661889BA"
    }
}

異常範例

{
    "code": 400,
    "status": "error",
    "message": "invalid signature.",
    "data": ""
}

方法二：傳入 polyv 雲直播的 access key

由於在小程式程式碼中，apiSecret 是以明文顯示的，存在小程式被反編譯的風險。因此建議使用方法一。

import plv from '*/sdk/core/index';
onLaunch() {
    plv.setApp({
        apiId: '',
        apiSecret: ''
    });
}

元件的使用

一、使用 polyv 元件。可參考 demo 的 polyv 目錄

1. 將 SDK 程式碼複製到自己的專案中，並在使用到 SDK 的頁面 JSON 檔案中引入元件。

   {
     "usingComponents": {
        "polyv": "*/sdk/components/polyv/polyv"
     }
   }
   

2. 在 WXML 中使用 polyv 組件

   <view>
       <polyv />
   </view>
   

3. 在頁面的 onload 中呼叫 init 方法，在 onUnload 中呼叫 destroy 方法

init 方法初始化觀看，取得頻道詳細資訊、初始化 socket 事件等。

import plv from '*/sdk/core/index';
// onLoad
onLoad() {
    const options = {
      channelId: '', // 频道ID
      openId: '', // 用户openId
      userName: '', // 用户名
      avatarUrl: '', // 用户头像
      param4: '', // 自定义参数
      param5: '', // 自定义参数
    };
    plv.init(options);
}
// onUnload
onUnload() {
   plv.destory();
 }

二、靈活組合元件。可參考 demo 的 polyv-sub

1. 在使用到 SDK 的頁面 JSON 檔案中引入元件

   {
     "usingComponents": {
        "player": "*/sdk/components/player/player",
           "ppt": "*/sdk/components/ppt/ppt",
        ...
     }
   }
   

2. 在 wxml 中使用元件，傳入必要的參數。

   <view>
       <player
      videoOption="{{ videoOption }}"
      bind:onLiveStatusChange="playerLiveStatusChange"
    />
       <ppt />
   </view>
   

3. 在頁面的 onload 方法中呼叫 init 方法。

   import plv from '*/sdk/core/index';
   Page({
       onLoad() {
           const options = { ... };
           options.plvInsideUse = true; // 区分是学一学还是sdk, 当为 true 时开启抽奖模块。
           plv.init(options)
               .then(data => {
                   const { detail, chat } = data;
                  // 处理业务逻辑
               })
               .catch(err => {
                           // 异常处理
               });
       },
       onUnload() {
          plv.destory();
       }
   });
   

元件詳細說明

使用以下元件之前，都需要先在 JSON 中透過 usingComponents 欄位引入。

1. polyv 元件

參數介紹

 <polyv
   bind:userBanned="handleUserBanned"
   bind:onError="handlePolyvError"
   allowDanmu="{{ false }}"
   skinAlwaysShow="{{ true }}"
   usePlayerSkin="{{ false }}"
   hasAnswerCard="{{ true }}"
 />

2. player 播放器元件

player 元件可以播放直播和點播。直播使用 live-player，模拟器不能播放，查看效果请用真机。 點播模擬器不能播放加密视频，查看效果请用真机。

參數介紹

注意：skinAlwaysShow 的優先級高於 usePlayerSkin，若將 skinAlwaysShow 設為 true，則 usePlayerSkin 參數將失效。

<player
 videoOption="{{ videoOption }}"
 allowDanmu="{{ false }}"
 skinAlwaysShow="{{ true }}"
 usePlayerSkin="{{ false }}"
 bind:onLiveStatusChange="playerLiveStatusChange"
 bind:playerVodProgress="playerVodProgress"
 bind:onVodEnd="playerVodEnd"
 bind:onLiveVodEnd="playerVodEnd"
 bind:onError="playerError"
/>

// ###### 播放直播或者暂存视频 #######
videoOption = {
   mode: 'live',
   uid: userId, // 直播频道uid
   cid: channelId, // 直播频道channelId
   isAutoChange: true, // 自动切换直播和暂存。
   vodsrc: '', // 指定回放地址。有暂存视频的情况下，传入暂存视频的mp4或者m3u8。
   pipMode: '', // 是否使用小窗模式，默认为undefined。相关参数设置详情参考注意2.2
   forceVideo: false, // 是否强制使用video标签作为播放器(播放m3u8)，建议使用live-player
   statistics: { // 播放器自定义统计参数, 如需添加param4、param5参数，详情见下面init方法详解
     param1: 'param1', // 用户ID
     param2: 'param2', // 用户昵称
   },
   // logoConfig: {
   //   enable: false, // 是否显示logo
   //   position: 'tl',// logo位置1 左上，2 右上（默认）3左下 4 右下
   //   opacity: 0.5, // 透明度
   //   src: '' // logo图片的url
   // }
};

// 直播状态改变: 只有在mode为live时才会触发。
playerLiveStatusChange(e) {
    const status = e.detail.status;
    if (status === 'live') {
      // 开始直播
    }
    if (status === 'end') {
      // 结束直播
    }
}

// 获取回放播放进度
playerVodProgress(e) {
  console.info(e.detail.currentTime, '----currentTime---');
}

// 播放器异常捕获
playerError(e) {
  console.info(e.detail, '-----e-----');
}

/*
* 回放播放结束事件
* onVodEnd: 点播回放列表播放结束触发，返回当前播放结束点播视频vid
* onLiveVodEnd: 直播暂存播放结束时触发，返回当前暂存视频播放地址
*/
playerVodEnd(e) {
  console.info(e.detail.curVodVid, '---curVodVid---');
}

// ###### 播放点播视频 #######
videoOption = {
    mode: 'vod',
    vodVid: '' // 播回放时vodVid为videoPoolId
};
// 在mode为vod时，从点播切换到直播状态，云课堂和普通直播监听直播开始的方法不同。
// 1. 普通直播通过轮询api.getOrdinaryLiveStatus(stream)获取当前的状态
// 2. 云课堂通过chat.on(chat.events.SLICESTART, () => {})监听直播开始

注意：

2.1 skinAlwaysShow 與 usePlayerSkin 的優先順序

skinAlwaysShow 的優先順序高於 usePlayerSkin，若將 skinAlwaysShow 設為 true，則 usePlayerSkin 參數將失效。

2.2 pipMode

參數範圍與觸發條件請參考官方API live-player組件參數。官方說明基礎庫需升級至2.11.0才支援小窗功能，建議登入公眾號平台 -> 設定 -> 基礎庫最低版本設定 進行升級。

3. PPT 文件元件

參數介紹

<ppt
   chatData="{{ detail }}"
   videoId="{{videoId}}"
   vidCurrentTime="{{vodPlayerProgress}}"
   pptSize='{{pptSize}}'
/>

// 直播时传入chatData
// 播放点播时传入回放的videoId和当前回放播放时间

4. concat 連麥元件

參數介紹

<concat
    id="test"
 channelDetail="{{ channelDetail }}"
    applyData="{{ applyData }}"
    bind:show="handleShowConcatApply"
    bind:refreshStatus="handleRefreshStatus"
    bind:stop="handleStop"
/>

 //js
 // 监听当前房间连麦状态
 // 弃用
 handleShowConcatApply(data) {
   // data.detail.status为open/close
   // open: 当前房间已开启连麦
   // close: 当前房间未开启连麦
 },

 // 监听当前用户连麦状态
 // 只有在房间开启了连麦功能后，用户才能进行连麦
 handleRefreshStatus(data) {
   // data.detail: {
   //  show: true/false, // 是否能连麦
   //  type: 'apply'/'cancel'/'stop', // 当前连麦类型：未举手/已举手/连麦中
   //  txt: '' //对应连麦类型：申请连线/取消申请/挂断连线
   //}
 },

 // 结束连麦
 handleStop(data) {
   console.info(data.detail, '---stop----');
 }

連麥組件相關方法說明

• apply

說明：連線控制方法，「舉手」/「取消申請」都需要呼叫此方法，呼叫此方法後元件會判斷當前連線狀態，觸發對應的事件。 - stop

說明：掛斷連線

5. chatroom 聊天室元件

<chatroom bind:onTapBulletin="handleShowBulletin" />

handleShowBulletin() {
  console.info('===点击聊天室公告按钮触发====')；
}

6. quiz 諮詢提問元件

<quiz />

7. playback 往期元件

參數介紹

<playback
    playbackList="{{ playbackList }}"
    nextVod="{{ currentVodId }}"
 bind:onTapPlayback="handlePlayback"
/>

// 回放列表通过api.getPlayBackVideos(channelId)获取
// 播放下一个回放，nextVod传入当前的回放videoPoolId
// 点击某个回放时，通知player播放
handlePlayback(e) {
    const { videoPoolId, videoId } = e.detail;
}

8. 章節元件

參數介紹

<chapter
    bind:onTapChapter="handleChangeChapter"
 vodCurTime="{{ vodPlayerProgress }}"
 chapterList="{{ chapterList }}"
/>

// 回放列表通过api.getChapterRecords(channelId)获取
// vodCurTime: 当前播放器的播放时间
// onTapChapter
handleChangeChapter(e) {
 const chapter = e.detail.chapter;
}

9. menu-custom 自訂選單元件

參數介紹

10. sign 互動功能簽到元件

<sign bind:onSignShow="handleSignShow" />

handleSignShow() {
  console.info('====收到签到开始事件，显示签到弹窗时触发====');
}

11. question 互動功能問卷組件

<question zIndex="2000" />

12. answer-card 互動功能答題卡元件

<answer-card
  class="c-answer-card"
  answerCardSize="{{ answerCardSize }}"
  bind:onAnswerCardShow="handleShowAnswerCard" />

handleShowAnswerCard() {
  console.info('=====收到答题事件，显示答题卡弹窗时触发====');
}

13. lottery 互動功能抽獎元件

<lottery zIndex="{{ lotteryIndex }}"/>

14. bulletin 互動功能公告元件

<bulletin
  show="{{ true }}"
  zIndex="2001"
  bulletinStr="公告显示内容"
  bind:onClose="handleHideBulletin"/>

handleHideBulletin() {
  console.info('===点击关闭公告按钮触发===');
}

公告可以自訂顯示內容，如果需要顯示聊天室的公告訊息，需要監聽聊天室的「BULLETIN」事件，以取得公告內容並顯示。

使用 API

功能使用時的核心方法為 setApp、init、destroy、api 方法。

setApp

設定 polyv 雲直播的 appId、appSecret。通常在 app.js 的 onLaunch 方法中呼叫。

init

初始化成功返回频道详情：detail、聊天室：chat、网络请求：api

plv.init(options)
  .then(r => {
    // 初始化成功
    const { detail, chat } = r;
  })
  .catch(err => {
    // 初始化失败
    console.error(err);
  });

自訂統計參數設定

如果需要傳入自訂互動統計資料 param4、param5，需在 options 中加入參數； 若是直接引用 polyv 元件，則直接在 options 中加入 param4、param5 即可；若是單獨引用 player 元件，則需設定 player 元件參數 videoOption。

直接引用 polyv 元件範例：

plv.init(options = {..., param4: 'param4', param5: 'param5'})
  .then(r => {
    // 初始化成功
    const { detail, chat } = r;
  })
  .catch(err => {
    // 初始化失败
    console.error(err);
  });

單獨使用player元件範例

  <player
    videoOption="{{ videoOption }}"
  />

videoOption = {
  statistics: {
    param4: 'param4',
    param5: 'param5'
  }
}
plv.init(options = {..., param4: 'param4', param5: 'param5'})
  .then(r => {
    // 初始化成功
    const { detail, chat } = r;
  })
  .catch(err => {
    // 初始化失败
    console.error(err);
  });

相關參數說明

頻道詳情：detail

聊天功能：chat

• chat.events 所有事件

• chat.socket 獲取 socket 物件

• chat.on 監聽 events 事件

• chat.off 卸載 events 事件

• chat.trigger 觸發事件

• chat.options 傳入的 options

• chat.roomClosed 房間是否關閉

• chat.teacherData 老師資訊

• 聊天室 API 相關

• 諮詢室 API 相關

• chat.getQuestionHistoryMessage() 取得諮詢歷史記錄

  • chat.sendQuestion() 發送諮詢訊息

• 連麥

• chat.checkCurrentStatus() 查詢當前連線狀態

  • chat.cancelJoinChannel() 取消加入連線

destory

在頁面的 onUnload 方法中呼叫該方法，重置資料。

api

• api.getUserId(openId) 取得 userId
• api.getChannelDetail(channelId) 取得頻道詳細資訊
• api.getOrdinaryLiveStatus(channelId) 取得一般直播狀態
• api.getPlayBackVideos(channelId) 取得回放列表資料
• api.getChapterRecords(params) 取得章節資訊
  • params.id 暫存檔案 ID / 回放影片的 videoId（當 type 為 record 時，id 為暫存檔案的 fileId；當 type 為 playback 時，id 為回放影片的 videoId）
  • params.channelId 頻道 ID
  • params.type 類型（record：暫存類型；playback：回放類型）
• api.getChannelKey(channelId) 取得連線密鑰

錯誤訊息說明