How Shadow Plugin Framework Shrinks Android APKs and Enables Dynamic Modules

Background

Because the QQ Reading APK grew too large, causing pressure on operations and promotion, the team first removed unused resources, converted image formats, and compressed assets, but eventually hit a size bottleneck. After research they chose a plugin architecture to deliver parts of the app as separate plugins, effectively reducing the host APK size.

What is Pluginization

Modular vs. Plugin

In a typical modular architecture, an application consists of multiple business modules, each with its own module . All modules are packaged into a single APK, communicating via routes or interfaces.

Pluginization is similar in that each module is independent, but plugin modules are not packaged into the host APK. Instead, each plugin is built as an independent APK and delivered to the host at runtime, allowing dynamic loading.

Benefits of Pluginization

Decouples host and plugins, providing compilation isolation.

Reduces the host APK size.

Plugins can be updated or fixed dynamically without a full app release.

Technical Foundations

Class Loader Mechanism

All plugin frameworks rely on ClassLoader to load classes from the plugin. Android uses a parent‑delegation model where BootClassLoader loads core classes, PathClassLoader loads the host APK, and DexClassLoader can load plugin APKs from external storage, typically with PathClassLoader as its parent.

In Android, the host’s classes are loaded by PathClassLoader , whose parent is BootClassLoader . Plugin frameworks insert a custom RuntimeClassLoader between them to load plugin classes.

Four‑component placeholder logic is needed because Android components (Activity, Service, BroadcastReceiver, ContentProvider) must be declared in the manifest. Plugin frameworks reserve placeholder components in the host manifest and replace them at runtime to bypass manifest checks.

Why Choose Shadow

During research the team evaluated three major plugin frameworks—VirtualAPK, RePlugin, and Shadow—based on compatibility, stability, and community activity.

VirtualAPK

Open‑sourced by Didi, stable in Didi’s environment, but has not been maintained for over two years and only supports up to Android 9.0.

Drawbacks: no recent commits, limited Android version support.

RePlugin

Developed by 360, long‑standing and active community.

Advantages: mature ecosystem.

Drawbacks: does not support AndroidX, heavy placeholder usage, only compatible up to Android 9.0.

Shadow

Tencent’s plugin framework, proven in QQ Reading, claims zero‑reflection hack and full dynamic plugin capabilities. Community is active and support is fast.

Advantages: minimal host code increase, dynamic delivery, stable on high‑version Android.

Drawbacks: flexible design raises learning curve, requires a PluginManager and a plugin zip for each plugin, no Maven repository (must use source or private Maven), SDK not fully comprehensive.

Shadow Overview

Shadow’s incremental host code compared to other frameworks is illustrated below.

Shadow claims zero‑reflection hack and full dynamic plugin support, delivering almost all functionality dynamically while keeping host code minimal.

Shadow Architecture Analysis

4.1 Plugin Components

PluginManager : Manages plugins, packaged as an independent APK. Host interacts with plugins via interfaces and reflection through PluginManager.

Plugin‑loader : Loaded as a separate APK inside the plugin zip; handles installation and invocation of plugins.

Plugin‑runtime : Also packaged in the plugin zip; contains proxy Activity, ContentProvider, etc.

Plugin‑app : The actual business code of the plugin, packaged as an APK inside the zip.

4.2 SDK Structure

4.3 Source Code Breakdown

4.3.1 Shadow Runtime Flowchart

The flow shows how the host calls PluginManager, which communicates with the plugin service via IBinder to load plugin‑runtime and plugin‑loader . The RuntimeClassLoader is inserted between BootClassLoader and PathClassLoader , allowing the host to load plugin classes that it cannot find itself.

4.3.2 PluginManager

When the host invokes DynamicPluginManager.enter() , it loads the real manager implementation via ManagerImplLoader , which uses ApkClassLoader to reflectively load ManagerFactoryImpl . The final manager instance is SamplePluginManager .

4.3.3 Plugin‑runtime

The host’s PluginProcessService loads plugin‑runtime via IBinder . The runtime contains proxy components that the host delegates to.

4.3.4 Plugin‑loader

PluginLoaderImpl implements IBinder . The host obtains it via PluginManager and uses it to perform plugin operations. The loader is created by LoaderFactoryImpl , which builds a SamplePluginLoader extending ShadowPluginLoader .

4.3.5 Plugin‑app

The plugin’s business code is loaded by ShadowPluginLoader , which creates the necessary ClassLoader , PackageInfo , Resources , and Application objects.

4.3.6 Execution Flow

When a plugin Activity is launched, Shadow creates a proxy Activity that extends PluginContainerActivity . Calls are delegated to ShadowActivityDelegate , which forwards them to the real plugin Activity, and then back to the host via HostActivityDelegator .

Shadow Usage

Project Structure

White‑list Mechanism

White‑lists bridge host and plugin classes. The host’s PluginManager declares bridge package names in its white‑list so that classes are loaded from the host’s PathClassLoader . Similarly, plugin‑loader and plugin‑app have their own white‑lists defined in Gradle files.

Conclusion

Shadow has been integrated into QQ Reading, converting the PDF and card modules into Shadow plugins. The migration required extensive refactoring of inheritance, UI frameworks, and host‑plugin communication. The key lesson is to first make a module independently runnable before turning it into a plugin. Plugins should depend on the host, while the host should avoid direct dependencies on plugin UI layers, aligning with Shadow’s design philosophy.

Pluginization is an ongoing process that involves continuous module extraction and adaptation. While challenging, it offers deep insights into design patterns, cross‑process communication, and compile‑time instrumentation.