Updating your app to support App Icon Change (iOS 10.3+)

With iOS 10.3, Apple added a new method, setAlternateIconName, that allows you to programmatically change your app icon. Rather than having to resubmit your app to the App Store for each change, you can now add alternate icons ahead of time, and switch between them using your code. However, per Apple's design docs, this change must be displayed and acknowledged by the user.

In our latest SDK (2.0.0), we've added the ability to change a user's app icon as an In-App Message Action. You can now send an in-app message to your users to change the app icon on their device. As an example, for a sports app, we could send a message to all our users that switches the app icon to their team's logo. With Leanplum's segmentation and targeting features, we can send different versions of the icon to each user, so the correct custom team app icons go to the right fans.

Requirements

This article assumes you have already:

  • Updated Xcode to 8.3+
  • Run pod update to get Leanplum SDK 2.0.0+
  • Created app icons in the correct sizes with the correct @2x/@3x naming convention

Add your icon files

If you've used an AppIcon set in the past to set your app's icon, it might be a good idea to move the files into a new folder, and remove the files from the icon set. Instead of using an AppIcon set, you will need to update your info.plist file with the appropriate filenames for both the primary icon and the alternate icons (see below).

Before doing that, you must have your icon files in a group in your project's directory.

📘

Your icons cannot be saved in an assets folder, image set, or regular folder. They must either be loosely saved in the project directory, or added to a new group.

To create a new group, right click your project folder, and select New Group. Then, right click that group and select Add files. Choose your icon files in the file dialog window.

For our example, we have all of our icons in a group creatively named Icons.

1338

Update your info.plist file

To use alternate icons, you must use the plist file to set your app icons (instead of an assets folder or AppIcon set).

📘

You must declare your app's primary and alternate icons using the CFBundle​Icons key of your app's Info.plist file. For information about how to configure alternate icons for your app, see the description of the CFBundle​Icons key in Information Property List Key Reference.

Using the plist and CFBundleIcons dictionary is supported in iOS 5.0+ (alternate icons are, of course only supported in iOS 10.3+).

Open your info.plist file as Source Code (Right click the info.plist file > Open as > Source Code). Then, add the correct supportsAlternateIcons and CFBundleIcons xml to the bottom of your plist, just before the final </dict> (see example below).

🚧

Be careful to:

  • Use a unique key name for each alternate icon.
    • Remove any extensions, and th @2x/@3x nomenclature, from file names when including them in the CFBundleIconFiles array (e.g. [email protected] icon should be listed simply as youricon).
    • Only include the filename once, if you have multiple resolutions (e.g. [email protected] and [email protected] are handled by the single youricon).

More detail can be found in Apple's Information Property List Key Reference.

An example plist

For our example, we have set up the following files in a group:

  1. [email protected] (primary)
  2. [email protected] (primary)
  3. GoldIcon.png (alternate)
  4. SilverIcon.png (alternate)

Note: We've used the filenames as the keys for the two alternate icons. This is not required. The keyname can be any string, as long as it is unique. It will, however, be used to name the file in Leanplum when it is uploaded. So changing a keyname after the initial sync can break the link, and duplicate files.

<plist version="1.0">
<dict>
...
    <key>supportsAlternateIcons</key>
    <true/>
    <key>CFBundleIcons</key>
    <dict>
        <key>CFBundlePrimaryIcon</key>
        <dict>
            <key>CFBundleIconFiles</key>
            <array>
                <string>icon</string>
            </array>
            <key>UIPrerenderedIcon</key>
            <false/>
        </dict>
        <key>CFBundleAlternateIcons</key>
        <dict>
            <key>GoldIcon</key>
            <dict>
                <key>CFBundleIconFiles</key>
                    <array>
                        <string>GoldIcon</string>
                    </array>
                <key>UIPrerenderedIcon</key>
                <false/>
            </dict>
            <key>SilverIcon</key>
            <dict>
                <key>CFBundleIconFiles</key>
                    <array>
                        <string>SilverIcon</string>
                    </array>
                <key>UIPrerenderedIcon</key>
                <false/>
            </dict>
        </dict>
    </dict>
...
</dict>

Run a test device in dev mode

Finally, you need to run your app in development mode, which will automatically upload the icon files to Leanplum. Leanplum treats these as files, which will be visible in the Files tab in the Leanplum dashboard.

Next steps

After you've uploaded your app icons to Leanplum, you can test sending an In-app message or an In-app Action. See how to Change a user's App Icon (iOS 10.3+).