Edit

Share via

Alternate app icons in .NET for iOS and tvOS

Apple has several UIApplication APIs that allow an app to manage its icon:

A sample alert when an app changes its icon

Adding alternate icons to a .NET project

To allow an app to switch to an alternate icon, a new .appiconset folder with a collection of icon images will need to be included in the project's asset catalog:

  1. Open the project's asset catalog (Assets.xcassets) in Finder:

    Open the asset catalog

  2. Create a copy of the existing AppIcon.appiconset folder:

    Copy appiconset folder

  3. Replace each icon in the copied folder with the new icon of the matching size:

    Create new icons

  4. Add the app icon to the project file using the AppIcon property:

    <PropertyGroup>
    <AppIcon>AppIcon</AppIcon>
</PropertyGroup>

    Note

    Existing projects typically specifies the app icon using the XSAppIconAssets key in the Info.plist file - this can still be used, but it's recommended to switch to the AppIcon property in the project file instead (which is simplier too, because its value is the name of the icon, not the path to the resource).

  5. Add the alternative icon(s) to the project file using the AlternativeAppIcons item group:

    <ItemGroup>
    <AlternativeAppIcon Include="AlternativeAppIcons" />
</ItemGroup>

Managing the app's icon

With the icon images included in the .NET project, the developer can the following ways to control the app's icon.

The SupportsAlternateIcons property of the UIApplication class allows the developer to see if an app supports alternate icons. For example:

// Can the app select a different icon?
primaryIconButton.Enabled = UIApplication.SharedApplication.SupportsAlternateIcons;
alternateIconButton.Enabled = UIApplication.SharedApplication.SupportsAlternateIcons;

The ApplicationIconBadgeNumber property of the UIApplication class allows the developer to get or set the current badge number of the app icon in the Springboard. The default value is zero (0). For example:

// Set the badge number to 1
var badgeCount = 1;
UNUserNotificationCenter.Current.SetBadgeCount (badgeCount, (error) => {
    Console.WriteLine ($"Set badge count to {badgeCount}: {(error is null ? "successfully" : error.ToString ())}");
}

Note

UNUserNotificationCenter.SetBadgeCount requires authorization from the user on iOS, which can be acquired by calling UNUserNotificationCenter.Current.RequestAuthorization before setting the badge count.

The AlternateIconName property of the UIApplication class allows the developer to get the name of the currently selected alternate app icon or it returns null if the app is using the Primary Icon. For example:

// Get the name of the currently selected alternate
// icon set
var name = UIApplication.SharedApplication.AlternateIconName;

if (name != null ) {
    // Do something with the name
}

The SetAlternameIconName property of the UIApplication class allows the developer to change the app icon. Pass the name of the icon to select or null to return to the primary icon. For example:

void UsePrimaryIcon (Foundation.NSObject sender)
{
    UIApplication.SharedApplication.SetAlternateIconName (null, (error) => {
        Console.WriteLine ($"Set Primary Icon: {(error is null ? "successfully" : error.ToString ())}");
    });
}

void UseAlternateIcon (Foundation.NSObject sender)
{
    UIApplication.SharedApplication.SetAlternateIconName ("AlternateAppIcons", (error) => {
        Console.WriteLine ($"Set Alternate Icon: {(error is null ? "successfully" : error.ToString ())}");
    });
}

When the app is run and the user selects an alternate icon, an alert like the following will be displayed:

A sample alert when an app changes its icon

If the user switches back to the primary icon, an alert like the following will be displayed:

A sample alert when an app changes to the primary icon

See also