Table of Contents

Check session availability and device support

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

Before you begin

Get reports in the startup process

If the session is started directly after assembly, the session report can be obtained through the StateChanged event.

It is necessary to subscribe to the StateChanged event before the session starts. It is usually safe to complete the subscription in Awake():

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

In the event handler, the session states that need attention include: Ready and Broken. The Ready state indicates that the session has been successfully started, which means the session is available on the current device. The Broken state indicates that the session failed to start, which means the session is not available on the current device.

The Broken state does not always appear when the device is not supported. Therefore, it is also necessary to use SessionReport.BrokenReason to obtain 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 not available on the current device
        if (Session.Report.BrokenReason == SessionReport.SessionBrokenReason.NoAvailabileFrameSource ||
            Session.Report.BrokenReason == SessionReport.SessionBrokenReason.FrameFilterNotAvailabile)
        {
            // the selected component is not supported by the current device
        }
        else
        {
            // device-independent reasons
        }
    }
}

The occurrence of SessionReport.SessionBrokenReason.NoAvailabileFrameSource and SessionReport.SessionBrokenReason.FrameFilterNotAvailabile indicates that the session component is not available on the current device; other reasons are usually device-independent. Strictly speaking, the occurrence of these two reasons means that the AR function under the current configuration (and only this configuration) cannot run on this device. The configuration refers to the functions and settings selected in the session object. Detailed availability reports can be obtained from Report.

For the case of SessionReport.SessionBrokenReason.NoAvailabileFrameSource, if the device is found to be supported during the network update of the device list when starting the session, the session may automatically recover.

Get reports before starting

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

You need to subscribe to the AssembleUpdate event before assembling the session,

Session.AssembleUpdate += OnAssembleUpdate;

In the first stage of assembly, you can still use ARSession.SessionState and Report to determine the session support status. However, the second-stage report will not be updated to the session.

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

You need to 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.

At the same time, you also need to pay attention to the availability of components in the SessionReport.AvailabilityReport.FrameFilters list. However, the judgment criteria will vary depending on the assembly options, requiring either all frame filters to be available or any number of frame filters to be available. By default, all frame filters are required to be available.

Under the default configuration, you can use the following code to determine whether the 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, you can start the session
        Session.StartSession();
    }
    else
    {
        // session components are not available on the current device
    }
    if (report.PendingDeviceList.Count <= 0)
    {
        Session.AssembleUpdate -= OnAssembleUpdate;
    }
}

Note that the AssembleUpdate event may be triggered twice. In the above code example, the event subscription will be canceled after confirming that the components are available.

This judgment method cannot determine other errors that may occur during the session startup process, but these errors are usually device-independent. If necessary, you can make supplementary judgments through the StateChanged event after starting the session.

Options when the session component is unavailable

In application development, it is generally desirable to provide compatibility support for as many devices as possible. Therefore, when the session component is unavailable on the current device, the following options can be considered:

  • Fall back to other AR features
    Modify the session component configuration to select AR features supported by the current device. Refer to Creating a session to learn how to modify the session component configuration.

  • Provide a non-AR experience
    When the session component is unavailable, offer a non-AR experience. For example, in navigation scenarios, providing traditional 2D navigation can be very useful if AR navigation is not feasible.

  • Prompt the user to switch devices
    In some application scenarios, users may use devices that do not support AR features. In such cases, you can prompt the user to switch devices for a better experience.

When choosing these solutions, you can 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 is still necessary to provide clear user prompts to inform users of the current device limitations.

Next steps