Writing an integration plugin

This page explains how to write integration plugins of the kind you see on the Market (OBS scene switcher, Twitch/Spotify control, Discord, hotkey) from scratch.

Integrations are written with T1 (trusted-node) and are not a sandbox — the plugin can access everything your Windows user account can access. Run only code you wrote/reviewed yourself. The public T2 sandbox model is different (see Trust tiers).

Core model: T1 = full Node process

The one idea that matters: evoX runs your T1 plugin as a separate, full Node.js process. That means:

You can use any npm library you want (npm install obs-websocket-js ws node-fetch …).
You can connect to external services directly — WebSocket, HTTPS API, local port. evoX does not sit in between.
The SDK only manages the host side: which event arrived (key pressed, knob rotated), what is shown on the key (title/image/state), settings and logs.

So the division of labor is: external service logic is your Node code + your npm libraries; the key/settings/event bridge is the SDK.

[ Dış servis: OBS / Twitch / Spotify ]
        ▲  (sizin npm kütüphaneniz: ws, api client — doğrudan)
        │
   runtime.mjs  (T1 tam Node)
        │
        ▼  (@evoxapp/plugin-sdk: event + setTitle/setImage + settings)
[ evoX host  →  cihaz tuşu ]

Project setup

npx @evoxapp/plugin-cli init obs-switcher --runtime trusted-node --name "OBS Sahne"
cd obs-switcher
npm install @evoxapp/plugin-sdk obs-websocket-js

Declare the action and its settings in manifest.json. Setting types are rich — secret, oauth, select, color, number, toggle, hotkey, url, path are supported:

{
  "actions": [
    {
      "id": "scene",
      "name": "Sahne Seç",
      "controllers": ["Keypad"],
      "settingsSchema": [
        { "key": "host", "type": "text", "label": "OBS Host", "default": "127.0.0.1" },
        { "key": "port", "type": "number", "label": "Port", "default": 4455 },
        { "key": "password", "type": "secret", "label": "OBS Parolası" },
        { "key": "sceneName", "type": "text", "label": "Sahne adı" }
      ]
    }
  ]
}

Pattern 1 — WebSocket integration (OBS)

runtime.mjs: set up the connection on the first willAppear, send commands on keyDown, clean up on willDisappear.

import { EvoxPluginClient } from '@evoxapp/plugin-sdk';
import { createNodeProcessIpcPluginTransport } from '@evoxapp/plugin-sdk/node';
import OBSWebSocket from 'obs-websocket-js';

const client = new EvoxPluginClient(createNodeProcessIpcPluginTransport(), { sdkVersion: '0.1.0' });
const obs = new OBSWebSocket();
let connected = false;

async function ensureConnected(settings) {
  if (connected) return;
  await obs.connect(`ws://${settings.host || '127.0.0.1'}:${settings.port || 4455}`, settings.password || undefined);
  connected = true;
}

client.on('action.willAppear', async (event) => {
  if (event.context?.actionId !== 'scene') return;
  await client.setTitle(event.context.bindingInstanceId, 'OBS');
});

client.on('action.keyDown', async (event) => {
  if (event.context?.actionId !== 'scene') return;
  const id = event.context.bindingInstanceId;
  try {
    const settings = await client.getSettings(id);
    await ensureConnected(settings);
    await obs.call('SetCurrentProgramScene', { sceneName: settings.sceneName });
    await client.showSuccess(id);
  } catch (error) {
    console.error('[obs] ' + String(error?.message || error));
    connected = false;
    await client.showError(id);
  }
});

client.on('plugin.stop', async () => { try { await obs.disconnect(); } catch {} });

await client.start();

The ws://127.0.0.1 connection is made directly — T1 is full Node, so no SDK “network capability” is needed. (This is not the case in the public T2 sandbox; there the host-brokered network.fetch is used.)

Pattern 2 — API + OAuth (Twitch/Spotify style)

There are two ways:

Your own token management: T1 is full Node, so you can read the token from a secret setting and use it directly with fetch.
Host-brokered OAuth: With SDK beginOAuth(provider) / getOAuthStatus(provider) you use evoX’s credential vault; the raw token never returns to your plugin, the host injects it into the request.

client.on('action.keyDown', async (event) => {
  if (event.context?.actionId !== 'nowPlaying') return;
  const id = event.context.bindingInstanceId;
  const settings = await client.getSettings(id);
  const res = await fetch('https://api.spotify.com/v1/me/player/currently-playing', {
    headers: { Authorization: `Bearer ${settings.token}` },
  });
  const data = await res.json();
  await client.setTitle(id, data?.item?.name?.slice(0, 12) || '—');
});

Key image — `setImage` (dynamic images such as album art)

Besides the title, you can draw a dynamic image on the key. Two formats:

// 1) Pakete gömülü asset (manifest-hash id ile):
await client.setImage(id, { kind: 'asset', assetId: 'scene-live' });

// 2) Çalışma anında üretilen/indirilen raster (base64):
const bytes = Buffer.from(await (await fetch(albumArtUrl)).arrayBuffer());
await client.setImage(id, { kind: 'raster', mimeType: 'image/png', dataBase64: bytes.toString('base64') });

For multi-state actions, change the state (starting at 0) with setState(id, n).

Knob support

Declare the action with "controllers": ["Knob"] and listen to action.dialRotate / action.dialDown — ideal for continuous values such as volume/brightness.

let volume = 50;
client.on('action.dialRotate', async (event) => {
  if (event.context?.actionId !== 'volume') return;
  // dialRotate payload'ı `delta` (işaretli adım) ve/veya `direction` ('LEFT'/'RIGHT') taşır.
  const step = Number(event.payload?.delta ?? (event.payload?.direction === 'LEFT' ? -1 : 1));
  volume = Math.max(0, Math.min(100, volume + step));
  await client.setTitle(event.context.bindingInstanceId, `%${volume}`);
});

Lifecycle and cleanup

Set up the connection lazily on willAppear; close it on plugin.stop.
If polling is needed, start it on willAppear and stop it on willDisappear; use exponential backoff on errors.
Wrap every handler in try/catch; log the error with console.error (visible in the Developer window) and notify the user with showError.
The host assigns identity: do not write to any context other than event.context.bindingInstanceId; ignore an actionId you don’t recognize.

Next step

Test in your own evoX

Load the project from the Developer window, assign it to a key, reload and see the logs.

References: Events and host-RPC · Manifest · Capability model (T2).

Getting started

Core concepts

Examples and distribution

Writing an integration plugin

Core model: T1 = full Node process

Project setup

Pattern 1 — WebSocket integration (OBS)

Pattern 2 — API + OAuth (Twitch/Spotify style)

Key image — `setImage` (dynamic images such as album art)

Knob support

Lifecycle and cleanup

Next step

Test in your own evoX

​Core model: T1 = full Node process

​Project setup

​Pattern 1 — WebSocket integration (OBS)

​Pattern 2 — API + OAuth (Twitch/Spotify style)

​Key image — setImage (dynamic images such as album art)

​Knob support

​Lifecycle and cleanup

​Next step

Test in your own evoX

Core model: T1 = full Node process

Project setup

Pattern 1 — WebSocket integration (OBS)

Pattern 2 — API + OAuth (Twitch/Spotify style)

Key image — `setImage` (dynamic images such as album art)

Knob support

Lifecycle and cleanup

Next step