Client Plugin API

FlipperPlugin

The plugin implementation that runs on (mobile) applications 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.

Android

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;
  }
}

iOS

@interface MyFlipperPlugin : NSObject<FlipperPlugin>
@end

@implementation MyFlipperPlugin

- (NSString*)identifier { return @"MyFlipperPlugin"; }
- (void)didConnect:(FlipperConnection*)connection {}
- (void)didDisconnect {}
- (BOOL)runInBackground {}

@end

C++

class MyFlipperPlugin : public FlipperPlugin {
public:
  std::string identifier() const override { return "MyFlipperPlugin"; }
  void didConnect(std::shared_ptr<FlipperConnection> conn) override;
  void didDisconnect() override;
  bool runInBackground() override;
};

React Native (JS)

danger

Using Flipper from JavaScript in React Native requires the package react-native-flipper to be installed in the hosting application.

import {addPlugin} from 'react-native-flipper';

addPlugin({
  getId() {
    return 'MyFlipperPlugin';
  },
  onConnect(connection) {
    console.log('connected');
  },
  onDisconnect() {
    console.log('disconnected');
  },
  runInBackground() {
    return false;
  },
});

React (JS)

danger

Using Flipper from JavaScript in your browser requires the package js-flipper to be installed in the hosting application.

import {flipperClient} from 'js-flipper';

// We want to import and start flipper client only in development and test modes
// We want to exclude it from our production build
let flipperClientPromise;
if (process.env.NODE_ENV !== 'production') {
  flipperClientPromise = import('js-flipper').then(({flipperClient}) => {
    flipperClient.start('React Tic-Tac-Toe');
    return flipperClient;
  });
}

flipperClientPromise?.then((flipperClient) => {
  flipperClient.addPlugin({
    getId() {
      return 'MyFlipperPlugin';
    },
    onConnect(connection) {
      console.log('connected');
    },
    onDisconnect() {
      console.log('disconnected');
    },
    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.

Android

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());
  }
});

iOS

@interface MyFlipperPlugin : NSObject<FlipperPlugin>
@end

@implementation MyFlipperPlugin

- (NSString*)identifier { return @"MyFlipperPlugin"; }

- (void)didConnect:(FlipperConnection*)connection
{
  [connection receive:@"getData" withBlock:^(NSDictionary *params, FlipperResponder *responder) {
    [responder success:@{
      @"data":[MyData get],
    }];
  }];
}

- (void)didDisonnect {}

@end

C++

void MyFlipperPlugin::didConnect(std::shared_ptr<FlipperConnection> conn) {
  conn->receive("getData", [](const folly::dynamic &params,
                             std::unique_ptr<FlipperResponder> responder) {
    dynamic response = folly::dynamic::object("data", getMyData());
    responder->success(response);
  });
}

React Native (JS)

addPlugin({
  getId() {
    return 'MyFlipperPlugin';
  },
  onConnect(connection) {
    console.log('connected');
    connection.receive('getData', (data, responder) => {
      console.log('incoming data', data);
      // respond with some data
      responder.success({
        ack: true,
      });
    });
  },
  // ...as-is
});

React (JS)

flipperClient.addPlugin({
  getId() {
    return 'MyFlipperPlugin';
  },
  onConnect(connection) {
    console.log('connected');
    connection.receive('getData', (data) => {
      console.log('incoming data', data);
      // return data to send it as a response
      return {
        ack: true,
      };
    });
    // Flipper client can also send the data you return from your async functions
    connection.receive('getDataAsync', async (data) => {
      console.log('incoming data', data);
      const myAsyncData = await doAsyncStuff();
      // return data to send it as a response
      return {
        data: myAsyncData,
      };
    });
    // Flipper client catches your exceptions and sends them as an error response to the desktop
    connection.receive('getErrorData', (data) => {
      console.log('incoming data', data);
      throw new Error('Ooops');
    });
    // It catches the execptions in your async functions as well
    connection.receive('getErrorDataAsync', async (data) => {
      console.log('incoming data', data);
      const myAsyncData = await doAsyncStuff();
      if (!myAsyncData) {
        throw new Error('Ooops! Async data is not there!!!');
      }
    });
  },
  // ...as-is
});

Push data to the desktop

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

Android

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

iOS

[connection send:@"getData" withParams:@{@"message":@"hello"}];

C++

void MyFlipperPlugin::didConnect(std::shared_ptr<FlipperConnection> conn) {
  dynamic message = folly::dynamic::object("message", "hello");
  conn->send("getData", message);
}

React Native (JS)

addPlugin({
  getId() {
    return 'MyFlipperPlugin';
  },
  onConnect(connection) {
    console.log('connected');
    connection.send('newRow', {message: 'Hello'});
  },
  // ...as-is
});

React (JS)

flipperClient.addPlugin({
  getId() {
    return 'MyFlipperPlugin';
  },
  onConnect(connection) {
    console.log('connected');
    connection.send('newRow', {message: 'Hello'});
  },
  // ...as-is
});

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

Null checks may be required as plugins may not be initialized, such as in production builds.

Android

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

iOS

FlipperClient *client = [FlipperClient sharedClient];
MyFlipperPlugin *myPlugin = [client pluginWithIdentifier:@"MyFlipperPlugin"];
[myPlugin sendData:myData];

C++

auto& client = FlipperClient::instance();
auto myPlugin = client.getPlugin<MyFlipperPlugin>("MyFlipperPlugin");
if (myPlugin) {
  myPlugin->sendData(myData);
}

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

Bi-directional communication demo

A minimal communication demo for Android and iOS can be found in the 'Sample' project:

• Desktop implementation
• Android / iOS

For React Native and JavaScript, there is a simple game of Tic Tac Toe:

• Desktop implementation
• React Native implementation / JavaScript (React) implementation

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() results in onConnect being called as soon as Flipper connects, which enables you to use the connection at any time. For more detals, see the Client Plugin Lifecycle. The advantage of this method 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.

danger

Please note that a background plugin could keep some data in memory until a Flipper connection is available, such as 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.

It's important to make sure that unbounded amounts of data are not stored!