Introduction to the Shadow Android Plugin Framework

Shadow Framework Overview

Shadow is an Android plugin framework developed by Tencent, open‑source and validated by billions of users. It reuses the source code of independently installed apps and provides a fully dynamic plugin solution with a minimal host footprint (about 15 KB, ~160 methods).

Official Introduction

Key features include source‑code reuse, zero‑reflection implementation (no hidden APIs), a fully dynamic architecture, and a very small host size.

Other Notes

High integration threshold due to incomplete documentation and complex demos.

No official Maven dependency; developers must publish and maintain it themselves.

Many GitHub issues are questions or misuse rather than real bugs.

Overall Call Flow

Main Modules

Host

shadow-host: loads shadow‑manager via reflection.

shadow-manager: manages plugin files and communicates with the plugin process (indirect host calls).

Plugin

shadow-runtime: provides runtime support and hooks the host classloader so that placeholder activities are implemented in shadow‑runtime.

shadow-loader: loads shadow‑app APK, creates a classloader, parses package info, instantiates the plugin Application, builds Resources, registers component information, and handles component startup.

shadow-app: contains business logic; multiple plugin apps can be supported.

Module Call Process

Plugin installation involves unzipping the plugin zip to an internal path (named by its MD5), copying the appropriate .so files according to the host CPU architecture, and saving plugin metadata (apk path, so path) into SQLite. Plugin loading uses a bindService call to a remote PluginProcessService, loads shadow‑runtime and shadow‑loader, and finally delegates the actual loading to shadow‑loader.

shadow-runtime

This module hooks the host ClassLoader, allowing the host to start placeholder Activities that are actually implemented in shadow‑runtime, thereby avoiding ClassNotFoundException. The solution is a single ClassLoader hook point.

shadow-loader

Responsible for creating a classloader for the plugin APK, parsing its PackageInfo, instantiating the plugin Application, creating Resources for the plugin, parsing the four main component types and storing them in ComponentManager, and managing component startup.

Transform Dynamic Replacement

During compilation Shadow replaces core Android classes (e.g., Activity → ShadowActivity, Application → ShadowApplication) with plugin‑aware versions, embedding the necessary logic for plugin operation.

Support for the Four Android Components

Activity (Proxy Model)

Host can start a plugin Activity via the placeholder Activity defined in shadow‑runtime (PluginContainerActivity).

Inside the plugin, Activity launches are wrapped by ShadowContext and delegated to ComponentManager, which ultimately calls the host context's startActivity.

Mapping between plugin Activity and host ContainerActivity is illustrated in the diagram.

Service (Simulated Calls)

Service lifecycle is simulated rather than using a proxy; startService and bindService approaches are shown.

ContentProvider (Unified Dispatch)

A unified entry PluginContainerContentProvider is defined in the host and registered in AndroidManifest.xml. External access uses URIs of the form content://$containerAuthority/$uriContent . The framework parses the URI, forwards the request to the actual provider, and manages provider lifecycle.

Uri.parse("content://$containerAuthority/$uriContent")

BroadcastReceiver (Wrapper)

Only dynamic broadcasts are supported; the context passed to onReceive is a ShadowContext wrapper.

Plugin‑Host Isolation

Shadow overrides ClassLoader.loadClass to break the parent‑delegation principle, preventing version conflicts between host and plugin libraries. Whitelisted paths are configured in the plugin’s build.gradle .

Integration with Flutter

Shadow already supports FlutterActivity, Flutter .so libraries, and asset handling, allowing a Flutter module to be added as a plugin. Two issues are addressed:

Flutter resource loading fails because Application.createPackageContext returns the host context; overriding this method to return this fixes the problem.

In debug mode, Flutter resources are not updated after plugin packaging because the timestamp check does not change; manually updating packageInfo.lastUpdateTime resolves it.

Conclusion

Shadow combines ClassLoader manipulation, code generation, and Transform dynamic replacement to create a stable, dynamic plugin framework. These characteristics make Shadow uniquely powerful for Android plugin development under increasingly strict system API restrictions.