Custom Data with Data Sources and Repeaters

ScreenManager can pull live data from external APIs and use it in your scenes. Data Sources define where the data comes from. Repeaters take an array from that data and render a template once per item — like a loop in a spreadsheet.

Overview

External API → Data Source → Repeater (array) → Template (Text, Image, QR code, …)

1. You register an API endpoint as a Data Source.
2. You add a Repeater to a scene and point it at that source.
3. You design a template inside the repeater (text, images, etc.).
4. Each child element can read fields from the current item in the array.
5. On playback, each screen fetches fresh data and renders one instance per array item.

Part 1: Create a Data Source

Where to find it

Go to Data Integrations → Data Sources in the admin panel, then click Create Data Source.

You need permission to manage data integrations (typically Account Administrator or Content & Device Manager).

Step 1 — Basic configuration

• Name — A label you will recognize in the scene editor (e.g. "Store Products API").
• Description — Optional notes for your team.
• URL — The HTTP(S) endpoint that returns JSON. Must be reachable from ScreenManager (see Proxy mode below).
• Headers — Optional JSON object for authentication, e.g. {"Authorization": "Bearer YOUR_TOKEN"}.
• Proxy and cache — When enabled, ScreenManager fetches the URL on your behalf and caches responses. Recommended for most setups.
• Refetch interval — How often cached data is refreshed: every minute, hour, or day.
• Active — Inactive sources are ignored during playback.

Step 2 — Test and configure sample data

After saving the basic settings:

1. Fetch live data — ScreenManager calls your API and shows the response.
2. If your URL contains {{deviceId}}, pick a device in the test step so the placeholder is replaced correctly.
3. The response is saved as example data. This is used in the scene editor when no live fetch is available (e.g. while designing on your laptop).

You can also paste JSON manually if the API is not reachable from the admin panel.

Step 3 — Review and save

Confirm the settings and finish. The data source appears in the list and is available in the scene editor.

URL placeholders

Use {{deviceId}} in the URL when each screen should call a device-specific endpoint:

https://api.example.com/devices/{{deviceId}}/status

During playback, ScreenManager replaces {{deviceId}} with the ID of the player showing the content.

Proxy vs. direct fetch

• Proxy and cache ON — ScreenManager server fetches the URL, caches it, and players receive the cached JSON. Hides API keys from devices and reduces load on your API.
• Proxy and cache OFF — Players receive the URL and headers and fetch directly. Use only when the API must be called from each device (e.g. local network).

For most public or cloud APIs, keep Proxy and cache enabled.

API requirements

• Response must be JSON.
• Response size is limited (configurable per source; default is generous for typical APIs).
• The endpoint should return 200 OK with a JSON body on success.

Example API response:

{
  "products": [
    { "name": "Espresso", "price": 3.50, "imageUrl": "https://cdn.example.com/espresso.jpg" },
    { "name": "Latte", "price": 4.20, "imageUrl": "https://cdn.example.com/latte.jpg" },
    { "name": "Croissant", "price": 2.80, "imageUrl": "https://cdn.example.com/croissant.jpg" }
  ]
}

Part 2: Use a Repeater in a Scene

What a Repeater does

A Repeater reads an array from your data source and renders its child items once per element. If the array has 5 products, you get 5 cards (or rows, or slides) from one template.

Add a Repeater

1. Open a Scene in the editor.
2. Add a Repeater from the scene items panel.
3. Resize and position the repeater on the canvas — it is the container for all repeated instances.

Bind the data source

Select the repeater and open its toolbar:

1. Data source — choose the source you created.
2. Data path — path to the array inside the JSON (dot notation).

For the example above, the path is:

products

If items are nested deeper:

data.forecast

Use the data path editor to browse the JSON and pick the path visually.

Choose a layout

• Vertical — Stacked list (menu items, news headlines)
• Horizontal — Side-by-side row (icon + label pairs)
• Grid — Cards in rows and columns (product catalog)
• Slideshow — One item at a time with timed transitions (featured products, announcements)

You can adjust spacing between items and, for slideshow, duration, transition, and loop.

Advanced settings (optional)

• Offset — skip the first N items.
• Maximum items — cap how many are shown (useful for large APIs).
• Minimum items — pad with empty slots if the array is shorter than expected.

Part 3: Design the Template

Two editing modes

• Container mode (default) — Repeater size, position, data binding, layout
• Template mode — Child items inside one instance of the repeater

To design content, click Edit Template (or double-click the repeater). A banner shows you are in template mode. Changes apply to every repeated instance.

Exit template mode when you are done designing.

Add child items

In template mode, drag items into the repeater:

• Text — names, prices, descriptions
• Image — product photos, icons
• QR code — dynamic links per item
• Other supported scene items

Position each child within the repeater bounds. Positions are relative to each instance, not the whole scene.

Bind fields with "Parent Item"

Inside a repeater, child items can use a special source called Parent Item ($parent). That is the current array element for that instance.

Example: for { "name": "Latte", "price": 4.20 }:

• Text — Parent Item, path name → shows "Latte"
• Text — Parent Item, path price → shows "4.20"
• Image — Parent Item, path imageUrl → shows the product image

Text items

1. Select the text item in template mode.
2. In the text editor toolbar, insert a data source placeholder.
3. Choose Parent Item.
4. Set the path (e.g. name, price, description).

Image items

Configure the image URL from Parent Item and the path to the image field (e.g. imageUrl).

QR codes

Set the QR content from Parent Item (e.g. path productUrl).

Preview while editing

In the editor, the repeater uses example data from the data source so you can see realistic content while designing. On devices, live data is fetched according to the refetch interval.

Part 4: Publish and Play

1. Save the scene.
2. Add it to a playlist or schedule.
3. Publish to your devices.

On each device:

• ScreenManager fetches (or reads cached) data from the configured source.
• The repeater builds one instance per array item.
• Each instance shows the template filled with that item's fields.

If the API fails or returns an error, affected fields may be empty; check the data source test step and device logs if content does not appear.

Example: Product list

Goal: Show a vertical list of products with name, price, and image.

1. Data source

• URL: https://api.myshop.com/v1/products
• Headers: {"Authorization": "Bearer …"}
• Proxy and cache: ON
• Refetch interval: Hour
• Example data: paste or fetch a sample response

2. Scene setup

• Add a Repeater (vertical layout, 5% spacing).
• Data source: Store Products API
• Data path: products

3. Template (in template mode)

• Text — Parent Item → name (large, top)
• Text — Parent Item → price (smaller, below name)
• Image — Parent Item → imageUrl (left or background)

4. Result

Three products in the API → three rows on screen, each with its own name, price, and image.

Example: Rotating announcements (slideshow)

Goal: Cycle through featured offers every 8 seconds.

1. Repeater with slideshow layout.
2. Data path: featured (array of { title, subtitle, imageUrl }).
3. Template: full-size Image + Text overlays using Parent Item paths.
4. Slideshow: 8 s per slide, fade transition, loop enabled.

Nested repeaters

You can put a repeater inside another repeater when data is hierarchical (e.g. categories, each with a list of products).

• The outer repeater uses your API data source.
• The inner repeater can use Parent Item as its data source and a path to a nested array (e.g. items on each category object).

Avoid very deep nesting; two levels is usually enough.

Troubleshooting

• No items shown — Data path must point to a JSON array. Test the path in the data path editor.
• Wrong number of items — Advanced settings: offset, min/max items.
• Placeholder text in editor only — Example data may be missing; fetch or paste sample JSON on the data source.
• Works in editor, not on device — API unreachable from ScreenManager (proxy mode), auth headers wrong, or source inactive. Re-test with Fetch on the data source.
• Stale data on screens — Shorten refetch interval or use force refresh when testing.
• Empty fields in template — Path typo, or field missing in API for some items. Inspect raw JSON in the data source test step.
• Cannot edit child items — Enter template mode on the repeater first.
• {{deviceId}} not replaced — URL must contain exact {{deviceId}}; test with a real device selected in the data source form.

Permissions

Managing data sources requires Data Integration permissions (read / update / delete depending on action). Users without access will not see Data Integrations or data source options in the scene editor.