These Mistakes Can Make Your AR Foundation App Display a Black Screen

Photo by Daniel Frank on Unsplash

This post was first published at Medium

In recent years, AR technology has developed rapidly. Following the release of the amazing ARKit 3 last year, this year Apple released ARKit 4 on WWDC 2020. And Unity also has expanded its AR Foundation to add these new features from ARKit 3.5 and ARKit 4 quickly. With the development of AR technology, more and more developers use Unity’s AR Foundation to develop AR applications running on different platforms.

AR Foundation In Unity

However, as a developer using Unity’s AR Foundation, there are some mistakes that may make you feel bad when developing an AR app. This post will detail 4 common mistakes that cause the AR application to display a black screen on your phone.

Mistake #1 You Didn’t Install The Platform Package For The Specific Platform

I think it’s the most common mistake that AR developers may encounter when using AR Foundation in Unity to develop AR apps. As you can see from the architecture of the AR solution in Unity above, you will find that AR Foundation is just an abstract layer for developers to develop their AR App in Unity using C# programming language.

If you only install the AR Foundation package via the Unity package manager, it won’t install the platform package required on a specific platform automatically for you. And you have to install it/them manually.

For example, if you want to create an AR app on the iOS platform, then you need to install the ARKit XR Plugin.

Mistake #2 The Device Doesn’t Support The AR Function

It is similar to the first mistake, but it is easily ignored by developers, which is the capabilities of the device itself.

Let’s look at the architecture of the AR Foundation again. Yes, there is a lower level than Unity’s platform package, which is the SDK layer, provided by the devices.

This mistake is more common on Android devices than iOS devices, for example, the Android phones that cannot install Google’s AR Core SDK, or the Android OS version of the device does not meet the requirements of AR Core SDK.

Mistake #3 The Universal Render Pipeline Is Not Set Up Correctly

If you want to use the Universal Render Pipeline instead of the built-in render pipeline in Unity, then you need to update your AR Foundation package and the corresponding ARKit XR Plugin package to 3.0.0 or later because the default verified version of AR Foundation package on Unity 2019.x is 2.x.x.

Next, you install the Universal RP package and set the UniversalRenderPipelineAsset to the Graphic setting of your project to replace the built-in render pipeline. Build your AR app to run on your iPhone, then you will see a black screen.

In addition to upgrading your AR Foundation version, you also need to set the Universal Render Pipeline correctly to successfully replace the built-in rendering pipeline. For the AR app, we need to add the AR Background Renderer feature to the URP renderer. You can see the gif below.

Mistake #4 Update To AR Foundation 4.0.x And Did Not Set Up Correctly

Presumably, you have corrected all the mistakes above , and you may encounter a fourth mistake that causes a black screen.

Now, let’s update the AR Foundation package and the corresponding platform package (ARKit XR plugin) to 4.0.2, and keep all other settings as before. Build the app and run it on your iPhone, and you will get another black screen with the following error message.

It’s not hard to fix this error, you just need to check the Plugin-providers in the XR Plug-in Management panel. But you don’t have to do it before AR Foundation 4.x.

Now your app should run as expected.

Thanks for reading and hope it’s helpful.

Have a chat at

Subscribe To Jiadong Chen's Blog

Jiadong Chen
Senior Software Developer

HusbandㅣProgrammerㅣAuthorㅣBloggerㅣSpeakerㅣMicrosoft @MVPAward In Developer TechnologiesㅣPreviously @Unity3d ㅣOpinions = my own.

comments powered by Disqus