Setting the screen on MAI
Key concepts
Screen vs screen view
When working with MAI, itʼs important to distinguish between a screen and a screen view, as they form the foundation of how information is presented and interacted with on the device.
Screen
A screen is the complete structure that defines both what is shown and how the user interacts with the device. It can contain 1-3 screen views and may also define additional behavior, such as action buttons (mapping physical buttons to actions). The screen is what the application sets when it wants to control both the content and user interactions on the device.
Screen view
A screen view represents a single page of visual content within a screen. When multiple screen views are defined, pagination allows the worker to swipe left or right to navigate between them. Only one screen view is visible at a time.
All screen views within a screen must be of the same template type (either Workflow view or List view). Notification views are treated as a special case: they always stand alone and cannot be combined with other screen views.
Reference IDs
A reference ID is a developer-defined string used to help uniquely identify screens and their elements — such as screen views, components, and action buttons. They allow the integrator to reliably track and handle interactions by linking incoming events (e.g., screen, button, or barcode events) to the specific elements that triggered them using the screen context.
While the SDK does not enforce uniqueness, it is strongly recommended to assign unique reference IDs per screen to avoid ambiguity in event handling. The maximum allowed length is 30 characters — longer values will cause the screen request to be rejected with an error.