OnePass · Web plugin development guide

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.

page loads insertNode.js → reads plugins / pluginsSite from the script URL → loads pusher → loads each plugins/.js → registerPlugin(name, run) → runs run(settings)
  • Each plugin is one .js file that calls WebsitePusher.registerPlugin(name, run) once on load.
  • The component loads the script and then executes run(settings), where settings holds every init parameter shared by all plugins.
  • A plugin can optionally set settings.newMsgCallback to 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>
ParameterDescription
appNameApplication name used for statistics.
channelCodeYour 32-character channel code. If omitted, one is claimed from the current URL.
pluginsPlugin 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).
pluginsSitePlugin 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.
danMu1 renders danmu; 0 disables danmu rendering (push and statistics still work).
hideDialog1 stops the chat window from popping up automatically.
hideIcon1 hides the bottom-right entry icon (useful when you only want a custom plugin UI).
autoInit0 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 nameEvent subscribedPayloadTypical use
starts with msg (case-insensitive), e.g. msg-dialog, msg-sms-codenew_msgFull message (head + content + uid + …)Render a message, recognize a verification code — anything needing the body.
any other name, e.g. stat, ad, panelnew_dmLightweight 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
    };
});
Guard against loops: if your plugin calls 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 / hookDescription
WebsitePusher.registerPlugin(name, run)Register a plugin. run(settings) executes after the script loads. Call it once per plugin file.
settingsAll 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 eventDOM 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 WebsitePusher not 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 full http(s)://…/x.js URL directly in plugins.
  • 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.

OnePass Web Plugin Development Guide

This guide explains how to extend the OnePass web plugin (insertNode.js) with custom plugins. A plugin is a single JavaScript file that registers a run function through WebsitePusher.registerPlugin and is loaded by listing its name in the plugins parameter. Plugins can report events, draw their own UI, or take over incoming messages.

How plugins work

The web plugin loads only the plugins you name. After insertNode.js reads the plugins and pluginsSite parameters from the script URL, it loads the pusher and each plugins/name.js, calls registerPlugin, and runs the plugin with shared settings.

Loading and parameters

Add plugins to the insertNode.js script URL with English commas between names. Other parameters include appName, channelCode, pluginsSite, danMu, hideDialog, hideIcon and autoInit. For plugins that only draw their own UI, use danMu=0&hideDialog=1&hideIcon=1.

Message streams

For faster delivery the widget subscribes to only one stream, chosen by plugin name prefix: plugins whose name starts with msg subscribe to new_msg (full message with body); all others subscribe to new_dm (lightweight head and avatar). Every full message is also dispatched as a pushNewMsg DOM event.

Custom plugins and publishing

Write strict ES5, wrap the code in an IIFE, place the file under static/customer/js/plugins/ with a name matching the plugin, and verify in the browser console and the channel push log. Official plugins include panel, stat, ad, axios-report, vue-report and msg-sms-code.