自定义插件扩展网页插件的能力
网页插件(insertNode.js)按需加载插件。一个插件就是一个 JS 文件:用 WebsitePusher.registerPlugin 注册一个 run 函数,再在 plugins 参数里写上插件名即可。插件可以上报事件、画自己的界面,或接管收到的消息,全部复用同一条通道码。
1插件的运行原理
网页插件只加载你点名的插件。不写 plugins 就不加载任何插件,也没有右上角面板,只有挂件默认行为。
- 每个插件是一个
.js文件,加载时调用一次WebsitePusher.registerPlugin(名字, run)。 - 组件加载完脚本后执行
run(settings),其中settings是所有插件共用的初始化参数。 - 插件可按需设置
settings.newMsgCallback接收完整消息,或调用上报接口把事件推回通道。 - 插件内部抛出的异常会被组件捕获,不会影响挂件主流程。
2加载方式与参数
在 insertNode.js 的 script 地址上加 plugins 参数,多个名字用英文逗号分隔。
<script src="https://ws.phprm.com/static/customer/js/insertNode.js?appName=my_site&channelCode=你的通道码&plugins=mynote,stat"></script>
| 参数 | 说明 |
|---|---|
appName | 应用名,用于统计。 |
channelCode | 32 位通道码;不传则按当前网址自动认领。 |
plugins | 插件名,英文逗号分隔:mynote、panel,stat。支持纯名字、http://…/x.js、https://…/x.js(完整 URL 直接加载,注册名取文件名)。 |
pluginsSite | 插件目录,默认 static/customer/js/plugins/;指向自己的服务器即可加载自托管插件。为了安全,danmu.js 不支持自定义pluginsSite插件目录,但可以在danmu.js下加载http开头的插件。 |
danMu | 1=渲染弹幕;0=不渲染弹幕(推送、统计照常)。 |
hideDialog | 1=不自动弹出对话窗口。 |
hideIcon | 1=不显示右下角入口图标(只留自定义插件界面时用)。 |
autoInit | 0=只加载依赖不初始化,之后监听 websitePusherReady 自行调用 WebsitePusher.init()。 |
只画自己界面或只上报数据的插件(如 ad、stat),建议加 danMu=0&hideDialog=1&hideIcon=1,让挂件本身不可见,只留你的插件。
3编写第一个插件
三步:建文件、注册插件、按名字加载。
也可以让 AI 参考 msg-sms-code 编写插件,支持从正文部分提取验证码,例如请支持识别验证码后自动复制到剪切板。
第 1 步:新建 plugins/mynote.js
(function () {
if (typeof WebsitePusher === "undefined" || !WebsitePusher.registerPlugin) {
return; // 组件还没加载,先放弃
}
WebsitePusher.registerPlugin("mynote", function (settings) {
console.log("mynote 已启动,通道码=" + settings.channelCode);
// 上报一条事件,通道后台「推送记录」里能看到 head=mynote
WebsitePusher.pushTrigger("mynote", "hello 自定义插件");
});
})();第 2 步:按名字加载
在 script 地址里写插件名,或 init() 时写 plugins: "mynote"。
<script src="https://ws.phprm.com/static/customer/js/insertNode.js?appName=my_site&channelCode=你的通道码&pluginsSite=https://push.phprm.com/static/js/plugins&plugins=mynote"></script>
第 3 步:验证结果
- 浏览器控制台看到
mynote 已启动; - 通道后台「推送记录」里出现
head=mynote的上报。
4消息流:new_msg 与 new_dm
为提升速度,服务端发两种消息;挂件只订阅其中一种,由插件名前缀决定。
| 插件名 | 订阅事件 | 消息体 | 适用场景 |
|---|---|---|---|
以 msg 开头(不分大小写),如 msg-dialog、msg-sms-code | new_msg | 完整消息(head + content + uid 等) | 渲染消息、识别验证码等需要正文的场景。 |
其他名字,如 stat、ad、panel | new_dm | 轻量消息(head + 头像) | 统计、广告、弹幕——不需要正文,速度更快。 |
URL 形式插件同样按此规则:注册名取 URL 末段去 .js,例如 https://x.com/msg-foo.js 命中 msg 前缀。
接收完整消息
在插件里设置 settings.newMsgCallback,参数是解析好的消息对象(不是 JSON 字符串)。
WebsitePusher.registerPlugin("msg-demo", function (settings) {
settings.newMsgCallback = function (message) {
console.log("完整消息:", message.content, message.head);
// 去重:socket 重连可能重复投递同一条消息
// 不要把收到的消息再用 sendMsg 发回去,否则会无限循环
};
});sendMsg(),这条消息会被服务端广播回 new_msg,插件再次收到→再次发送→无限循环。务必按消息 ID 和发送内容双重去重。在页面任意处监听
除回调外,每条完整消息还会派发为 pushNewMsg DOM 事件,任何脚本都能监听,无需注册插件:
window.addEventListener("pushNewMsg", function (e) {
console.log("收到消息:", e.detail);
});5插件 API 一览
| API / 钩子 | 说明 |
|---|---|
WebsitePusher.registerPlugin(name, run) | 注册插件,脚本加载后执行 run(settings),每个插件文件调用一次。 |
settings | 所有插件共用的初始化参数:channelCode、plugins、pluginsSite、appName 等。 |
settings.newMsgCallback(message) | 在 msg* 插件里设置,接收完整消息对象。 |
settings.danMuMessageCallback(message) | 轻量消息闸门;返回 true 表示已处理,不再渲染成弹幕。 |
WebsitePusher.pushTrigger(head, body) | 上报事件到通道,可在通道「推送记录」里核对。 |
pushNewMsg 事件 | DOM 事件,完整消息在 event.detail,可替代 newMsgCallback。 |
window.sendMsg(text) | H5 挂件页(kf-pc.js)提供,发送聊天消息。注意上面的防循环措施。 |
闸门示例:只消费自己的消息,其余交回原处理器:
var origin = settings.danMuMessageCallback; // 先留住原有闸门
settings.danMuMessageCallback = function (message) {
if (message.head === "mynote") {
console.log("收到 mynote 消息", message);
return true; // 我处理了,不渲染弹幕
}
return typeof origin === "function" ? origin.call(settings, message) : false;
};6官方插件清单
挂件自带的现成插件,在 plugins 参数里按名字加载即可。
panel
右上角面板:通道码、登录账户、增加通道、弹幕设置,以及打开/关闭面板的 API。
stat
访问统计:加载上报 visit,点击上报 click。
ad
右下角图片广告位,可关闭、可按时长自动消失。建议配 danMu=0。
axios-report
axios 接口异常上报(head=axios)。建议配 danMu=0&hideDialog=1&hideIcon=1。
vue-report
Vue 异常与告警上报(head=vue),参数同上。
msg-sms-code
识别消息里的短信验证码并调用 sendMsg(code)。msg 前缀 → 订阅 new_msg。
从书签挂件页把官方插件书签拖到浏览器地址栏,即可立即体验。
绝大部分插件都可以在 danmu.js 直接使用,少部分需考虑 danmu 和 dialog 显示方式不同。
插件运行在开源弹幕组件 teakong/danmu 之上,源码开放,可自行部署或修改(Gitee 仓库,国内访问更稳定)。
7部署与发布
- 使用严格 ES5(不用箭头函数、
let/const),兼容更多浏览器。 - 代码用 IIFE 包起来,并判断
WebsitePusher是否已加载。 - 文件放到
static/customer/js/plugins/(本站为static/js/plugins/),文件名与插件名一致,改完强刷缓存。 - 自托管插件目录:在 insertNode.js 的 script 地址传
pluginsSite=https://你的域名/plugins/(仅 insertNode.js 支持,danmu.js 不支持),或直接在plugins里写完整http(s)://…/x.js。 - 发布前用浏览器控制台和通道「推送记录」核对效果。
8常见问题
怎么确认插件有没有加载成功?
打开浏览器控制台,按 [网页插件] 过滤即可。每次加载都会按统一规范打印日志:✓ 表示脚本加载 + registerPlugin + run() 全部成功,✗ 会给出具体原因(未注册 / run() 抛错):
[网页插件] ┌─ 开始加载 2 个: panel, mynote [网页插件] │ ✓ panel 已就绪 (12ms) [网页插件] │ ✗ mynote 脚本已加载但未注册 (未调用 registerPlugin) [网页插件] └─ 加载完成: 1 成功 / 1 失败 | 耗时 45ms
插件没加载
检查名字拼写与大小写、文件是否在 pluginsSite/名字.js、脚本加载完时是否调用了 registerPlugin。
插件收不到消息正文
只有 msg* 插件订阅 new_msg(完整消息);其他名字收的是轻量的 new_dm,没有正文。
消息一直重复发送
插件每收到消息就调用 sendMsg() 会形成回环。按消息 ID 和发送的内容双重去重即可。
两个插件都要处理完整消息怎么办
它们共用一个 settings.newMsgCallback,后设置的会覆盖前一个。要各自独立处理,改用 pushNewMsg DOM 事件。
还没有通道码?
到消息页创建一个通道,再把上面示例里的 你的通道码 替换掉即可。
文档公开可看,但每个示例都要一个真实通道码。通道码是凭证,不要提交到公开仓库。
一封传话网页插件开发手册
本页讲解如何用自定义插件扩展一封传话网页插件(insertNode.js)。一个插件就是一个 JS 文件,通过 WebsitePusher.registerPlugin 注册 run 函数,在 plugins 参数里写上插件名即可加载。插件可以上报事件、画自己的界面,或接管收到的消息。
插件运行原理
网页插件只加载你点名的插件。insertNode.js 从 script 地址读取 plugins 与 pluginsSite 参数,加载 pusher 和每个 plugins/名字.js,调用 registerPlugin 后用共享的 settings 执行插件。
加载方式与参数
在 insertNode.js 的 script 地址上加 plugins 参数,多个名字用英文逗号分隔。其他参数有 appName、channelCode、pluginsSite、danMu、hideDialog、hideIcon、autoInit。只画自己界面的插件建议加 danMu=0&hideDialog=1&hideIcon=1。
消息流模式
为提升速度,挂件只订阅一种消息流,由插件名前缀决定:以 msg 开头的插件订阅 new_msg(含正文的完整消息),其余插件订阅 new_dm(只有 head 和头像的轻量消息)。每条完整消息还会派发为 pushNewMsg DOM 事件。
自定义插件与发布
用严格 ES5 编写、IIFE 包裹,文件放到 static/customer/js/plugins/ 且文件名与插件名一致,发布前用浏览器控制台和通道「推送记录」核对。官方插件有 panel、stat、ad、axios-report、vue-report、msg-sms-code。