> ## Documentation Index
> Fetch the complete documentation index at: https://docs.layarva.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Connect Data to a Widget
> Choose Static JSON, Layarva Push API, or Secure WebSocket for a data-driven 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.
## Add and select a Widget
1. Open **Studio → Designs**, then open a Design.
2. Select **Widgets** in the left toolbar.
3. Find the required Widget category.
4. Double-click the Widget card to add it to the Canvas.
5. Select the Widget on the Canvas.
6. In the right inspector, scroll to **Data Source**.
## Use Static JSON
Static JSON is saved inside the Design. It is also the safest fallback when a dynamic source is temporarily unavailable.
1. Select **Static JSON** under **Data Source**.
2. Open **Advanced JSON**.
3. Paste a payload that matches the selected Widget.
4. Select **Apply JSON**.
5. Preview the Design, then select **Save**.
6. Publish the Playlist again whenever the saved static data changes.
Example for **Today's Schedule**:
```json theme={null}
{
"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.
1. Select **Layarva Push API** under **Data Source**.
2. Open **API Setup & Usage Guide**.
3. Copy the **Unique Widget ID**.
4. Copy the **Workspace API Key** when its full value is shown.
5. Store the key in the sending system's secret manager.
6. Save and publish the Design once.
7. Send complete replacement snapshots to the production endpoint:
```text theme={null}
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](/developers/structured-widget-push) 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.
```text theme={null}
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:
1. Build and host a small relay service.
2. Use a managed WebSocket service and make it emit the required envelope.
3. 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
1. Select **Secure WebSocket** under **Data Source**.
2. Enter an endpoint such as `wss://stream.example.com/widgets/wdg_example`.
3. Set the initial reconnect interval. Five seconds is a reasonable starting point.
4. Configure declarative mapping only if `envelope.data` does not already match the Widget schema.
5. Keep valid Static JSON as the fallback.
6. 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](/developers/widget-websocket) 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 |
## Related guides
* [Create and Edit a Design](/studio/canvas)
* [Push Structured Widget Data](/developers/structured-widget-push)
* [Build a Widget WebSocket Relay](/developers/widget-websocket)
* [Understand Publishing](/studio/publishing)