Determine session availability and device support

Before starting AR, it's usually necessary to check whether the session is available and if the current device supports the required AR features. This article explains how to perform these checks.

Before you begin

Understand the basic concepts, components, and workflow of sessions through Introduction to ARSession
Learn the basics of device support and session reports in Unity through Device support and reports
Understand how to create a session

Get reports during startup flow

If you start the session directly after assembly, you can obtain session reports through the StateChanged event.

Subscribe to the StateChanged event before session start. It's generally safe to complete the subscription in Awake():

void Awake()
{
    Session.StateChanged += HandleSessionStateChange;
}

Session states to focus on in the event handler include: Ready and Broken. The Ready state indicates that the session has started successfully, meaning the session is available on the current device. The Broken state indicates that the session failed to start, meaning the session is unavailable on the current device.

The Broken state doesn't always appear when the device is unsupported. Therefore, you also need to use SessionReport.BrokenReason to get the specific failure reason.

void HandleSessionStateChange(ARSession.SessionState status)
{
    if (status == ARSession.SessionState.Ready)
    {
        // session is available on the current device
    }
    else if (status == ARSession.SessionState.Broken)
    {
        // session is unavailable on the current device
        if (Session.Report.BrokenReason == SessionReport.SessionBrokenReason.NoAvailabileFrameSource ||
            Session.Report.BrokenReason == SessionReport.SessionBrokenReason.FrameFilterNotAvailabile)
        {
            // selected components are not supported on the current device
        }
        else
        {
            // device-independent reasons
        }
    }
}

The reasons SessionReport.SessionBrokenReason.NoAvailabileFrameSource and SessionReport.SessionBrokenReason.FrameFilterNotAvailabile indicate that the session components are unavailable on the current device; other reasons are typically device-independent. Strictly speaking, these two reasons mean that the AR functionality under the current configuration (and only this configuration) cannot run on this device. Configuration refers to the selected features and settings in the session object. Detailed availability reports can be obtained from Report.

For SessionReport.SessionBrokenReason.NoAvailabileFrameSource, the session might automatically recover if the device is found to be supported during online device list updates when starting the session.

Get reports before startup

If you want to make a judgment before starting the session and decide whether to start it based on specific circumstances, you can manually call Assemble() and use the AssembleUpdate event to obtain component availability reports.

Subscribe to the AssembleUpdate event before session assembly:

Session.AssembleUpdate += OnAssembleUpdate;

During the first phase of assembly, you can still use ARSession.SessionState and Report to determine session support. However, reports from the second phase won't update to the session.

Therefore, when manually calling Assemble(), you generally need to handle component availability reports in the AssembleUpdate event to determine whether the session is available on the current device.

Focus on the availability of components in the SessionReport.AvailabilityReport.FrameSources list. If any frame source component is available, then the SessionReport.AvailabilityReport.FrameSources part is available on the current device.

Also pay attention to the availability of components in the SessionReport.AvailabilityReport.FrameFilters list. But the judgment criteria vary depending on assembly options—either requiring all frame filters to be available or any number of frame filters to be available. By default, all frame filters must be available.

Under default configuration, you can use the following code to determine if session components are available on the current device:

void OnAssembleUpdate(SessionReport.AvailabilityReport report)
{
    if (report.FrameSources.Any(f => f.Availability == SessionReport.AvailabilityReport.AvailabilityStatus.Available) &&
        report.FrameFilters.All(f => f.Availability == SessionReport.AvailabilityReport.AvailabilityStatus.Available))
    {
        Session.AssembleUpdate -= OnAssembleUpdate;
        // session components are available on the current device, can start session
        Session.StartSession();
    }
    else
    {
        // session components are unavailable on the current device
    }
    if (report.PendingDeviceList.Count <= 0)
    {
        Session.AssembleUpdate -= OnAssembleUpdate;
    }
}

Note that the AssembleUpdate event may trigger twice. In the code example above, the event subscription is canceled once component availability is confirmed.

This judgment method cannot detect other errors that may occur during session startup, but these errors are usually device-independent. If needed, you can supplement the judgment through the StateChanged event after starting the session.

Options when session components are unavailable

In application development, it's generally desirable to provide compatibility support for as many devices as possible. Therefore, when session components are unavailable on the current device, consider the following options:

Fallback to other AR features
Modify session component configurations to select AR features supported by the current device. Refer to create a session to learn how to modify session component configurations.
Provide non-AR experience
Offer a non-AR experience when session components are unavailable. For example, in navigation scenarios, providing traditional 2D navigation is very useful if AR navigation cannot be implemented.
Prompt users to switch devices
In some application scenarios, users might use devices that don't support AR features. You can prompt users to switch devices for a better experience.

When choosing these solutions, weigh them against the specific needs of the application and the user base. In AR applications, if some devices truly cannot provide AR or fallback solutions, it's still necessary to provide good user prompt information to help users understand the current device limitations.

Next steps