How to implement Runtime resource Overlay in AOSP source.

The implementation details for the Runtime resource overlay in the AOSP source will be discussed in this blog.

Photo by Daniel Cheung on Unsplash

What is Runtime Resource Overlay?

The RRO technique is a defined standard way to customize the UI component of an application and framework without doing modifications to the original resources associated with it. We can say the original resources of an application can be overlapped with the provided resources by RRO.

I have collected more information about runtime resource overlay, please have a look at the below article.

AOSP UI Customization: Runtime Resource Overlay

Overlay target

We will make this practice way easier by implementing an overlay on a single resource, I have selected randomly a “Contacts” application to implement the RRO over its resources, you can do it with any application or System UI.

Our motive is to implement the runtime resource overlay and understand how it works so I will perform overlay on a simple string present in a Contact application. That is “Your Contact list is empty” will be replaced by “No Contact Available” after performing RRO.

Let’s start understanding the Runtime Resource Overlay with a practical approach and try RRO with small changes in the AOSP source on the Contact Application.

Steps to implement RROS

Prerequisites: Prerequisites are only for those who perform RRO directly on an AOSP source. AOSP source is downloaded and built first for anyone to build a suitable build option. You can also implement your sample application for practice. Also, I mentioned “Android.bp” file structure below for building RROs directly with AOSP sources.

There is a string resource in my AOSP 12 Source code in the Contacts application.

"<string name="noContacts">Your contacts list is empty</string>"

The image below shows the value before the overlay is implemented.

We will overlay “No Contacts available” on the original string value “Your contacts list is empty”

#Step 1: Look at overlayable.xml.

Now you have to look for an overlayable.xml file in the path “res/value/” within the selected application source and the resource should be available within that overlayable.xml file.

Example: overlayable.xml

<resources>
  <overlayable name="Contacts">
    <policy type="public">
      <item type="string" name="noContacts"/>
    </policy>
  </overlayable>
</resources>

The packages are already exposed to be overlaid by default in that case you will be able to locate the overlayble.xml within in res dir or nested dirs of res.

There might be a possibility!!

1. overlayable.xml is not available.
2. overlayable.xml is available but the resource is not added to exposed for implementing overlay.

Note → In these cases, the overlay should be preinstalled on the system image or the overlay should be signed with the same signature as the target package. In the Contacts Application case, the overlayable.xml file is not available and I will be building the overlay with an AOSP source with the same signature as the target application.

#Step 2: Create the overlay structure and required files.

Now we will create an overlay package structure.

As simply mentioned above prepare the structure and all the files with the same names and we can place the overlay structure package in any suitable location in the AOSP source.

#Step 3: Prepare AndroidManifest.xml.

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
          package="com.android.contacts.rro">
    <overlay
        android:priority="1"
        android:targetName="Contacts"
        android:targetPackage="com.android.contacts"
        android:isStatic="true"
        android:resourcesMap="@xml/overlays"
    />
</manifest>

target Name: name of the package the RRO intends to overlay.

target package: The target package the RRO intends to overlay

is Static: It defines if the RRO should be mutable or immutable if isStatic is set to true then dynamically we can not enable or disable the RROs. and It will be enabled by default at boot time.

resource map: This tag holds overlay.xml which specifies the resource mapping of the RRO package and Target Application or Framework Resource package. These resource IDs will be mapped and the IdMap file will be generated for RROs based on resource mapping.

priority: IT is used internally when there are multiple RROs overlay the single target package and the static RROs priority will be always set to MAX value.

package: Package is the namespace like “com.android.contacts.rro” Generally by the standard way we can extend the RRO package suffixing .rro with the package name of the target package.

#Steps 4: Prepare Android.bp

android_app {
    name: "testcustomerro",
    resource_dirs: ["res"],
    certificate: "shared",
    product_specific: true,
    privileged: true,
    sdk_version: "system_current",
    min_sdk_version: "21",
    manifest: "AndroidManifest.xml",
    aaptflags: [
        "--no-resource-deduping",
        "--no-resource-removal",
     ]
}

#Step 5: Prepare overlays.xml

<overlay>
    <item target="string/noContacts" value="@string/noContacts"/>
</overlay>

#Step 6: Prepare res file

<resources xmlns:xliff="urn:oasis:names:tc:xliff:document:1.2">
    <string name="noContacts">No Contacts available</string>
</resources>

Once All the files are configured in the mentioned manner we can build RRO packages with AOSP source the RRO package must be installed when you run the Contact application.

Probably with a single resource, it is less possible to leave any mistake but with a large resource or cross-reference conflict we may face some issues with RRO. In case you face any issues with RRO that it is successfully built it is not reflected as expected then we have a few debugging techniques which we can use to debug our RRO.

Please have a look at the below article for Runtime resource overly debugging technique.

Thanks for Reading! If this article was helpful. Please hit the clap!

Follow on medium https://medium.com/@narendra147h

Connect on Linked In: linkedin.com/in/narendraharny

Please Follow & subscribe to Make Android Publication by Narendra K H for prompt updates on Android platform-related blogs.

Make Android

Thank you!