How to add a launch-screen storyboard for iOS in Unity - App Store requirement by June 30, 2020

[JC-Cimetiere_1]

UPDATE: deadline is extended to June 30, 2020 (see Deadline for App Updates Has Been Extended - Latest News - Apple Developer)
This document provides information, instructions, and examples for how you can meet Apple’s App Store requirement to use a launch-screen storyboard for all app updates and submissions as of April 30, 2020.

The new App Store requirements
Apple will require all apps submitted to the store to have their launch screen (splash screen) built using a proprietary Apple storyboard file. Until now, users have been able to specify a single image or an Apple xib file that Unity handles automatically during player build, inserting it in the correct places in Xcode.
If you are not currently using a storyboard file for your launch screen, you must upgrade before the April 30 deadline.
To create a storyboard file, you need to use Xcode, and therefore a Macintosh computer.

Unity support for storyboard files
Unity 2017.4, 2018.4, and 2019.3 support the use of storyboard files as launch-screen images, however, they do not create them for you. As well, note the following:

• The “Use Storyboard for Launch Screen” option in Unity’s iOS player settings is not selected by default.
  

• For Unity, you need to create the storyboard in Xcode, and then you have to copy it (with any necessary images) into your Unity project.

• Unity will build your specified launch-screen storyboard into an Xcode project, but it will not copy any referenced image assets across automatically unless you put them in the StreamingAssets folder.

• Unity’s built-in Splash Screen (mandatory for Personal Edition) is not affected by this update. The launch-screen storyboard appears before the Unity Splash Screen (if you have enabled it).

We are working on making the launch-screen storyboard as default and improving the overall workflow. For now, see the details below.

Setting up a storyboard in Unity
There are two methods you can use to set up your storyboard:

• Method 1: Copy, link, and reference an existing launch-screen storyboard and assets within the Xcode project, either manually or using automated means, after the project has been built.
• Method 2: Add the storyboard file to your Unity project and place any referenced images in the StreamingAssets folder. Unity treats these as raw assets so it will copy and link them to Xcode and use them in the storyboard.

Method 2 lets you keep the storyboard and images within the Unity project, therefore they are checked into source control. This method leverages Unity’s ability to build the storyboard into an Xcode project and it ensures that images you place in the StreamingAssets folder get copied across too.

This document assumes that a launch-screen storyboard already exists, created on a Macintosh, and all the required images are available. The easiest way to create a launch-screen storyboard in Xcode is to start with a new blank project, work on the launch-screen storyboard in it, then copy the storyboard file and images into your Unity project (this also allows the project to be checked into source control).

Once you have created a simple Xcode project you can edit the LaunchScreen.storyboard, using a splash.png image which you can adjust to scale to fit for example:

In Finder, the project structure would look like the following (we’ve selected the assets of interest).

Copy the LaunchScreen.storyboard file to your Unity project. If you don’t have a StreamingAssets folder in your Assets folder, then create it and copy any images in there.

Now, in the iOS player settings, select Use Storyboard for Launch Screen and browse to the LaunchScreen.storyboard file. Remove any other splash images you may already have.

NOTE: Restart Unity at this point because it may still have the old splash assets cached.

You can now build your iOS project. When you’re finished, open Unity-iPhone.xcodeproj in Xcode and you should see the storyboard file. The images should be in the Unity-iPhone/Data/Raw/ directory. When you select the storyboard file, you should see it with the images. For example:

Confirm that the Unity-iPhone target has the Launch Screen File set to the correct storyboard. For example:

In order for the splash screen images to be copied to the device there are a few final steps.
In the Unity-iPhone build target, select the “Build Phases” tab and open “Copy Bundle Resources”

Click the + button to add a new item(s) to “Copy Bundle Resources” and select “Add Other”

Browse to the "{xcode project}/Data/Raw” directory, select your splash images and click “Open”

Check the options match the above and click “Finish”

Note your image(s) will be added to “Copy Bundle Resources”. This ensures that the splash screen images are installed onto the device correctly.

Other resources
See also the Xcode Storyboard option for Splash Screens forum post (thank you @Marat_Gilyazov ) which includes a link to a complete tutorial on how to make a launch screen storyboard.

[BrunoGaspar_1]

Hi,

Unfortunately we still have projects on Unity 5.5, what are our options regarding this? Any chance we implement this support by ourselves using Unity5.5? any advice?

Thank you in advance.

[tonemcbride]

@JC-Cimetiere_1 Thanks for the detailed tutorial on how to add the storyboard. It looks like the requirement has now been delayed until June 30th which will give people a little more time - Deadline for App Updates Has Been Extended - Latest News - Apple Developer

[JC-Cimetiere_1]

@BrunoGaspar_1

Hi,

Unfortunately we still have projects on Unity 5.5, what are our options regarding this? Any chance we implement this support by ourselves using Unity5.5? any advice?

Thank you in advance.

Hi
You might be able to hack the Xcode project exported by Unity and reference an existing launch-screen storyboard within the Xcode project, but since Unity 5.5 support ended long ago we won’t be able to go back, try or verify or help. Sorry.
The more future proof option is to upgrade to 2017LTS (although support will end this year) or 2018 LTS.
JC

[yuriythebest]

Hi JC-Cimetiere!
If I have older apps ( made with unity 5x), does unity logo use the storyboards?

[Mr-Oliv]

@JC-Cimetiere_1 Thanks for this! I followed Marat’s tutorial (and his script) and got it to work right away by building through XCode. But then I tried uploading the project to Unity’s cloud build and the storyboard splash screen got lost somewhere in the process. Is there anything I can do to make it work?
Thanks
M

[iterbit]

@yuriythebest

Hi JC-Cimetiere!
If I have older apps ( made with unity 5x), does unity logo use the storyboards?

Probably not and you can easily tell the difference.

Apple Storyboards: When you tap any app that uses storyboards, it will show the icon of that app (or whatever file image is used in storyboards - usually it’s app’s icon) right away in an instant. I believe that Apple is enforcing this because it wants the user to feel “native” and gives the impression that Apple product is good quality, responsive etc.

Unity Logo: When you open the app the “black screen” appears for a moment and then you can see Unity Logo (it seems that Unity logo is loaded somewhere in the “middle” of launching the app - before opening your project, but after the storyboards).

In a nutshell: If you never used your own storyboards in a Unity then its very likely that your project does not contain Storyboards file and your app won’t go through a review after June 30.

[yuriythebest]

Ok, I upgraded my project to unity 2018.4.01 and checked the “use storyboard for launch screen” option in the splash section in the player settings. However, when I build 'n launch the app, it’s still the same as before with the “black screen” before the unity logo.

Is my understanding correct that what I did is not enough, and that I’m required to make/add a custom storyboard for this to work? I previously just had the unity logo and no personal splash screen.

[AcidArrow]

Why are you guys always so late with these things? Why are you always behind to support stuff like that and we mobile developers are always rushed into last minute changes and trying to find workaround.

Storyboards have been around for a while, and your support has been super buggy forever.

And even now: Using storyboard as a launch screen makes the launch screen fade to grey before loading the next scene. It’s this bug here : Unity Issue Tracker - [2018.4] A grey screen fades in between the storyboard launch screen and the first Unity scene

You might read that and think, oh, I can just delete .storyboard in info.plist and that will fix the issue. And it does, BUT IT MAKES THE ORIENTATION ISSUE COME BACK.

It has been years and still you can’t figure out a simple way to let us have a professional looking splash screen. Stop dragging your feet.

[Dmitry-Pyalov]

Do storyboards actually work in Unity? Or only on paper.
When I tried Unity’s option - it didn’t work unless you explicitly named the storyboard “LaunchImage” - no custom names for you
And as AcidArrow stated - the storyboard then faded to grey - you need to patch-out some Unity’s Obj-C code to make it work.

Is any of this fixed now? Sorry, I have no spare time to test things out.

[AcidArrow]

Only on paper. But also controller support with input manager is broken for both iOS and tvOS, so at this point storyboard fading to grey seems like a minor issue.

[Dmitry-Pyalov]

@AcidArrow

Only on paper. But also controller support with input manager is broken for both iOS and tvOS, so at this point storyboard fading to grey seems like a minor issue.

Yeah, we also have controller issues, that are still not fixed in 2019.3.10 (my bug report is not even confirmed by Unity). Thank god, it is possible patch those issues in Obj-C or remap some of the buttons in Rewired.

[yuriythebest]

Using unity 2018.4.1, the storyboard works ( I create it using xcode and add it to my unity project), however I still get a warning when building about the lack of storyboard. HOWEVER, in the actual app, everything works fine - the storyboard instantly appears when launching the app, then the unity logo, then the app

Launch images are deprecated in iOS 13.0. Use a launch storyboard or XIB instead

==> Anyone know if this will be an issue when the deadline comes? will apple auto-detect these warnings and think the apps are non-compliant?

[stevenchan_playstudios]

Using unity 2019.2.21, the project is set to use landscape only.
When the device is hold in portrait and open the app for the first time, the launch screen storyboard’s imageview is shown as landscape (correct orientation). However, if you close it and open it again (kept device in portrait), the imageview is sometime autorotate or the main scene will become portrait mode.

[AcidArrow]

@stevenchan_playstudios

However, if you close it and open it again (kept device in portrait), the imageview is sometime autorotate or the main scene will become portrait mode.

Yeah, variations of this issue have been an issue for years with Unity’s implementation.

I just want to note:

We are past the original April deadline.Current builds of Unity have issues with storyboards and also have broken controller support for iOS and tvOS.

If Apple hadn’t pushed back the deadline, we’d all be fucked by Unity’s chronic dragging of feet.

[Time-Jockey]

@Dmitry-Pyalov

Yeah, we also have controller issues, that are still not fixed in 2019.3.10 (my bug report is not even confirmed by Unity). Thank god, it is possible patch those issues in Obj-C or remap some of the buttons in Rewired.

I gave up waiting for a fix too - I’ve written way more native controller/tvos remote bindings than I ever wanted to.

[protopop]

This whole issue has me terrified. I’m on a great update cycle with Wilderless on iOS and I’m worried this will bring it to a halt. I’m also on unity 2019.2 so I’m not even sure a fix will come.

I don’t really have much to say except I wish there wasn’t always these kind of scary updates lurking over the horizon so often. For me it’s yhe worst out of game design and I try to mitigate it though production planning but it’s really tough.

I’m gonna get my next update up and then try to make sure I understand what we need tontonnd get it all prepped so I won’t be stuck unable to update.

[JauntyBearGames]

is the storyboard integration expected for 2019.4?

[homenetgames-jacek]

@yuriythebest

Using unity 2018.4.1, the storyboard works ( I create it using xcode and add it to my unity project), however I still get a warning when building about the lack of storyboard. HOWEVER, in the actual app, everything works fine - the storyboard instantly appears when launching the app, then the unity logo, then the app

Launch images are deprecated in iOS 13.0. Use a launch storyboard or XIB instead

==> Anyone know if this will be an issue when the deadline comes? will apple auto-detect these warnings and think the apps are non-compliant?

If someone wants to remove that warning, solution is here: https://forums.macrumors.com/threads/uilaunchimages-has-been-deprecated-warning-message.2201424/?post=27799290#post-27799290
“Look for Asset Catalog Launch Image Set Name under Asset Catalog Compiler - Options. If I set that previously unset value to a random string in my project, it throws the same compile-time error you mentioned. Try clearing that setting.”

you can do it from postprocess in Unity:

private static void PrepareProject(string buildPath)
    {
        string projPath = Path.Combine(buildPath, "Unity-iPhone.xcodeproj/project.pbxproj");
        PBXProject project = new PBXProject();
        project.ReadFromString(File.ReadAllText(projPath));
        string target = project.TargetGuidByName("Unity-iPhone");

         project.SetBuildProperty(target, "ASSETCATALOG_COMPILER_LAUNCHIMAGE_NAME", "");

        File.WriteAllText(projPath, project.WriteToString());
    }

[MoribitoMT_1]

Hello.

What will happen to existing apps they are not updated?

I have couple of old apps, however I will update them in 2020 August due to some reasons. Will apple remove the apps from market?