diff --git a/docs/background-plugin-jsside.md b/docs/background-plugin-jsside.md new file mode 100644 index 000000000..d8b97c0b7 --- /dev/null +++ b/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). diff --git a/docs/create-plugin.md b/docs/create-plugin.md index 3d5ac6cb1..c1c19cce9 100644 --- a/docs/create-plugin.md +++ b/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 conn) override; void didDisconnect() override; + bool runInBackground() override; }; ``` @@ -138,3 +145,7 @@ void MyFlipperPlugin::didConnect(std::shared_ptr 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). diff --git a/website/i18n/en.json b/website/i18n/en.json index 518a2f8c2..714215818 100644 --- a/website/i18n/en.json +++ b/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", diff --git a/website/sidebars.json b/website/sidebars.json index 73668d126..0573030fa 100644 --- a/website/sidebars.json +++ b/website/sidebars.json @@ -12,6 +12,7 @@ "Plugins: Desktop part": [ "js-setup", "communicating", + "background-plugin-jsside", "create-table-plugin", "ui-components", "styling-components"