1
2# SystemUI Plugins
3
4Plugins provide an easy way to rapidly prototype SystemUI features.  Plugins are APKs that will be installable only on Build.IS_DEBUGGABLE (dogfood) builds, that can change the behavior of SystemUI at runtime.  This is done by creating a basic set of interfaces that the plugins can expect to be in SysUI, then the portion of code controlled by the interface can be iterated on faster than currently.
5
6Plugins keep the experimental and turbulent code outside of master and only on the devices which need to use the prototype.  You can distribute early prototype directly to those that need to see it either through drive or email, and only show it to dogfooders when ready.
7
8## Adding Plugin Hooks
9
10Existing plugin hooks can be found [here](/packages/SystemUI/docs/plugin_hooks.md).
11
12### Writing the Interface(s)
13
14The first step of adding a plugin hook to SysUI is to define the interface layer between the plugin and SysUI.  This interface should be relatively stable so that many different plugins will work across multiple different builds.
15
16All interfaces need to be independent and not reference classes from SysUI.  They should be placed in the plugin library, under com.android.systemui.plugin or sub-packages.  The main interface (entry point) for the plugin should extend the interface Plugin so that you can listen for it.
17
18
19The most important part of interfaces is the version included in them.  Every time the interface changes in an incompatible way, the version should be incremented.  Incompatible changes are changes to the signature of any of the interface methods, or the addition of a new method that doesn’t have a default implementation.  All classes that are in the plugin library should be tagged with a version, they should also be tagged with an action if they are the root interface for the Plugin. If a plugin makes use of the other versioned interface, they can use DependsOn to indicate their dependence. They are tagged using annotations like the following.
20
21
22```java
23@ProvidesInterface(action = MyPlugin.ACTION, version = MyPlugin.VERSION)
24@DependsOn(target = OtherInterface.class)
25public interface MyPlugin extends Plugin {
26    String ACTION = "com.android.systemui.action.PLUGIN_MY_PLUGIN";
27    int VERSION = 1;
28    ...
29}
30```
31
32### Plugin Listener
33
34To actually listen for plugins, you implement a plugin listener that has the following interface.
35
36```java
37public interface PluginListener<T extends Plugin> {
38    /**
39     * Called when the plugin has been loaded and is ready to be used.
40     * This may be called multiple times if multiple plugins are allowed.
41     * It may also be called in the future if the plugin package changes
42     * and needs to be reloaded.
43     */
44    void onPluginConnected(T plugin);
45
46    /**
47     * Called when a plugin has been uninstalled/updated and should be removed
48     * from use.
49     */
50    default void onPluginDisconnected(T plugin) {
51        // Optional.
52    }
53}
54```
55
56Then you register the PluginListener with the PluginManager.  The constants for action and version should be defined on class T.  If allowMultiple is false, the plugin listener will only be connected to one plugin at a time.
57
58```java
59void addPluginListener(String action, PluginListener<T> listener,
60            int version, boolean allowMultiple);
61```
62
63### Examples
64[Allow quick settings panel to be replaced with another view](/packages/SystemUI/plugin/src/com/android/systemui/plugins/qs/QS.java)
65
66[Allow plugins to create new nav bar buttons](/packages/SystemUI/plugin/src/com/android/systemui/plugins/statusbar/phone/NavBarButtonProvider.java)
67
68[Allow lockscreen camera/phone/assistant buttons to be replaced](/packages/SystemUI/plugin/src/com/android/systemui/plugins/IntentButtonProvider.java)
69
70## Writing Plugins
71### Make Files and Manifests
72
73When compiling plugins there are a couple vital pieces required.
741. They must be signed with the platform cert
752. They must include SystemUIPluginLib in LOCAL_JAVA_LIBRARIES (NOT LOCAL_STATIC_JAVA_LIBRARIES)
76
77Basically just copy the [example blueprint file](/packages/SystemUI/plugin/ExamplePlugin/Android.bp).
78
79To declare a plugin, you add a service to your manifest.  Add an intent filter to match the action for the plugin, and set the name to point at the class that implements the plugin interface.
80
81```xml
82       <service android:name=".SampleOverlayPlugin"
83            android:label="@string/plugin_label">
84            <intent-filter>
85                <action android:name="com.android.systemui.action.PLUGIN_OVERLAY" />
86            </intent-filter>
87        </service>
88```
89
90Plugins must also hold the plugin permission.
91
92```xml
93   <uses-permission android:name="com.android.systemui.permission.PLUGIN" />
94 ```
95
96
97### Implementing the interface
98
99Implementing the interface is generally pretty straightforward.  The version of the plugin should tagged with an annotation to declare its dependency on each of the plugin classes it depends on.  This ensures that the latest version will be included in the plugin APK when it is compiled.
100
101```java
102@Requires(target = OverlayPlugin.class, version = OverlayPlugin.VERSION)
103public class SampleOverlayPlugin implements OverlayPlugin {
104    ...
105}
106```
107
108After the plugin is created and passes all permission/security checks, then the plugin will receive the onCreate callback.  The pluginContext is pregenerated for the plugin and can be used to inflate or get any resources included in the plugin APK.
109
110```java
111public void onCreate(Context sysuiContext, Context pluginContext);
112```
113
114When the plugin is being removed, the plugin will receive the onDestroy callback.  At this point the plugin should ensure that all its resources and static references are cleaned up.
115
116```java
117public void onDestroy();
118```
119
120### Adding Settings
121
122A plugin can provide plugin-specific settings that will be surfaced as a gear button on the plugin tuner screen where plugins can be enabled or disabled.  To add settings just add an activity to receive the PLUGIN_SETTINGS action.
123
124```xml
125        <activity android:name=".PluginSettings"
126            android:label="@string/plugin_label">
127            <intent-filter>
128                <action android:name="com.android.systemui.action.PLUGIN_SETTINGS" />
129            </intent-filter>
130        </activity>
131 ```
132
133The plugin settings activity does not run in SysUI like the rest of the plugin, so it cannot reference any of the classes from SystemUIPluginLib.
134
135## Examples
136[The definitive ExamplePlugin](/packages/SystemUI/plugin/ExamplePlugin)
137
138[Replace lock screen camera button with a settings trigger](todo)
139
140[A nav button that launches an action](todo)
141
142
143## Writing plugins in Android Studio
144
145As long as the plugin doesn’t depend on any hidden APIs (which plugins should avoid anyway) and only uses Plugin APIs, you can be setup to build in android studio with only a couple steps.
146
147### Signing
148
149Plugins need to be signed with the platform cert, so you’ll need a copy of the keystore that contains the same cert.  You might find one at http://go/plugin-keystore, you can copy it to the root directory of your project.  Then you can tell your module to be signed with it by adding the following to the android section of your module’s build.gradle.
150
151```groovy
152android {
153    ...
154    buildTypes {
155        release {
156            minifyEnabled false
157            proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
158        }
159        debug {
160            signingConfig signingConfigs.debug
161        }
162     }
163     signingConfigs {
164        debug {
165            keyAlias 'platform'
166            keyPassword 'android'
167            storeFile file('../platform.keystore')
168            storePassword 'android'
169        }
170     }
171   ...
172}
173```
174
175
176### Compiling against Plugin APIs
177
178To be able to implement a plugin, you’ll need a jar file that contains the plugin classes for compilation.  Generally you can grab a recent plugin lib from jmonk’s experimental directory.  However if you recently changed one of the plugin interfaces, you might want to build an updated version, you can use the following script to do so.
179
180```
181$ frameworks/base/packages/SystemUI/plugin/update_plugin_lib.sh
182```
183
184Once you have the jar you are going to compile against, you need to include it in your android studio project as a file dependency.  Once it is included change its scope from Compile to Provided in the project structure (you may need to build once before changing to provided).  This is required to ensure you don’t actually include the plugin library in your plugin APK.
185
186## Implementation Details
187
188Plugins are APKs that contain code and resources that can be dynamically loaded into SystemUI.  The plugins are compiled against a set of relatively stable (and version tagged) interfaces, that the implementations are provided by SysUI.  This figure shows an overview of how the plugin compiling/loading flow works.
189
190![How plugins work](sysui-plugins.png)
191
192### Security
193
194Whenever loading a code from another APK into a privileged process like SysUI, there are serious security concerns to be addressed.  To handle this, plugins have a couple lines of defense to ensure these don’t create any security holes.
195
196The first line of defense is Build.IS_DEBUGGABLE checks.  In 2 different places, SysUI checks to ensure that the build is debuggable before even scanning or loading any plugins on the device.  There are even tests in place to help ensure these checks are not lost.
197
198The second line of defense is a signature permission.  This ensures that plugins are always provided by the source of the android build.  All plugins must hold this permission for any of their code to be loaded, otherwise the infraction will be logged, and the plugin ignored.
199
200```xml
201   <permission android:name="com.android.systemui.permission.PLUGIN"
202            android:protectionLevel="signature" />
203 ```
204
205### Plugin Management
206
207Plugins are scanned for by intent filters of services.  A plugin is not actually a service, but the benefits of declaring it as a service makes it worth it.  Each plugin listener in SysUI simply specifies an action to look for, and the PluginManager scans for services declaring that action and uses that to know the class to instantiate.
208
209
210The other major advantage to declaring plugins through components in a manifest is management of enabled state.  Whether a plugin is enabled or disabled is managed by the package manager component enabled state.  When a device has had a plugin installed on it, an extra section is added to the SystemUI Tuner, it lists all of the plugins on the device and allows the components to be easily enabled and disabled.
211
212### Versioning
213
214When a plugin listener is registered in SysUI, the interface version is specified.  Whenever a plugin is detected, the first thing that is done after instantiation is the version is checked.  If the version of the interface the plugin was compiled with does not match the version SysUI contains, then the plugin will be ignored.
215
216### Class loading
217
218When plugins are loaded, they are done so by creating a PathClassLoader that points at the plugin APK.  The parent of the classloader is a special classloader based on SysUI’s that only includes the classes within the package com.android.systemui.plugin and its sub-packages.
219
220Having SysUI provide the implementations of the interfaces allows them to be more stable.  Some version changes can be avoided by adding defaults to the interfaces, and not requiring older plugins to implement new functionality.  The plugin library can also have static utility methods that plugins compile against, but the implementations are in sync with the platform builds.
221
222The class filtering in the parent classloader allows plugins to include any classes they want without worrying about collisions with SysUI.  Plugins can include SettingsLib, or copy classes directly out of SysUI to facilitate faster prototyping.
223
224### Crashing
225
226Whether it be from accidental reference of hidden APIs, unstable prototypes, or other unexpected reasons, plugins will inevitably cause SysUI to crash.  When this happens it needs to ensure a bad acting plugin do not stop the phone from being usable.
227
228When a plugin crashes, the PluginManager catches it and tries to determine the plugin that caused the crash.  If any of the classes in the stack trace are from the package of the plugin APK, then the plugin is disabled.  If no plugins can be identified as the source of the crash, then all plugins are disabled, just to be sure they aren’t causing future crashes.
229