December 21, 2018

Adding Adaptive Icons to a UE4 project for Android

Tech Blog

By Unreal Engine Team

With the release of Android 8.0 Oreo (API 26), support was added for adaptive icons, which can display a variety of different icon shapes across different device models. As more devices utilize these updates, it is increasingly likely to see additional icon shapes as the default. As a result, existing icons may appear incorrectly. To ensure that your icons display properly, you’ll need to add adaptive icons to your project. Fortunately, this is a rather straightforward process that doesn't require you to change the target SDK level in order to work.

Here’s what you need to know:

On the left is a standard icon used as an adaptive icon. On the right is a new icon that has been modified to work with the adaptive icon system.

Icon Types

In the image below you can see how an adaptive icon will look when used with the different icon shapes that the user may choose.

Creating an Adaptive Icon

Using one bitmap icon for adaptive icons is simple. Start by making a new 108 x 108 PNG with the inner 72 x 72 containing the part of your design you need to be sure is shown. When you save this file make sure to name it icon_bg.png.

Adaptive Icon Location

Once the adaptive icon is created you will need to place it in the following location in your UE4 project folder: Build/Android/res/drawable

Doing this will ensure that this new icon is included when your project is built for Android devices.

Registering Your Adaptive Icon

Now you need an icon resource XML to reference your new adaptive icon image. First, create a new folder in Build/Android/res called drawable-anydpi-v26. Create a new XML file inside of this folder called icon.xml and then add the following as the file contents:

<?xml version="1.0" encoding="utf-8"?>
<adaptive-icon xmlns:android="http://schemas.android.com/apk/res/android">
    <background android:drawable="@drawable/icon_bg" />
</adaptive-icon>

You can make a more complicated icon, but this is the quickest way to handle it with the greatest compatibility. Refer to the adaptive icons guidelines for more details using foreground images and vector shapes.

Using A Round Icon

You may wish to also provide support for a round icon to be used for the Circle shape (default on some new Android devices). This requires an addition to the AndroidManifest.xml which is easy to do with the Unreal Plugin Language, but be aware that this requires use of a code project. Note: You can convert any Blueprint-only project to a code project by adding an empty class.

First, make another 108x108 PNG called icon_round.png and copy it into your UE4 project folder: Build/Android/res/drawable. Now you’ll need another icon resource XML to specify in the AndroidManifest.xml. Inside your project’s Build/Android/res/drawable-any-dpi-v26 folder create a new XML file called icon_round.xml and then add the following file contents:

<?xml version="1.0" encoding="utf-8"?>
<adaptive-icon xmlns:android="http://schemas.android.com/apk/res/android">
    <background android:drawable="@drawable/icon_round_bg" />
</adaptive-icon>

The following UPL file should be named AddRoundIcon_UPL.xml and be placed in your project’s Source directory where the module Build.cs file is located. This will normally be the same as your uproject filename, so if your project was named Match3.uproject, you would find this in Source/Match3. Here are the contents for this file:

<?xml version="1.0" encoding="utf-8"?>
<root xmlns:android="http://schemas.android.com/apk/res/android">
	<!-- init section is always evaluated once per architecture -->
	<init>
	</init>

	<androidManifestUpdates>
		<!-- add roundIcon attribute to application -->
		<addAttribute tag=”application” name=”android:roundIcon” value=”@drawable/icon_round”/>
	</androidManifestUpdates>
</root>

Finally, we need to register this UPL file by making an addition to your project’s Build.cs file (Source/Match3/Match3.Build.cs in the previous example). Add the following to this file:

if (Target.Platform == UnrealTargetPlatform.Android)
{
	// Add UPL to add configrules.txt to our APK
	string PluginPath = Utils.MakePathRelativeTo(ModuleDirectory, Target.RelativeEnginePath);
	AdditionalPropertiesForReceipt.Add("AndroidPlugin", System.IO.Path.Combine(PluginPath, "AddRoundIcon_UPL.xml"));
}

Once that has been completed you can now build your UE4 project for Android using the standard packaging workflow. Then, when your project has been deployed to a device, you will see your new icons.

UPDATE: While the above will make it so that your project can use adaptive icons, you will need an extra step for Android 7.1 devices if you are using a round icon. To make sure that your project’s icon is displayed for all version of Android you should also add this step.

First, you will need to open up your project's Build\Android\res folder and create a new folder called drawable-anydpi-v25. Next, open up the newly created drawable-anydpi-v25 folder and make a new file called, icon_round.xml. Then, open up the icon_round.xml file and add the following:

<?xml version="1.0" encoding="utf-8"?>
<layer-list xmlns:android="http://schemas.android.com/apk/res/android">
  <item>
    <bitmap android:src="@drawable/icon_bg" />
  </item>
</layer-list>

Once this has been completed make sure to save the icon_round.xml file and then re-build your project for release. When completed your project will now display the correct icons on any Android device it is used on.