Partner Customizations on Google Devices

Beginning in Lollipop, Google has included a new hook in its own applications for customizing the core device experience. Rather than using the overlay mechanism to configure and customize the behavior of core application resources, we are now seeing Google apps hunt for an external "partner customizations" application at runtime.

It looks as though it was originally intended as the mechanism to allow OEMs to provide basic customizations to Android's more locked-down form factors (i.e. Wear & TV). Customizing applications that are not otherwise open source in AOSP seems to be a strong indicator as to why things are being done this way.

Applications that support customization will inspect the system for another package meeting the following criteria:

• FLAG_SYSTEM is set - This means it is stored in /system/app or /system/priv-app
• A BroadcastReceiver is registered for an application-specific action string

As an example of this, the AOSP Launcher3 application includes a Partner interface that we can inspect. Below we can see how it combs the device for the first APK it finds to meet the necessary criteria. In this case, the required action is com.android.launcher3.action.PARTNER_CUSTOMIZATION:

/** Marker action used to discover partner */
private static final String ACTION_PARTNER_CUSTOMIZATION =
        "com.android.launcher3.action.PARTNER_CUSTOMIZATION";
public static final String RES_FOLDER = "partner_folder";
public static final String RES_WALLPAPERS = "partner_wallpapers";
public static final String RES_DEFAULT_LAYOUT = "partner_default_layout";
public static final String RES_DEFAULT_WALLPAPER_HIDDEN =
        "default_wallpapper_hidden";
public static final String RES_SYSTEM_WALLPAPER_DIR = "system_wallpaper_directory";
public static final String RES_REQUIRE_FIRST_RUN_FLOW = "requires_first_run_flow";

/** These resources are used to override the device profile  */
public static final String RES_GRID_AA_SHORT_EDGE_COUNT =
        "grid_aa_short_edge_count";
public static final String RES_GRID_AA_LONG_EDGE_COUNT = "grid_aa_long_edge_count";
public static final String RES_GRID_NUM_ROWS = "grid_num_rows";
public static final String RES_GRID_NUM_COLUMNS = "grid_num_columns";
public static final String RES_GRID_ICON_SIZE_DP = "grid_icon_size_dp";

private static boolean sSearched = false;
private static Partner sPartner;

/**
 * Find and return partner details, or {@code null} if none exists.
 */
public static synchronized Partner get(PackageManager pm) {
    if (!sSearched) {
        Pair apkInfo =
                Utilities.findSystemApk(ACTION_PARTNER_CUSTOMIZATION, pm);
        if (apkInfo != null) {
            sPartner = new Partner(apkInfo.first, apkInfo.second);
        }
        sSearched = true;
    }
    return sPartner;
}

The associated receiver does not need to have any code, as the host application is most interested in reading it's resource bundle. AOSP provides a few sample "customizer" applications to indicate how the interface can be used with regards to Android TV:

• SetupCustomizer - Customizations applied during the Android TV setup process
  • Action: com.google.android.tvsetup.action.PARTNER_CUSTOMIZATION
• LeanbackCustomizer - Customizations applied in the Andorid TV Launcher experience
  • Action: com.google.android.leanbacklauncher.action.PARTNER_CUSTOMIZATION

Nexus handset/tablet devices (as well as manufacturers like Motorola) are leveraging these hooks to customize the launcher experience on their Lollipop builds. We can find some additional examples of these apps in AOSP (for Nexus anyway) that hook into Launcher3:

• ShamuLayout (Nexus 6)
• VolantisLayout (Nexus 9)

What Can You Customize?

Since the apps control what types of resource contents they read out of the external package, we can't really glean a complete list. But based on the Launcher3 source, here's a start:

• Wallpapers
• Launcher icons
• Home screen layouts

TV devices have some additional hooks for specific features:

• Showing live TV on launch
• Skipping portions of the setup sequence

Definitely not a replacement for device overlays, but an interesting supplement for allowing partners to further customize the experience on devices running the GMS software bundle.