Client Plugin API

FlipperPlugin

The plugin implementation that runs on the (mobile) application side of things is called the client plugin in Flipper terminology. To build a client plugin, implement the FlipperPlugin interface.

The ID that is returned from your implementation needs to match the name defined in your JavaScript counterpart's package.json.

public class MyFlipperPlugin implements FlipperPlugin {
private FlipperConnection mConnection;
@Override
public String getId() {
return "MyFlipperPlugin";
}
@Override
public void onConnect(FlipperConnection connection) throws Exception {
mConnection = connection;
}
@Override
public void onDisconnect() throws Exception {
mConnection = null;
}
@Override
public boolean runInBackground() {
return false;
}
}

Using FlipperConnection

onConnect will be called when your plugin becomes active. This will provide a FlipperConnection allowing you to register receivers for desktop method calls and respond with data.

connection.receive("getData", new FlipperReceiver() {
@Override
public void onReceive(FlipperObject params, FlipperResponder responder) throws Exception {
responder.success(
new FlipperObject.Builder()
.put("data", MyData.get())
.build());
}
});

Push data to the desktop

You don't have to wait for the desktop to request data though, you can also push data directly to the desktop. If the JS plugin subscribes to the same method, it will receive the data.

connection.send("MyMessage",
new FlipperObject.Builder()
.put("message", "Hello")
.build()

Using a plugin instance to send data

It is often useful to get an instance of a Flipper plugin to send data to it. Flipper makes this simple with built-in support.

using FlipperClient to obtain a plugin instance

Plugins should be treated as singleton instances as there can only be one FlipperClient and each FlipperClient can only have one instance of a certain plugin. The Flipper API makes this simple by offering a way to get the current client and query it for plugins.

Plugins are identified by the string that their identifier method returns, in this example, "MyFlipperPlugin". Note that null checks may be required as plugins may not be initialized, for example in production builds.

final FlipperClient client = AndroidFlipperClient.getInstanceIfInitialized(context);
if (client != null) {
final MyFlipperPlugin plugin = client.getPluginByClass(MyFlipperPlugin.class);
plugin.sendData(myData);
}

Here, sendData is an example of a method that might be implemented by the Flipper plugin.

Background Plugins

In some cases you may want to provide data to Flipper even when your plugin is not currently active. Returning true in runInBackground() will result in onConnect being called as soon as Flipper connects, and allow you to use the connection at any time. See the Client Plugin Lifecycle for more details.

This should be used in combination with a persistedStateReducer on the desktop side. See the JS Plugin API for details.

The benefit is that the desktop plugin can process this data in the background and fire notifications. It also reduces the number of renders and time taken to display the data when the plugin becomes active.

Please note that a background plugin could keep some data in memory until a Flipper connection is available, for example to keep statistics about the app startup process. However, a plugin shouldn't assume it will eventually get a connection, since this depends on whether the user has enabled the plugin on the Desktop side. So make sure to not store unbounded amounts of data!