一封传话 · 网页插件开发手册

自定义插件扩展网页插件的能力

网页插件(insertNode.js)按需加载插件。一个插件就是一个 JS 文件:用 WebsitePusher.registerPlugin 注册一个 run 函数,再在 plugins 参数里写上插件名即可。插件可以上报事件、画自己的界面,或接管收到的消息,全部复用同一条通道码。

1插件的运行原理

网页插件只加载你点名的插件。不写 plugins 就不加载任何插件,也没有右上角面板,只有挂件默认行为。

页面加载 insertNode.js → 从 script 地址读取 plugins / pluginsSite → 加载 pusher → 依次加载 plugins/名字.js → registerPlugin(名字, run) → 执行 run(settings)
  • 每个插件是一个 .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应用名,用于统计。
channelCode32 位通道码;不传则按当前网址自动认领。
plugins插件名,英文逗号分隔:mynote、panel,stat。支持纯名字、http://…/x.js、https://…/x.js(完整 URL 直接加载,注册名取文件名)。
pluginsSite插件目录,默认 static/customer/js/plugins/;指向自己的服务器即可加载自托管插件。为了安全,danmu.js 不支持自定义pluginsSite插件目录,但可以在danmu.js下加载http开头的插件。
danMu1=渲染弹幕;0=不渲染弹幕(推送、统计照常)。
hideDialog1=不自动弹出对话窗口。
hideIcon1=不显示右下角入口图标(只留自定义插件界面时用)。
autoInit0=只加载依赖不初始化,之后监听 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-codenew_msg完整消息(head + content + uid 等)渲染消息、识别验证码等需要正文的场景。
其他名字,如 stat、ad、panelnew_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。