Activity Alias in Android Manifest
Android’s <activity-alias>
tag is one of the most unused tags in the android manifest. The existence and benefits of it are unknown to many Android developers, even today.
Activity alias represents a symlink to an Activity. The most popular use of activity alias is to prevent the removal of the app launcher shortcut when the underlying launcher activity is changed.
💡 Activity alias has been residing inside the androiManifest.xml since API 1.
The Curious Case of the missing shortcut
When a launcher icon shortcut is created, it is statically linked to the exact activity of the Launcher. In the below case, the shortcut is directly linked to the SplashActivity
In the future, due to the need to improve code organization or implementing new features, you could change the componentName of the launcher activity to point to some other activity.
The launcher is changed from SplashActivity
to LoginActivity
.
What would be the behavior of the shortcut?
Common case: The icon is removed from the user’s home screen, but still visible in the app drawer.
Other cases: The icon remains, but the device says the app is not installed
Since the file name and location are changed, the shortcut link is lost, thus removed by the android OS. This is the hidden side effects of having a part of the app exposed as a public API. To know more, you need to understand the manifest better.
AndroidManifest.xml
We often think that only the packageName
in the manifest is immutable, but surprisingly, the major function of the AndroidManifest contribute to declaring a public API from your application to be used by the Android system and other applications.
Every public component (android:exported=true)
declared in the manifest should be treated as a public API. These components should never be changed in any way that could break compatibility.
The common attribute android:name
usually breaks compatibility. This attribute is unique, thus an identifier of the specific application component (Activity
, Service
, BroadcastReceiver
, or ContentProvider
).
Changing the android:name
can have negative consequences for the users.
- If an activity name is changed, any shortcut the user-created, based on that activity, will no longer work. Shortcuts are explicit intent which is directly referring to the ComponentName it should run.
- If the live wallpaper service name is changed, the user’s wallpaper will be reverted to the system default. This also applied to Input Methods, Accessibility Services, and app widgets.
- If the device admin receiver name is changed, the device admin will be disabled.
How to fix the broken shortcut — Permanently
The explicit Intent that was previously saved during shortcut creation is now invalid because the ComponentName it references no longer exists. To solve this an activity alias is created in the manifest and points to the target class by targetActivity
attribute.
This preserves the componentName and targets any desired activity without having side-effects.
The targetActivity
can be changed to any new class when needed, without breaking the existing explicit intent created by the shortcut.
This avoids the user to bump into a surprise missing shortcut after an app update.
Activity Alias
Activity alias is a subset of activity attributes in the androidManifest.xml, with the exception of targetActivity
attribute. This means it can have a set of intent filters of its own.
None of the values from the subset attributes for the target will carry over to the alias. But, the attributes that are not present in the subset, the values set for the target will also apply to the alias.
Due to the importance of componentName declared in the manifest, it is necessary to not change name if they are visible to other applications.
android:name
andandroid:targetActivity
cannot be the same.android:targetActivity
can target only declared activityandroid:enabled=false
will prevent the target activity to be instantiated by the system through the alias
What happens if
— I create an activity alias with an activity that is not declared, or use same name for android:name
and android:targetActivity
Output: INSTALL_PARSE_FAILED_MANIFEST_MALFORMED error.

Quick check on Activity alias
The below images shows the android studio’s commands to launch an application.
It could be seen that the class name changes when we launch the app, as the name is public and essential to launch the app. When using an alias the name remains the same, thus avoiding side-effects.

Personal note
It is a good practice to use an activity alias to handle the Launcher activity. It is up to us to use as many aliases as our app demands, but every app should have one activity alias(for starters) which saves our shortcuts.
To know more about attributes on activity alias, do visit the android guide Activity alias element.