Build a Widget WebSocket Relay

What you’ll accomplish

You will understand the WebSocket data path, create a small Node.js relay, emit valid RuntimeDataEnvelope v1 snapshots, test locally, and prepare a production wss:// endpoint.

Who must provide the WebSocket server?

Layarva Player is a WebSocket client. It connects to an endpoint and listens; it does not create the server that publishes your data. For the current Secure WebSocket mode, the customer or integration partner normally provides the relay. You can:

host a small relay on your own server or container platform;
use a managed service that supports WebSocket broadcasting; or
connect directly to an existing provider only when its endpoint already satisfies the Layarva message and security requirements.

Layarva does not currently provide a generic hosted WebSocket broker for customer Widget data.

If updates every few seconds are sufficient, use Structured Widget Push API. Push API is simpler to operate because no continuously connected server is required.

How it works

1. Your source changes
   CMS / ERP / POS / IoT / database
                 |
                 v
2. Your relay builds RuntimeDataEnvelope v1
                 |
                 v  wss:// persistent outbound connection
3. Each Layarva Player receives and validates the message
                 |
                 v
4. Player stores Last Known Good and renders the Widget

The Player rejects malformed messages, messages larger than 1 MiB, and messages whose sourceId does not exactly match the Widget ID. When the connection closes, it reconnects with exponential backoff up to five minutes.

Prerequisites

Node.js 20 or later for this example.
A host that supports long-lived WebSocket connections.
A DNS name and valid TLS certificate for production.
The Unique Widget ID and workspace ID.
Data that can be transformed into the selected Widget’s semantic schema.

Create the relay

Create a new server project outside browser code:

mkdir layarva-widget-relay
cd layarva-widget-relay
npm init -y
npm install ws

Create server.mjs:

import { createHash } from "node:crypto";
import { WebSocket, WebSocketServer } from "ws";

const port = Number(process.env.PORT ?? 8080);
const widgetId = process.env.LAYARVA_WIDGET_ID;
const workspaceId = process.env.LAYARVA_WORKSPACE_ID;

if (!widgetId || !workspaceId) {
  throw new Error("LAYARVA_WIDGET_ID and LAYARVA_WORKSPACE_ID are required");
}

const wss = new WebSocketServer({ port });
let sequence = 0;

function buildWidgetData(now) {
  return {
    schemaVersion: 2,
    title: "Today's Agenda",
    locale: "en-US",
    timezone: "Asia/Jakarta",
    date: now.toLocaleDateString("en-CA", { timeZone: "Asia/Jakarta" }),
    updatedAt: now.toISOString(),
    items: [
      {
        id: "agenda-001",
        startAt: "2026-08-27T09:00:00+07:00",
        endAt: "2026-08-27T09:30:00+07:00",
        title: "Morning Briefing",
        location: "Meeting Room A",
        status: "SCHEDULED"
      }
    ]
  };
}

function buildEnvelope() {
  const now = new Date();
  const data = buildWidgetData(now);
  const contentHash = createHash("sha256")
    .update(JSON.stringify(data))
    .digest("hex");

  return {
    schemaVersion: "1",
    sourceId: widgetId,
    workspaceId,
    sequence: ++sequence,
    contentHash,
    generatedAt: now.toISOString(),
    expiresAt: new Date(now.getTime() + 60_000).toISOString(),
    staleAt: new Date(now.getTime() + 86_400_000).toISOString(),
    status: "FRESH",
    data
  };
}

function sendSnapshot(client) {
  if (client.readyState === WebSocket.OPEN) {
    client.send(JSON.stringify(buildEnvelope()));
  }
}

wss.on("connection", (client, request) => {
  const expectedPath = `/widgets/${widgetId}`;
  const path = new URL(request.url ?? "/", "http://relay.local").pathname;

  if (path !== expectedPath) {
    client.close(1008, "Unknown Widget source");
    return;
  }

  sendSnapshot(client);
});

setInterval(() => {
  for (const client of wss.clients) sendSnapshot(client);
}, 30_000);

console.log(`Widget relay listening on port ${port}`);

This example broadcasts a complete schedule snapshot every 30 seconds and immediately after a Player connects. Replace buildWidgetData() with a database query, event subscription, or provider call.

Run locally

macOS or Linux:

export LAYARVA_WIDGET_ID="wdg_example"
export LAYARVA_WORKSPACE_ID="ws_example"
node server.mjs

Windows PowerShell:

$env:LAYARVA_WIDGET_ID = "wdg_example"
$env:LAYARVA_WORKSPACE_ID = "ws_example"
node server.mjs

Connect a test client:

npx wscat -c ws://localhost:8080/widgets/wdg_example

Use this ws://localhost address only for local testing. Do not publish a Design with a localhost endpoint; a remote Player would interpret localhost as the Player device itself.

Understand RuntimeDataEnvelope v1

Field	Required	Rule
`schemaVersion`	Yes	String `"1"`
`sourceId`	Yes	Exact Unique Widget ID
`workspaceId`	Yes	Owning workspace identity
`sequence`	Yes	Safe integer that increases for every new snapshot
`contentHash`	Yes	Lowercase SHA-256, exactly 64 hexadecimal characters
`generatedAt`	Yes	ISO 8601 generation time
`expiresAt`	Yes	Time after which the snapshot becomes stale
`staleAt`	Yes	Time after which the snapshot must no longer be used
`status`	Yes	`FRESH`, `CACHED`, `STALE`, or `ERROR`
`data`	Yes	Object containing semantic Widget data or source data for declarative mapping
`error`	No	`{ code, message, retryable }` when the source reports an error

Use this ordering:

generatedAt < expiresAt < staleAt

The Player accepts the envelope directly or inside { "envelope": { ... } }.

Deploy with TLS

Production Studio configuration accepts wss://. Deploy the Node process behind a TLS-terminating load balancer or reverse proxy that supports WebSocket upgrades. Example reverse-proxy requirements:

Public:  wss://stream.example.com/widgets/wdg_example
Proxy:   preserve HTTP/1.1 Upgrade and Connection headers
Target:  ws://127.0.0.1:8080/widgets/wdg_example

Confirm that:

the TLS certificate is valid for the hostname;
the endpoint is reachable from every Player network;
idle connections are not closed too aggressively by the proxy;
the service restarts automatically after a crash or host restart;
the relay can handle one connection per online Player using that Widget source.

Configure Studio

Select the Widget in Studio.
Open Properties → Data Source.
Select Secure WebSocket.
Enter wss://stream.example.com/widgets/<WIDGET_ID>.
Set Reconnect to five seconds initially.
Keep valid Static JSON as a fallback.
Save and publish the Design.

Security model and current limitation

TLS protects data in transit, but wss:// alone does not decide which client may subscribe. The current Studio WebSocket configuration does not provide arbitrary authentication headers, cookies, or a configurable subprotocol. Therefore:

never put API keys, passwords, or long-lived bearer tokens in the URL;
keep provider credentials inside the relay, not in Studio or the Player;
expose only display-safe data;
use network allowlisting, private connectivity, or a gateway appropriate to your deployment when access must be restricted;
do not use the current direct WebSocket mode for sensitive data on an unauthenticated public endpoint.

If the upstream provider requires a secret, the relay authenticates to that provider server-side and publishes a separate display-safe WebSocket endpoint to Players.

Reconnect and Last Known Good

The Player connects using the configured initial reconnect delay.
A valid message becomes the current snapshot and is persisted as Last Known Good.
A malformed message is rejected without replacing the valid snapshot.
On close, retries back off exponentially up to 300 seconds.
After expiresAt, data is treated as stale.
After staleAt or the Player’s maximum stale policy, the snapshot is no longer eligible.
Static JSON remains the final safe fallback.

Production validation

Troubleshooting

Symptom	Likely cause	Action
Connection is rejected immediately	Wrong path or proxy is not upgrading WebSocket	Verify the public path and Upgrade forwarding
Studio accepts URL but Player never connects	DNS, firewall, certificate, or endpoint reachability	Test from the Player network using the production hostname
Connection succeeds but Widget never changes	Envelope is invalid or `sourceId` differs	Validate every required field and exact Widget ID
Updates stop after proxy idle timeout	No traffic or proxy timeout is too short	Send regular snapshots and increase the proxy idle timeout
Old snapshot stays on screen	Last Known Good is still eligible	Review `expiresAt`, `staleAt`, and fallback settings
Many Screens overwhelm the relay	One connection is opened per Player	Add connection monitoring, horizontal scale, and broadcast fan-out

Build with Layarva

Queue API Reference

Structured Widget API Reference

Prayer Schedule API Reference

What you’ll accomplish

Who must provide the WebSocket server?

How it works

Prerequisites

Create the relay

Run locally

Understand RuntimeDataEnvelope v1

Deploy with TLS

Configure Studio

Security model and current limitation

Reconnect and Last Known Good

Production validation

Troubleshooting

​What you’ll accomplish

​Who must provide the WebSocket server?

​How it works

​Prerequisites

​Create the relay

​Run locally

​Understand RuntimeDataEnvelope v1

​Deploy with TLS

​Configure Studio

​Security model and current limitation

​Reconnect and Last Known Good

​Production validation

​Troubleshooting

​Related guides

What you’ll accomplish

Who must provide the WebSocket server?

How it works

Prerequisites

Create the relay

Run locally

Understand RuntimeDataEnvelope v1

Deploy with TLS

Configure Studio

Security model and current limitation

Reconnect and Last Known Good

Production validation

Troubleshooting

Related guides