Platform notes
iOS
- Alternate icons require iOS 10.3+.
- iOS shows a system alert when the icon changes — this is expected Apple behavior.
- The icon name must match a key in
CFBundleAlternateIcons, or use"Default"for the primary icon.
Test on a real device
Some recent iOS Simulator versions fail to show the system alert after an icon change. When that happens, the icon switch may appear to do nothing even though your setup is correct.
Always verify icon switching on a physical iPhone or iPad before concluding there is a bug in your app or this library.
Android
- Icon names are derived from
activity-aliasnames: everything afterMainActivityin the alias class name. - The icon switch is deferred until the app is backgrounded for a smoother UX.
- The library waits if sign-in, OAuth, or other overlay activities are in the foreground.
Naming cheat sheet
| Platform | How names are defined | Example setIcon() argument |
|---|---|---|
| iOS | Key in CFBundleAlternateIcons / .appiconset folder | AlternativeIcon |
| Android | Suffix after MainActivity in alias | AlternativeIcon |
| Both | Primary icon | Default |