Adding Icon Images to an Asset Catalog

1. Select the asset catalog in the project navigator. It is named Assets.xcassets for new projects, or Images.xcassets for migrated projects, by default.

2. From the set outline view (left column), select the app icon set. For new or migrated projects it will be named 'AppIcon'. You may need to create an icon set by clicking the (+) button in the bottom left corner of the editor and choosing App Icons and Launch Images > New iOS App Icon from the context menu.

The set will only contain image wells for icons that are relevant depending upon the project's configuration at the time the asset catalog was created. If an image well is missing, expand the attributes inspector and select the appropriate options from the pull-down menus under the App Icon section, depending upon the project's deployment target and supported devices.

1. Drag images from the Finder onto each image well to configure the associated icon.

Asset catalogs create a copy of images added to them. If you had previously added the images as resources to your project you can safely remove them.

1. Configure your application to use the new icon set.

2. 1. Select the project in the project navigator.

   2. Select the application target from the list in the left column of the project editor.

   3. Switch to the General pane at the top of the project editor.

   4. Select the app icon set from the App Icons Source popup menu under the App Icons And Launch Images section.

Migrating an iOS App Icon Set

Simplify image management by moving existing app icons into an asset catalog.

1. In the project navigator, select your target.

2. Open the General pane, and scroll to the App Icons and Launch Images section.

3. Click the Use Asset Catalog button next to the App Icons Source label.

1. Configure any options in the dialog. To choose a different asset catalog or to create a new one, click on the pop-up menu. Choose an existing asset catalog or choose New Asset Catalog to create a new one. The menu is shown when there is at least one asset catalog in the project.

2. Click the Migrate button. If there is no asset catalog or if you selected New Asset Catalog from the pop-up menu, you will be prompted to create one. Canceling creation of the new asset catalog will cancel the migration.

The icons are migrated to the new or existing asset catalog.

Configuring Icons Without an Asset Catalog

1. Follow the steps in the Xcode Help to add each icon image to your project as a resource.

2. Locate the target's information property list in the project navigator. By default it will be named Info.plist. Command click on it and choose Open As > Source Code from the context menu.

As of iOS 5.0, icons are specified by including the CFBundleIcons key. Older applications may have previously specified their icons by including the CFBundleIconFiles key. This key should be removed if it is still present (don't forget to remove any device specific variants too). All applications should migrate to the CFBundleIcons key to specify their icons.

The value for the CFBundleIcons key is a dictionary with two child keys: CFBundlePrimaryIcon and UINewsstandIcon. The UINewsstandIcon key is for newsstand apps and can otherwise be omitted. The value for the CFBundlePrimaryIcon key is a dictionary that identifies the icon images associated with the bundle. It may contain two child keys: CFBundleIconFiles and UIPrerenderedIcon. The value for the UIPrerenderedIcon key is a boolean that specifies whether the images already incorporate a shine effect. The value for CFBundleIconFiles key is an array of strings, each identifying an image in the bundle.

Listing 1  Example configuration for a universal app.

<key>CFBundleIcons</key>

<dict>

    <key>CFBundlePrimaryIcon</key>

    <dict>

        <key>CFBundleIconFiles</key>

        <array>

            <string>Icon-Small</string>

            <string>Icon-Small-40</string>

            <string>Icon-Small-50</string>

            <string>Icon</string>

            <string>Icon-60</string>

            <string>Icon-72</string>

        </array>

    </dict>

</dict>

<key>CFBundleIcons~ipad</key>

<dict>

    <key>CFBundlePrimaryIcon</key>

    <dict>

        <key>CFBundleIconFiles</key>

        <array>

            <string>Icon-Small</string>

            <string>Icon-Small-40</string>

            <string>Icon-Small-50</string>

            <string>Icon-72</string>

            <string>Icon-76</string>

            <string>Icon-83.5</string>

        </array>

    </dict>

</dict>

If your application supports iOS 4.3 you must also include the CFBundleIconFiles key to specify the application's icon images. The value for this key is an array of strings, each identifying an image in the bundle. If you have included images for the iPad-specific icons, you may either list them under the CFBundleIconFiles key, or you may list them under the device specific CFBundleIconFiles~ipad key. iPad-only applications should list their icon images under the CFBundleIconFiles key.

Listing 2  Example configuration for a universal app with deployment target of iOS 4.3.

<key>CFBundleIconFiles</key>

<array>

    <string>Icon-Small</string>

    <string>Icon-Small-40</string>

    <string>Icon-Small-50</string>

    <string>Icon</string>

    <string>Icon-60</string>

    <string>Icon-72</string>

</array>

<key>CFBundleIconFiles~ipad</key>

<array>

    <string>Icon-Small</string>

    <string>Icon-Small-40</string>

    <string>Icon-Small-50</string>

    <string>Icon-72</string>

    <string>Icon-76</string>

    <string>Icon-167</string>

</array>

Adding Icon Images to an Asset Catalog

1. Select the asset catalog in the project navigator. It is named Images.xcassets by default.

2. From the left column of the editor, select the icon set. For new it will be named 'AppIcon'. You may need to create an icon set by clicking the (+) button in the bottom left corner of the editor and choosing 'New App Icon' from the context menu.

By default, the set will only contain image wells for watch icons. If image wells for iOS app icons are present, expand the attributes inspector and select the appropriate options from the pull-down menus under the App Icon section.

1. Drag images from the Finder onto each image well to configure the associated icon.

Asset catalogs create a copy of images added to them. If you had previously added the images as resources to your project you can safely remove them.

1. Configure the Watch application to use the new icon set.

2. 1. Select the project in the project navigator.

   2. Select the Watch App target from the list in the left column of the project editor.

   3. Switch to the General pane at the top of the project editor.

   4. Select the icon set from the App Icons Source popup menu under the App Icons section.

Adding Icon Images to an Asset Catalog

1. Select the asset catalog in the project navigator. It is named Assets.xcassets by default.

2. From the set outline view (left column), select the app icon set. It is named 'iMessage App Icon' by default. You may need to create an icon set by clicking the (+) button in the bottom left corner of the editor and choosing App Icons and Launch Images > New Messages Extension Icon from the context menu.

1. Drag images from the Finder onto each image well to configure the associated icon.

1. Configure the extension to use the new icon set.

2. 1. Select the project in the project navigator.

   2. Select the iMessage extension or Sticker Pack extension target from the list in the left column of the project editor.

   3. Switch to the General pane at the top of the project editor.

   4. Select the icon set from the Sticker Icons Source popup menu under the App Icons section.

[Asset Catalogs] Remove icon related keys from the information property list

If a target is using asset catalogs to manage its icons then its information property list should not include any icon related keys; they will be added at build time by the asset catalog compiler.

1. Open the information property list for the target. It can be found under the Info tab in the project editor or in the project navigator where it will likely be named either Info.plist or <ProductName>-Info.plist.

2. Remove the following keys, including device specific variations.

   • “Icon file” (CFBundleIconFile)

   • “Icon files” (CFBundleIconFiles)

   • CFBundleIcons

[Asset Catalogs] Verify that the asset catalog is associated with the target

If a target is using asset catalogs to manage its icons, verify that the asset catalog file is associated with the target and that the correct image set is selected for the target's App Icons Source.

1. Select the asset catalog in the project navigator.

2. In the utility panel, check the box next to the target under the Target Membership section as shown in Figure 12.

1. Select the project in the project navigator.

2. Select the target from the list in the left column of the project editor.

3. Switch to the General pane at the top of the project editor.

4. Verify that the name of the icon set is selected in the App Icons Source popup menu under the App Icons and Launch Images section as shown in Figure 4.

[Manual] Verify that all icon images are associated with the target

If a target is not using asset catalogs to manage its icons, verify that each of the icon images are associated with the target. Images that are not associated with the target are not copied into the target's bundle when it is built.

1. Select the icon image in the project navigator.

2. In the utility panel, check the box next to the target under the Target Membership pane as shown in Figure 13.

[Manual] Verify that the CFBundleIcons key is present in the information property list

If a target is not using asset catalogs to manage its icons, the information property list must contain the CFBundleIcons key to specify the application's icon images. See Configuring Icons Without an Asset Catalog.

[Manual] Verify that all images referenced by the CFBundleIcons key are present

If a target is not using asset catalogs to manage its icons, each of the entries under the CFBundleIcons key in the information property must reference at least one image in the app bundle. Remember that if you include filename extensions in the information property list, you must specify the names of all icon image files (including the high-resolution variants) explicitly.

Verify that all icon images are in PNG format, use a supported color model, and are the correct sizes

All icon images must be in PNG format and use a supported color model. Images that do not use the RGB color model may appear correctly in Xcode but will fail to load on the device. You can use the Preview application to inspect the format, color model, and size of an image.

1. Open the image in Preview

   • For an image inside of an asset catalog: Select the asset catalog in the project navigator, choose the image set containing the icons, select the image and choose File > Open with External Editor.

   • For an image not inside of an asset catalog: Select the image in the project navigator and choose File > Open with External Editor.

2. From the Preview menubar, choose Tools > Show Inspector.

3. The Inspector window opens

   • The value of the Document Type field shows the image format. It should be Portal Network Graphics image.

   • The value of the Image Size field shows the image size. It should match the size shown in the tabes above.

   • The value of the Color Model field shows the image size. It should be RGB.

If the Document Type is not a Portal Network Graphics image, use Preview to export a copy of the image in PNG format.

1. From the Preview menubar, choose File > Export.

2. Select PNG from the Format menu at the bottom of the save dialog.

3. Click the Save button.

4. Import the saved image into your Xcode project, replacing the original image.

Repeat the above for all icon images.

Validation Errors

There are multiple icon-related problems that will result in your application failing validation by Xcode or iTunes Connect. The underlying issue depends upon the error.

Other Errors

Icon has a black border

Your icon artwork includes rounded corners or transparent areas. iOS will automatically apply a mask that rounds the corners to each icon it displays on the Home screen. Do not inset your icon artwork and make sure your icon has 90° corners so it looks good after the mask is applied.

Icon has a black background in the App Store

The Large App Icon you uploaded to iTunes Connect includes transparent areas. The iTunes Connect Developer Guide lists the complete requirements for the Large App Icon, including that it must be opaque.

You can use the Preview app to check your image for transparent areas, which will appear dark grey as shown in Figure 17. Use your preferred graphics editing software to fill in the transparent areas with the desired background color.

Start Over

If the none of the above solutions resolve the problem, follow the steps below to remove all the icons and icon related configuration from the application. Then follow the steps in Adding Icons to an iOS Application to re-configure the proper icons for the application.