Player-level overlay

Overview

The player-level overlay, also known as the firmware overlay, allows the player to display an independently managed project on top of the main content. Unlike an overlay layer included within a project or an ARYA alert, a player-level overlay is configured directly on the player using the URL of an externally hosted project.

It is particularly suited to emergency alerts, evacuation instructions, corporate notifications, building-management messages, and other event-driven content that must appear independently of the project currently playing. The overlay project can be updated without modifying or republishing the main content.

The player-level overlay is rendered above all other content displayed by the player, including alerts managed through ARYA Enterprise.

Requirements

Player model: HMP400/W, iBX410/W, iBX440, HMP350, HMP300, and third-party DSOS players
Firmware version: DSOS 4.8.6 or later
Feature Set: KIOSK or SYSTEMS
Web server for deployment

How it works

A typical deployment involving this feature consists of:

A main digital signage content published or scheduled (if using ARYA) on the player.
A dedicated overlay project hosted on a web server.
An overlay URL specified in the player configuration.

The player renders the main content and, on top of it, the overlay project loaded from the URL specified in the player configuration. This separation makes it possible to maintain a single overlay project centrally instead of adding and maintaining a copy of the alert layer in every main project.

Other overlay mechanisms

It is possible to create overlayed content through other means, such as:

In a DSaaS deployment, where the player content is managed through SpinetiX ARYA Enterprise, an alert can be created in ARYA and published on the player to be displayed above the existing scheduled content.
In a Self-Manage deployment, where the player content is usually created with Elementi, a dedicated layer can be added in the root index file of the Elementi project and positioned on top of everything else. This is referred to as an in-project overlay.

But the player-level overlay encompasses both scenarios; is configured directly on the player and is displayed above all other content, including ARYA alerts.

Comparison

The table below details the differences between these mechanisms:

Characteristic	ARYA alert	In-project overlay	Player-level overlay
Configuration	Created and managed in ARYA	Added within the Elementi project	Added within the player configuration
Source	Alert content managed through ARYA	Part of the published project	External project referenced by URL
Scope	Content scheduled on the player through ARYA	The project containing the overlay	All content displayed by the player
Deployment	Deployed through ARYA	Published with each project	Configured on each player
Maintenance	Updated through ARYA	Requires modifying and republishing the project	Updated independently on the web server
Availability	Available to players managed through a SpinetiX cloud account with ARYA Enterprise subscription	Present only in projects that include it	Loaded independently of the existing content
Rendering order	Above ARYA-scheduled content	Part of the main project, should be on top of the rest of the content	Above all content, including ARYA alerts
Typical purpose	Centrally managed alerts in a DSaaS deployment	Project-specific visuals or interactions	Player-level alerts independent of the content-management system

Behavior and limitations

The player-level overlay is rendered above the regular content and shares the execution environment of the main project. It behaves as if the top-level index.svg document of the main project contained a full-screen SVG <animation> element referencing the overlay project. Although the overlay is hosted and maintained separately, it is attached to the top-level document of the main project rather than executed as a separate top-level application. This allows the overlay to receive UI events and communicate in both directions with the main content.

The overlay does not have separate local storage. It shares local storage with the main project, so developers should use distinct key names to avoid collisions. When inactive, the overlay project should normally remain transparent so that the main content remains visible and usable.

The player may cache the overlay project and its referenced resources. When updating the project on the web server, avoid immediately removing or overwriting resources referenced by the previously published index.svg. A player might continue using a cached copy of that document while downloading its associated resources. If one of those resources is no longer available, playback may stop or the displayed image may freeze. Restarting the player does not necessarily resolve the problem because it does not invalidate cached content. If this situation occurs, reset the player cache to force the overlay project and its resources to be retrieved again.

Configuration

At this time, the player-level overlay feature is not exposed in Control Center, so it must be configured through the Configuration API, using a configuration file or by sending a set_config RPC command containing the configuration string. See more about how to use the Configuration API.

To add or change an overlay, use the <overlay> element with a URL pointing to the root index file of the overlay project, such as:

<overlay>https://server.example.com/overlay/index.svg</overlay>

To remove the current player overlay, use an empty <overlay> element:

<overlay/>

The <overlay> tag requires a player reboot to become effective, so make sure to include the <reboot/> tag as well.

Example

In case the server requires authentication, you can provide them though the <credential> element within the same configuration file, as shown below:

<?xml version="1.0"?>
<configuration version="2.2">
    <credential>
        <server>https://server.example.com/</server>
        <password>Your_38_characters_STRONG_PASSWORD! ;)</password>
        <username>spx.content</username>
    </credential>
    <overlay/>
    <overlay>https://server.example.com/overlay/index.svg</overlay>
    <reboot/>
</configuration>

Best practices

Use a player-level overlay when content must be maintained independently of the main projects or content-management system.
Keep the configured overlay URL stable so that updates do not require configuration changes across the player fleet.
Keep the overlay focused on a clearly defined purpose, such as alerts or notifications.
Host the overlay project on a reliable web server accessible to every target player.
When updating the project, retain previously referenced resources for at least as long as players may continue using a cached version of index.svg and its resources.
Design the overlay to remain transparent when no message is active.
Use distinct local-storage key names to prevent conflicts with the main project.
Test UI-event handling and communication with the different main projects used on the player.
Consider the rendering priority when both ARYA Enterprise alerts and a player-level overlay are configured.