Device support and session report
Due to differences in device hardware and performance, AR features often cannot run on all devices. Therefore, it is crucial to accurately determine the support status of the current device when using AR features. This article explains how device availability is represented in Unity and how to obtain information about device support and session availability through the session report (ARSession.Report).
Before you begin
- Learn the basic concepts, components, and workflow of a session through Introduction to ARSession
Device support, session availability and assembly
Each AR feature may support different devices. For example, motion tracking has certain hardware requirements and usually requires device calibration, while image tracking can run on almost any device with a usable camera. Therefore, determining whether an AR application can run on a specific device typically requires knowing which AR features are currently being used, or in other words, determining whether a session can run on the device.
In Unity, the above judgment process is completed during the session assembly (Assemble()) phase. The assembly process determines the final state of the session before startup based on the components included in the session and the current device's support.
If the assembly succeeds, the session will enter the Ready state and can proceed to start and run. If the assembly fails, the session will enter the Broken state, and the specific failure reason can be queried through the session report (ARSession.Report).
Session report
The ARSession.Report property provides the runtime report of the session. A session report contains the following fields:
| Property | Description |
|---|---|
| Availability | Complete availability report |
| BrokenReason | The reason for session failure, valid when the session state is Broken |
| Exception | Specific exception for session failure, valid when the session state is Broken |
In the session report, you can query the availability of each component through Availability, or query the detailed reason for the failure when the session is broken through BrokenReason.
A session report example
For example, on Windows, if a session includes ImageTrackerFrameFilter, CameraDeviceFrameSource, and several other frame source components, the assembly process will check the availability of each component and generate a report as follows:
As shown in the image, although the ARCoreFrameSource component's Availability is Unavailable, because both ImageTrackerFrameFilter and CameraDeviceFrameSource have Availability as Available, the entire session assembly is successful, and the session successfully enters the Ready state.
If we remove CameraDeviceFrameSource from the session, the assembly process will generate the following report:
It can be seen that the number of items in the FrameSources list has decreased from 9 to 8, and although the ImageTrackerFrameFilter component's Availability remains Available, because there are no available frame source components, the entire session assembly fails, and the session enters the Broken state. At this point, the BrokenReason field in the report has the value NoAvailabileFrameSource, indicating that there are no available frame sources.
In addition to the assembly process, the session may also become broken during operation, such as when a running component is accidentally removed. In such cases, the specific reason for the breakage can also be queried through the session report.
Report updates
The session report will change at the following points:
When the first phase of assembly is completed
At this point, a complete session report will be generated, including the component availability report. The Availability section of the session report will be determined at this time and will no longer change.
You can obtain component availability report updates through the AssembleUpdate event.
If the session is started directly after assembly, you can also obtain session report updates through the StateChanged event. The session states to pay attention to include: Ready and Broken.When the second phase of assembly is completed
At this point, a new component availability report will be generated. Unless the session is restarted, the session report will not be updated.
You can obtain component availability report updates through the AssembleUpdate event.When the session starts or is broken during operation
The BrokenReason and Exception sections of the session report will be updated.
You can obtain session report updates through the StateChanged event. The session state to pay attention to includes: Broken.
Report content: Reasons for session failure
BrokenReason indicates the reasons for session failure, including the following scenarios:
| Reason | Description |
|---|---|
| Uninitialized | During assembly, EasyAR Sense failed to initialize successfully |
| LicenseInvalid | During assembly, EasyAR Sense license verification failed or is not applicable for current use |
| SessionObjectIncomplete | During assembly, the session object is incomplete. For example, RendererFeature is not correctly configured in URP |
| NoAvailabileFrameSource | During assembly, no available frame source. For example, all frame sources are unavailable or no frame source is added. Under and only under the default session configuration, this indicates the current device's lack of support for the selected AR functionality |
| FrameSourceIncomplete | During assembly, the frame source is incomplete. This generally occurs when the frame source interface is not correctly implemented during custom frame source creation |
| FrameFilterNotAvailabile | During assembly, there is an unavailable frame filter. This situation only exists under certain assembly options. |
| StartFailed | Startup failure. For example, an exception occurred during startup |
| RunningFailed | Runtime failure. For example, a running component was unexpectedly removed, or RendererFeature is not correctly configured in URP, etc. |
Report content: Availability information
Availability provides availability information for each component in the session. It contains the following fields:
| Field | Description |
|---|---|
| FrameFilters | List of frame filter availability checked during the assembly process |
| FrameSources | List of frame source availability checked during the assembly process |
| PendingDeviceList | Pending device list download tasks |
| DeviceList | Device list download result |
The PendingDeviceList and DeviceList fields are used to indicate the download status of the device support list. When the first stage of assembly is completed, the assembly will enter the second stage if and only if PendingDeviceList is not empty. This condition can be used to determine whether AssembleUpdate will be executed a second time.