Connect Data to a Widget

What you’ll accomplish

You will add a data-driven Widget to a Design, choose the appropriate data source, configure a safe fallback, and understand what must run outside Layarva.

Prerequisites

A workspace role with content editing permission.
A Design open in Studio Canvas.
Valid data that matches the selected Widget’s schema.
For Push API, a trusted backend or automation that can store a Workspace API Key.
For Secure WebSocket, a reachable wss:// endpoint that emits the Layarva runtime envelope.

Choose a data source

Mode	Best for	Who sends the update	Infrastructure you operate
Static JSON	Fixed or rarely changing content	An editor saves the Design	None
Layarva Push API	CMS, ERP, POS, schedules, and operational snapshots	Your backend sends an HTTPS request to Layarva	A job, automation, or backend that runs when data changes
Secure WebSocket	Rapid updates that should reach Players almost immediately	A WebSocket relay broadcasts to connected Players	A continuously available WebSocket relay, unless your provider already supplies a compatible one

Start with Static JSON. Move to Layarva Push API when another system owns the data. Use Secure WebSocket only when the normal Push refresh path is not fast enough.

Open Studio → Designs, then open a Design.
Select Widgets in the left toolbar.
Find the required Widget category.
Double-click the Widget card to add it to the Canvas.
Select the Widget on the Canvas.
In the right inspector, scroll to Data Source.

Built-in Widget browser in Layarva Studio — The Built-in Widget browser contains the supported data, schedule, operations, and integration components.

Use Static JSON

Static JSON is saved inside the Design. It is also the safest fallback when a dynamic source is temporarily unavailable.

Select Static JSON under Data Source.
Open Advanced JSON.
Paste a payload that matches the selected Widget.
Select Apply JSON.
Preview the Design, then select Save.
Publish the Playlist again whenever the saved static data changes.

Example for Today’s Schedule:

{
  "schemaVersion": 2,
  "title": "Today's Agenda",
  "locale": "en-US",
  "timezone": "Asia/Jakarta",
  "date": "2026-08-27",
  "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"
    }
  ]
}

The schema is strict. Use unique item IDs, valid ISO 8601 timestamps, an IANA timezone such as Asia/Jakarta, and plain text without HTML.

Use Layarva Push API

Push API stores the latest accepted snapshot in Layarva. Players read that secured snapshot on the Widget refresh interval and retain the last valid data during temporary failures.

Select Layarva Push API under Data Source.
Open API Setup & Usage Guide.
Copy the Unique Widget ID.
Copy the Workspace API Key when its full value is shown.
Store the key in the sending system’s secret manager.
Save and publish the Design once.
Send complete replacement snapshots to the production endpoint:

POST https://app.layarva.com/api/public/v1/widgets/{widgetId}/data/push

After the initial publish, accepted snapshots update the Widget without republishing the Design.

Never put a Workspace API Key in browser JavaScript, the Design JSON, a Player, a URL, or a screenshot. Push from a trusted server or automation.

See Push Structured Widget Data for the complete request, response, validation, idempotency, sequence, and retry contract.

Use Secure WebSocket

In WebSocket mode, each online Player opens an outbound connection to the configured endpoint and waits for snapshot messages.

Your CMS / ERP / IoT source
            |
            v
Your WebSocket relay (wss://)
            |
            v
Layarva Player -> validate -> cache Last Known Good -> render Widget

Do you need to create a WebSocket server?

Usually, yes. Layarva currently provides the Player-side WebSocket client, but not a generic hosted WebSocket relay for customer Widget data. You have three choices:

Build and host a small relay service.
Use a managed WebSocket service and make it emit the required envelope.
Connect directly to an existing provider endpoint only when it already uses wss://, needs no secret in the URL, and emits a compatible RuntimeDataEnvelope v1.

If none of those options is practical, use Push API. Push API does not require an always-running WebSocket server.

Configure the endpoint

Select Secure WebSocket under Data Source.
Enter an endpoint such as wss://stream.example.com/widgets/wdg_example.
Set the initial reconnect interval. Five seconds is a reasonable starting point.
Configure declarative mapping only if envelope.data does not already match the Widget schema.
Keep valid Static JSON as the fallback.
Save and publish the Design.

Production endpoints must use wss://. Plain ws:// is accepted only for localhost development.

Studio does not configure a secret request header for the Player WebSocket connection. Do not put passwords, API keys, or long-lived access tokens in the URL. Use a relay or network boundary designed for Player access, and do not send sensitive data through an unauthenticated public stream.

See Build a Widget WebSocket Relay for a working Node.js server, the message envelope, TLS, testing, reconnect behavior, and production checklist.

Expected result

Static JSON renders from the saved Design.
Push API renders the latest accepted Layarva snapshot without republishing.
Secure WebSocket renders valid snapshots received from the configured relay.
When a dynamic source fails temporarily, the Player keeps the Last Known Good snapshot or returns to the configured static fallback.

Important notes

Dynamic data changes content, not the Widget’s visual design.
Publish once after changing the data-source mode or endpoint.
The current Structured Push v2 contract supports Announcements, Today’s Schedule, Events, and Departure & Arrival.
Other legacy Widgets can show a different managed API contract in their Studio integration dialog. Do not mix legacy request bodies with Structured Push v2.
A WebSocket connection is online-only. Test failure behavior before deploying it to a production Screen.

Troubleshooting

Symptom	Likely cause	What to check
Static JSON does not apply	Invalid or mismatched schema	Field names, item IDs, timestamps, timezone, and validation message
Push returns success but Player has old data	Initial Design was not published or refresh has not run	Publish once and wait for the configured refresh interval
Push returns HTTP 409	Reused Idempotency Key or non-increasing sequence	Retry the same body with the same key, or send a new snapshot with a higher sequence
WebSocket connects but does not update	Invalid envelope or wrong `sourceId`	Runtime envelope fields, content hash, and exact Widget ID
WebSocket works locally only	Endpoint is not reachable from the Player or still uses `ws://`	Public/private routing, firewall, TLS certificate, and `wss://` URL
Old content remains visible	Last Known Good is still usable	`expiresAt`, `staleAt`, and the static fallback

Overview

Workspace administration

Getting started

Layarva Studio

Screens

Layarva Edge

Queue Management

Operations and reporting

What you’ll accomplish

Prerequisites

Choose a data source

Add and select a Widget

Use Static JSON

Use Layarva Push API

Use Secure WebSocket

Do you need to create a WebSocket server?

Configure the endpoint

Expected result

Important notes

Troubleshooting

​What you’ll accomplish

​Prerequisites

​Choose a data source

​Add and select a Widget

​Use Static JSON

​Use Layarva Push API

​Use Secure WebSocket

​Do you need to create a WebSocket server?

​Configure the endpoint

​Expected result

​Important notes

​Troubleshooting

​Related guides

What you’ll accomplish

Prerequisites

Choose a data source

Add and select a Widget

Use Static JSON

Use Layarva Push API

Use Secure WebSocket

Do you need to create a WebSocket server?

Configure the endpoint

Expected result

Important notes

Troubleshooting

Related guides