Openbravo/Orisha Commerce - Building a Reliable Customer Display

 In retail POS systems, the customer display is a small but important part of the checkout experience. It shows the customer what is being scanned, the item quantity, price, discounts, totals, payment status, and sometimes promotional or screensaver content.

Our requirement looked simple at first:

Open a customer-facing display automatically on the second monitor and keep it updated from WebPOS and SCO.

But once we started implementation, the browser security model made this much more complex than expected.

Requirement

The business requirement was to support a browser-based Customer Display for:

• WebPOS checkout
• SCO, Self Checkout
• Customer-facing second monitor
• Automatic opening of the display
• No repeated display selection by the cashier
• Full-screen or app-mode display
• Recovery if the display browser is closed
• Recovery if the external monitor is disconnected and reconnected
• Support for translated labels
• Product image display, including SCO-specific image configuration
• HTTPS/WSS support
• Low memory usage on store machines

The expected behaviour was that the POS application should control the customer display without disturbing the cashier.

Initial Browser-Based Approach

The first approach was to use browser APIs, mainly the Presentation API.

The Presentation API works well when the user manually selects a display. Once selected, the browser creates a presentation session, and the POS can communicate with the display page.

However, we quickly found important limitations.

Challenges With Presentation API

The browser does not allow a web application to automatically select an external display. This is intentional browser security behaviour.

A website cannot silently decide:

• Which monitor to use
• When to open a second screen
• whether to reopen it after a browser restart
• whether to bypass the display picker

The browser requires user interaction and display selection because opening windows on external screens can be abused by malicious websites.

We also reviewed PresentationRequest.reconnect(). It can reconnect to an existing active presentation session if the session is still alive. But it does not reliably handle restart cases.

If Chrome is killed, the machine restarts, or the presentation session is closed, the old session is no longer guaranteed to exist. Saving the presentation session ID is useful only while the browser still has an active session. It is not a permanent device binding.

So the Presentation API was not enough for an autonomous retail customer display.

Window Management API Review

We also reviewed the Window Management API. It can help detect screens and position windows, but it still has browser restrictions.

Limitations include:

• User permission is required
• browser chrome/title bar cannot be fully controlled like a native app
• Popup behaviour differs between browsers
• Full kiosk-like behaviour is not guaranteed
• Support across all major browsers is not consistent

Since our application needs to support multiple browsers and behave reliably in retail stores, this was not the best primary approach.

Why HWM Was Chosen

The better approach was to move the display-control responsibility to HWM (Hardware Manager).

HWM runs locally on the store machine and is not limited in the same way as browser JavaScript. It can launch a browser process using OS-level commands and pass proper launch arguments.

With this approach:

• POS communicates with HWM through WebSocket
• HWM opens the customer display browser
• HWM chooses the screen using the configuration
• HWM can use a dedicated browser profile
• HWM can prevent duplicate customer display windows
• HWM can reopen the display when it is closed
• HWM can monitor display/browser health
• POS only sends display data, not display-control commands, directly to the browser

This provides greater control and makes the solution suitable for real-world store operations.

HWM-Based Flow

The final flow is:

1. WebPOS or SCO starts.
2. The customer display module connects to HWM using WebSocket.
3. POS sends a OPEN request to HWM.
4. HWM launches Chrome or Edge with the configured customer display URL.
5. The browser opens in app/fullscreen mode on the configured screen.
6. POS sends order updates to HWM.
7. HWM forwards display data to the customer display page.
8. Customer display updates item lines, totals, translations, payment state, and screensaver.
9. If the display is closed or the monitor is disconnected, the HWM watchdog detects this and attempts to reopen it when possible.

Issues Faced and Fixes

Duplicate display windows

Initially, multiple display windows were opening from different flows. We fixed this by adding duplicate prevention and using a dedicated customer display profile.

Display opened on the wrong screen.

This required OS-specific testing. Screen index and secondary display behaviour differ between Mac and Windows. We added configurable properties such as screen mode and screen index.

Browser closed manually

If the customer display browser was closed, HWM now tracks the process/window and can reopen it.

Monitor unplug/replug

When the display cable was disconnected, the old browser session could remain broken. We added an HWM watchdog and force-reopen behaviour. Browser-side unplug detection is kept only as a secondary signal.

Translations not reflected

Translated labels were correctly sent over the socket but not always rendered. We fixed the display update flow so that received labels are applied properly on the customer display page.

Product images in SCO

SCO uses its own image configuration:

• ImageDomain
• DefaultProductImage
• EM_Decim_Imagename

We implemented the same logic for the second display. If the product has an image name, the display builds the image URL from the configured image domain. If not, it uses the default product image.

Large image payloads

Sending full image data through the socket caused performance and rendering issues. We changed the approach to prefer image URLs where possible, rather than large inline image payloads.

HTTPS/WSS

For HTTPS environments, WebSocket also needs to use WSS with trusted certificates. Invalid local certificates caused browser connection errors, so certificate/keystore setup became part of the deployment checklist.

Benefits of the HWM Approach

The HWM approach gave us the control that browser APIs could not provide.

Main benefits:

• No browser display picker required
• automatic display launch
• better recovery from browser close
• better recovery from monitor disconnect
• configurable browser path/profile
• support for WebPOS and SCO
• reduced browser API dependency
• works better for store restart scripts and daily operations
• suitable for low-resource POS machines

Remaining Considerations

HWM must run in a graphical user session. If it runs in a headless or server-only mode, it cannot reliably open a browser on a physical monitor.

Also, true kiosk behaviour depends on the browser and OS launch options. Chrome app mode/fullscreen gives good results, but full control of the title bar and browser UI is still OS- and browser-dependent.

Conclusion

The main lesson from this implementation is that browser APIs are intentionally restrictive in controlling external display. They are good for user-driven presentation flows, but not ideal for autonomous retail POS customer displays.

For a real store environment, HWM is the better architectural owner for display control. The browser-based POS should focus on business data and UI state. At the same time, HWM should handle local machine responsibilities like launching the display, selecting the monitor, preventing duplicates, and recovering from failures.

This separation made the customer display more reliable, more supportable, and better aligned with retail operations.