Extend the OnePass web plugin with your own plugins
The webpage plugin (insertNode.js) loads plugins on demand. A plugin is just one JavaScript file: register a run function with WebsitePusher.registerPlugin, then list its name in the plugins parameter. Plugins can report events, draw a custom UI, or take over incoming messages — all reusing the same channel code.
1How plugins work
The web plugin loads only the plugins you name. No plugin means no extra scripts and no panel — just the default widget behaviour.
- Each plugin is one
.jsfile that callsWebsitePusher.registerPlugin(name, run)once on load. - The component loads the script and then executes
run(settings), wheresettingsholds every init parameter shared by all plugins. - A plugin can optionally set
settings.newMsgCallbackto receive full messages, or call the reporting API to push events back to your channel. - Exceptions inside a plugin are caught by the component and never break the web plugin itself.
2Loading plugins and parameters
Add the plugins parameter to the insertNode.js script URL. Separate multiple names with English commas.
<script src="https://ws.phprm.com/static/customer/js/insertNode.js?appName=my_site&channelCode=YOUR_CHANNEL_CODE&plugins=mynote,stat"></script>
| Parameter | Description |
|---|---|
appName | Application name used for statistics. |
channelCode | Your 32-character channel code. If omitted, one is claimed from the current URL. |
plugins | Plugin names, English commas separated: mynote, panel,stat. Supports a bare name, http://…/x.js or https://…/x.js (full URL loaded directly, name taken from the file name). |
pluginsSite | Plugin directory. Defaults to static/customer/js/plugins/. Point it at your own server to load self-hosted plugins. For security, danmu.js does not support a custom pluginsSite plugin directory, but you can still load http-based plugins in danmu.js. |
danMu | 1 renders danmu; 0 disables danmu rendering (push and statistics still work). |
hideDialog | 1 stops the chat window from popping up automatically. |
hideIcon | 1 hides the bottom-right entry icon (useful when you only want a custom plugin UI). |
autoInit | 0 loads dependencies without initializing; listen for websitePusherReady and call WebsitePusher.init() yourself. |
For plugins that only draw their own UI or report data (for example ad, stat), add danMu=0&hideDialog=1&hideIcon=1 so the widget stays invisible except for your plugin.
3Write your first plugin
Three steps: create the file, register the plugin, then load it by name.
You can also ask AI to write a plugin based on msg-sms-code, which extracts verification codes from the message body — for example, ask it to copy the recognized code to the clipboard automatically.
Step 1 — create plugins/mynote.js
(function () {
if (typeof WebsitePusher === "undefined" || !WebsitePusher.registerPlugin) {
return; // component not loaded yet
}
WebsitePusher.registerPlugin("mynote", function (settings) {
console.log("mynote started, channel=" + settings.channelCode);
// report an event: visible in the channel's push log with head=mynote
WebsitePusher.pushTrigger("mynote", "hello from my plugin");
});
})();Step 2 — load it by name
Write the name in the script URL, or set plugins: "mynote" when calling init().
<script src="https://ws.phprm.com/static/customer/js/insertNode.js?appName=my_site&channelCode=YOUR_CHANNEL_CODE&pluginsSite=https://push.phprm.com/static/js/plugins&plugins=mynote"></script>
Step 3 — check the result
- Open the browser console for
mynote started. - Open the channel's push log: the reported event appears with
head=mynote.
4Message streams: new_msg vs new_dm
For faster delivery, the server emits two kinds of messages. The widget subscribes to only one, decided by the plugin name prefix.
| Plugin name | Event subscribed | Payload | Typical use |
|---|---|---|---|
starts with msg (case-insensitive), e.g. msg-dialog, msg-sms-code | new_msg | Full message (head + content + uid + …) | Render a message, recognize a verification code — anything needing the body. |
any other name, e.g. stat, ad, panel | new_dm | Lightweight message (head + avatar) | Statistics, ads, danmu — no body needed, so it's faster. |
URL plugins follow the same rule: the name is taken from the last path segment without .js. For example https://x.com/msg-foo.js matches the msg prefix.
Receive full messages
Set settings.newMsgCallback inside your plugin. It receives the parsed message object (not a JSON string).
WebsitePusher.registerPlugin("msg-demo", function (settings) {
settings.newMsgCallback = function (message) {
console.log("full message:", message.content, message.head);
// de-duplicate: socket reconnects may deliver the same message twice
// do NOT echo the message back with sendMsg(), or you create a loop
};
});sendMsg() after receiving a message, that message is broadcast back to new_msg and your plugin receives it again — an infinite loop. Always de-duplicate by message id and by the value you send.Listen from anywhere on the page
Besides the callback, every full message is dispatched as a pushNewMsg DOM event, so any script can listen without registering a plugin:
window.addEventListener("pushNewMsg", function (e) {
console.log("got message:", e.detail);
});5Plugin API reference
| API / hook | Description |
|---|---|
WebsitePusher.registerPlugin(name, run) | Register a plugin. run(settings) executes after the script loads. Call it once per plugin file. |
settings | All init / script-URL parameters shared by plugins: channelCode, plugins, pluginsSite, appName, etc. |
settings.newMsgCallback(message) | Set in a msg* plugin to receive full messages as objects. |
settings.danMuMessageCallback(message) | Message gate for lightweight messages. Return true to consume the message so it is not rendered as danmu. |
WebsitePusher.pushTrigger(head, body) | Report an event to the channel. Check the channel's push log to verify. |
pushNewMsg event | DOM event carrying the full message in event.detail; an alternative to newMsgCallback. |
window.sendMsg(text) | Available in the H5 widget page (kf-pc.js), sends a chat message. Use with the loop guard above. |
Gate example — consume only your own messages, pass everything else through to the original handler:
var origin = settings.danMuMessageCallback; // keep the original gate
settings.danMuMessageCallback = function (message) {
if (message.head === "mynote") {
console.log("got mynote message", message);
return true; // handled here, do not render as danmu
}
return typeof origin === "function" ? origin.call(settings, message) : false;
};6Official plugins
Ready-to-use plugins shipped with the widget. Load them by name in the plugins parameter.
panel
Top-right panel: channel code, login, add channel, danmu settings and open/close API.
stat
Visit statistics: report visit on load and click on interaction.
ad
Bottom-right image ad slot, auto-dismiss and close button. Use with danMu=0.
axios-report
Report axios request errors (head=axios). Use with danMu=0&hideDialog=1&hideIcon=1.
vue-report
Report Vue errors and warnings (head=vue). Same invisible parameters as axios-report.
msg-sms-code
Recognizes SMS verification codes in messages and calls sendMsg(code). msg prefix → subscribes to new_msg.
Drag an official plugin bookmarklet to your browser bar from the booklet widget page to try it instantly.
Most plugins work directly in danmu.js; a few need extra care because danmu and dialog display differently.
Plugins run on the open-source danmu component teakong/danmu. The source is open for self-hosting or modification.
7Deploy and publish
- Use strict ES5 (no arrow functions /
let/const) for maximum browser compatibility. - Wrap your code in an IIFE and guard against
WebsitePushernot being loaded yet. - Place the file under
static/customer/js/plugins/(on this site:static/js/plugins/) with a file name equal to the plugin name; hard-refresh to clear the cache. - Self-hosted plugin directory: pass
pluginsSite=https://your.com/plugins/in the insertNode.js script URL (insertNode.js only — danmu.js does not support it), or use a fullhttp(s)://…/x.jsURL directly inplugins. - Verify with the browser console and the channel push log before publishing.
8FAQ
How do I check whether a plugin loaded?
Open the browser console and filter by [网页插件]. Every plugin load prints a unified log; ✓ means script loaded + registerPlugin + run() all succeeded, ✗ gives the exact reason (not registered / run() threw):
[网页插件] ┌─ 开始加载 2 个: panel, mynote [网页插件] │ ✓ panel 已就绪 (12ms) [网页插件] │ ✗ mynote 脚本已加载但未注册 (未调用 registerPlugin) [网页插件] └─ 加载完成: 1 成功 / 1 失败 | 耗时 45ms
My plugin is not loading
Check the name spelling and case, that the file is at pluginsSite/<name>.js, and that registerPlugin is called by the time the script finishes loading.
My plugin gets no message body
Only msg* plugins subscribe to new_msg (full message). Other names get the lightweight new_dm stream with no body.
Messages are sent over and over
A plugin that calls sendMsg() on every received message creates a feedback loop. De-duplicate both by message id and by the code/text you send.
Can two plugins both handle full messages?
They share one settings.newMsgCallback slot, so the last one wins. To handle messages independently, use the pushNewMsg DOM event instead.
Need a channel code to try this out?
Create a channel on the message page, then replace YOUR_CHANNEL_CODE in the examples above.
Documentation is public, but every example needs a real channel code. Treat the channel code as a credential — do not commit it to a public repository.