Documentation for background plugin

Summary: Documentation for background plugin

Reviewed By: passy

Differential Revision: D10378898

fbshipit-source-id: 42f23b9464c41ee2f329301233c1e01d0ae05e95

docs/background-plugin-jsside.md

@@ -0,0 +1,23 @@
+---
+id: background-plugin-jsside
+title: Background Plugin Setup
+sidebar_label: Background Plugin
+---
+
+A Flipper Plugin can run in the background too. With this capability, the plugin running in the background can send messages even when the plugin is not active (i.e. the user is using some other plugin in Flipper). To prepare a Flipper plugin for running in the background, its JavaScript side should implement `persistedStateReducer`.
+
+`persistedStateReducer` will be called whenever the JavaScript side receives data from the client. It gets two arguments: one is the current Redux store of the plugin and the second is the data received from client. The function returns the state with which the plugin should get updated. For more info follow the [network plugin](https://github.com/facebook/flipper/blob/14e38c087f099a5afed4d7a1e4b5713468eabb28/src/plugins/network/index.js#L122)
+
+
+```js
+export default class extends FlipperPlugin {
+  static persistedStateReducer = (
+    persistedState: PersistedState,
+    data: Data,
+  ): PersistedState => {
+    // Logic to merge current state with new data
+  };
+}
+```
+
+You will also have to make the plugin opt in to run in the background from native side too. For more info around this, read the mobile [setup](create-plugin.md).

docs/create-plugin.md

@@ -28,6 +28,11 @@ public class MyFlipperPlugin implements FlipperPlugin {
   public void onDisconnect() throws Exception {
     mConnection = null;
   }
+
+  @Override
+  public boolean runInBackground() {
+  	return false;
+  }
 }
 ```
 
@@ -42,6 +47,7 @@ public class MyFlipperPlugin implements FlipperPlugin {
 - (NSString*)identifier { return @"MyFlipperPlugin"; }
 - (void)didConnect:(FlipperConnection*)connection {}
 - (void)didDisonnect {}
+- (BOOL)runInBackground {}
 
 @end
 ```
@@ -54,6 +60,7 @@ public:
   std::string identifier() const override { return "MyFlipperPlugin"; }
   void didConnect(std::shared_ptr<FlipperConnection> conn) override;
   void didDisconnect() override;
+  bool runInBackground() override;
 };
 ```
 
@@ -138,3 +145,7 @@ void MyFlipperPlugin::didConnect(std::shared_ptr<FlipperConnection> conn) {
   conn->send("getData", message);
 }
 ```
+
+## Background Plugins
+
+If the plugin returns false in `runInBackground()`, then the Flipper app will only accept messages from the client side when the plugin is active (i.e. when user is using the plugin in the Flipper app). Whereas with the plugin marked as `runInBackground`, it can send messages even when the plugin is not in active use. The benefit is that the data can be processed in the background and notifications can be fired. It also reduces the number of rerenders and time taken to display the data when the plugin becomes active. As the data comes in the background, it is processed and a state is updated in the Redux store. When the plugin becomes active, the initial render will contain all the data. Currently, the network plugin is run in background. To setup the plugin in background, follow the above steps and for the JavaScript side follow the steps given [here](background-plugin-jsside.md).

website/i18n/en.json

@@ -4,6 +4,8 @@
     "next": "Next",
     "previous": "Previous",
     "tagline": "Extensible mobile app debugging",
+    "background-plugin-jsside": "Background Plugin Setup",
+    "Background Plugin": "Background Plugin",
     "communicating": "Device Communication",
     "Device Communication": "Device Communication",
     "create-plugin": "Mobile Setup",

website/sidebars.json

@@ -12,6 +12,7 @@
     "Plugins: Desktop part": [
       "js-setup",
       "communicating",
+      "background-plugin-jsside",
       "create-table-plugin",
       "ui-components",
       "styling-components"