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.

Photo by Daniel Romero on Unsplash

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

Initial launcher in AndroidManifest.xml

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.

Launcher changed in AndroidManifest.xml

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.

Activity alias in Android manifest

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.

1. android:name and android:targetActivity cannot be the same.
2. android:targetActivity can target only declared activity
3. android: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.

INSTALL_PARSE_FAILED_MANIFEST_MALFORMED

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.

Android studio commands to launch an app

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.