In the GitHub repo, you'll find Flipper clients for Android, iOS and C++ code, but there's nothing to stop you from writing a FlipperClient for another device or OS.
Flipper clients communicate with the Flipper desktop app using JSON RPC messages over an RSocket connection.
This page documents the API, and you can use FlipperConnectionManagerImpl.cpp for reference.
Establishing a connection
Start by connecting to the Flipper server running within the desktop app. Connecting to the server registers your application with Flipper and enables plugins to interact with it. As the Flipper desktop has a different lifecycle than your app and may connect and disconnect at any time it is important that you attempt to reconnect to the Flipper server until it accepts your connection.
We use the RSocket protocol for communication between desktop and client, because it allows for easy certificate pinning and functionality like request-response messages.
In order to securely connect to Flipper, your client should first obtain a certificate.
After the client certificate has been obtained, connect to the following URL with an RSocket client:
OS: The OS which the connecting is being established from. For example
os=Android if your client is running on Android. This is usually hard-coded into the FlipperClient implementation. This string may be used by the Flipper desktop app to identify valid plugins as well as present in the UI to the user.
DEVICE: The name of the device running the application. For example
DEVICE_ID: A unique identifier for the device. The Flipper server / desktop app may use this to coalesce multiple connections originating from the save device or present the string in the UI to differentiate between connections to different clients.
APP: The name of the app running this client instance. For example
app=Facebook when connecting to a running facebook app. OS + DEVICE_ID + APP should together uniquely identify a connection.
FOREGROUND: A boolean indicating whether this connection was established with a foreground process. This is a hint to the Flipper desktop app of whether to re-focus on this connection or not. For example
foreground=true. This parameter is recommended but optional.
SDK_VERSION: A number indicating the latest protocol version this client is compatible with. You can find the current version in our C++ connection implementation. Usually stored as a constant in the client code, this allows protocol changes to be made whilst still preserving connectivity with old clients. When Flipper desktop encounters an old SDK version, it may attempt to communicate using a matching protocol. However, backwards compatibility is not guaranteed and you should strive to update clients on the rare occasion that the protocol version advances.
Responding to messages
Flipper uses a simple Remote Procedure Call protocol using JSON-formatted payloads.
method field of the payload indicates which method of the FlipperClient is being called. This will always be present.
payload field contains the JSON parameters for the method call. This may be omitted when no parameters are used.
It is recommended that implementations gracefully ignore extra fields for the sake of backwards and forwards compatibility.
Responses contain either a success object representing the return value of the RPC invocation or an error object indicating that an error occurred.
The following methods must be implemented by all FlipperClient implementations:
The syntax used for these type definitions is Flow. All requests/responses are JSON objects. Where no Response type is specified, it's a void call - no response is expected.
Returns a subset of the available plugins returned by
getPlugin. The background connections will automatically receive a connection from Flipper once it starts (and if the plugins are enabled), rather than waiting for the user to open the plugin.
Initialize a plugin. This should result in an onConnected call on the appropriate plugin. Plugins should by nature be lazy and should not be initialized up front as this may incur significant cost. The Flipper desktop client knows when a plugin is needed and should control when to initialize them.
Opposite of init. A call to deinit is made when a plugin is no longer needed and should release any resources. Don't rely only on deinit to release plugin resources as Flipper may quit without having the chance to issue a deinit call. In those cases, you should also rely on the RSocket disconnect callbacks. This call is mainly for allowing the desktop app to control the lifecycle of plugins.
The Flipper desktop app handles error reporting so you don't have to. If an error occurs during the execution of an RPC invocation, return a serialization of it in the response so it can be attributed to the method call.
If an error occurs in some other context, you can proactively send it to Flipper with the following request structure:
Testing is incredibly important when building core infrastructure and tools. The following is pseudo code for tests we would expect any new FlipperClient implementation to implement and correctly execute. To run tests we strongly encourage you to build a mock for the RSocket connection to mock out the desktop side of the protocol and to not have any network dependencies in your test code.