Screen configuration options
Screen Timer
The Screen Timer is an optional screen-level feature that allows a screen action to be triggered automatically after a specified delay. It is defined at the screen level, not for individual screen views.
By default, the Screen Timer is disabled. When enabled, the timer starts as soon as the screen becomes active on the MAI device.
Configuration
When enabled, the Screen Timer is defined by two parameters:
Delay – Duration in milliseconds after which the action will be triggered. It must be a positive integer.
Action – A screen action that should be executed when the timer expires.
The timer must include both parameters to be valid.
Timer behavior
Only one timer can be defined per screen.
The timer starts automatically once the screen is rendered.
The timer is cancelled when the screen is replaced.
If the user performs an action (e.g., presses an action button), the timer is not automatically cancelled unless the resulting screen transition replaces or hides the current screen.
The timer works independently of screen orientation or hand preference.
Supported screen actions and behavior
When the Screen Timer expires, it triggers a specific screen action:
Navigate back – Closes the current screen and returns to the previous one (if any). Useful for creating automatic back navigation in workflows, to make time-limited notifications that should block user workflow for a limited time period.
Notify – Triggers a screen event (
display_v2-eventin Streams API) of typeScreenTimerExpired, including the screen context. This allows the integrator to handle the timeout with custom logic.Click on screen component – Simulates a click on a defined screen component on the same screen after the delay. Useful for automatically triggering UI components with explicit (e.g., button or list item) or implicit (e.g., opening a keyboard for a text field) click behavior. For example, a short delay can be used to open a keyboard automatically shortly after the screen is shown.
None – No action.
Override screen orientation
By default, MAI uses the screen orientation chosen by the user (portrait or landscape). In most cases, the integrator does not need to change this.
However, in some situations, a specific screen may require a fixed orientation due to layout constraints or limited usability in certain orientations. To handle this, the integrator can explicitly override the orientation for a single screen using the forcedOrientation flag in the setScreen request (display_v2 in Streams API).
Available options
Portrait – Forces the screen to display in portrait mode, regardless of user preference.
Landscape – Forces the screen to display in landscape mode, regardless of user preference.
Default – Uses the user’s preferred orientation (default behavior). This is the default behavior if no value is provided.
Note
The override applies only to the current screen. Once the screen is replaced, the device returns to the user’s preferred orientation.
When to use
Use orientation override when:
A screen layout is designed specifically for one orientation.
A template is not supported or recommended in a certain orientation (see Template library).
Screen readability or interaction is significantly affected by orientation.
You want to ensure consistent layout for a specific screen regardless of user settings.