Development tools

The command line tool of @viswoo/plugin-sdk is viswoo-plugin.

viswoo-plugin init <code> [--template basic|interactive|server] [--dir <folder>]
viswoo-plugin dev [folder] [--port 5199] [--webhook http://localhost:8787/webhook]
viswoo-plugin validate [folder]
viswoo-plugin pack [folder] [--out dist]
viswoo-plugin publish [folder] [--api https://api.viswoo.com]

init

Creates a folder from a template: manifest, panel tab, screen view, a phone page and server example where relevant, README, .gitignore, an ES5-safe Prettier config (trailingComma: "es5") and .viswooignore. The folder must be empty.

dev: the simulator

npm run dev

The simulator opens at http://localhost:5199:

• Panel tab, TV and phone side by side. The TV is drawn at 16:9 or 9:16, 1280×720, 1920×1080 or 3840×2160, and scaled to fit.
• Toolbar: theme, language, user role, resolution, orientation, touch, offline, New visitor (resets the phone’s daily limit), Reset data.
• Settings: edit settings as JSON; schema errors are listed below. Settings that do not match the schema are saved too, so you can see how a plugin with incomplete setup behaves.
• Bridge calls: each call with its surface, result and duration.
• State: plugin data, codes, stock, events and values stored on the phone, all in .viswoo-dev/state.json.

The simulator applies the platform rules: permissions, viewers not being able to write, the settings schema and setup state, server-only fields not reaching the screen or phone, draw stock, the daily limit per phone, the cooldown between draws on a screen, code expiry and single redemption. The screen view opens with the player’s CSP: no network requests or external scripts.

The simulator has no placement; the TV frame counts as a screen the plugin is placed on.

With a real phone

The phone page opens on a phone in the same network at http://<computer IP>:5199/phone. The QR code in the screen view (context.publicUrl) shows this address, so you can scan it.

With your own server

server.webhookUrl in the manifest must be https; during development pass the local address with --webhook:

npx viswoo-plugin dev . --webhook http://localhost:8787/webhook

On start the simulator prints the signing secret (whsec_dev_…) and install token (vzp_dev_…) and sends the installed event. Your server can call the platform API at http://localhost:5199/api/v1/plugin/<code>/.... See Your own server.

validate and pack

validate checks the package with the platform rules; pack produces the .vzp after the same checks:

• manifest schema, file types, sizes (package 5 MB, screen view 512 KB), paths
• consistent permissions (settings schema → settings, draw → draw, public page → public …)
• kit usage: the panel tab and public page link viswoo-ui.css, the screen view links viswoo-screen.css
• at least one TV screenshot for plugins with a screen view
• ES5: scripts in the screen view are parsed as ES5; let, const, arrow functions, template strings, trailing commas and similar are reported with their line

The server checks uploaded packages again with the same rules.

publish

Uploads the package to the developer portal. Create a token in the portal under Command line → New token (two-step verification required); its value is shown once. A token can only upload versions and works while its owner keeps 2FA on.

VISWOO_TOKEN=vzd_… npx viswoo-plugin publish .

The command first runs the validate checks, then uploads; on errors it prints the server code and lines (for example plugin.not_es5, plugin.version_exists, plugin.code_not_registered). In CI, pass VISWOO_TOKEN as a secret.

Not packaged: files starting with a dot, node_modules, dist, package.json and lock files, and paths in .viswooignore (one path per line; a trailing / for folders).