flipper/docs/extending/new-clients.mdx

---
id: new-clients
title: Implementing a Flipper Client
---

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](http://rsocket.io/) connection.

This page documents the API, and you can use [FlipperConnectionManagerImpl.cpp](https://github.com/facebook/flipper/blob/master/xplat/Flipper/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](establishing-a-connection).

After the client certificate has been obtained, connect to the following URL with an RSocket client:

```
localhost:8088/sonar?os={OS}
                     &device={DEVICE}
                     &device_id={DEVICE_ID}
                     &app={APP}
                     &sdk_version={SDK_VERSION}
                     &foreground={FOREGROUND}
```

**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=iPhone7`.

**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](https://github.com/facebook/flipper/blob/master/xplat/Flipper/FlipperConnectionManagerImpl.cpp#L37). 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.

The `method` field of the payload indicates which method of the FlipperClient is being called. This will always be present.

The `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](https://flow.org/en/docs/types/objects/). All requests/responses are JSON objects. Where no Response type is specified, it's a void call - no response is expected.

### getPlugins
Return the available plugins as a list of identifiers. A plugin identifier is a string which is matched with the plugin identifier of desktop javascript plugins. This allows the client to specify the plugins it supports.

```
Request = {
  "method": "getPlugins",
}

Response = {
  "success": {
    "plugins": Array<string>
  },
}
```


### getBackgroundPlugins

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.

```
Request = {
  "method": "getBackgroundPlugins",
}

Response = {
  "success": {
    "plugins": Array<string>
  },
}
```

### init
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.
```
Request = {
  "method": "init",
  "params": {
    "plugin": string,
  },
}
```

### deinit
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.
```
Request = {
  "method": "deinit",
  "params": {
    "plugin": string,
  },
}
```

### execute
This is the main call and how the Flipper desktop plugins and client plugins communicate. When a javascript desktop plugin issues a client request it will be wrapped in one of these execute calls. This execute indicates that the call should be redirected to a plugin.
request.params.api is the plugin id.
request.params.method is the method within the plugin to execute.
request.params.params is an optional params object containing the parameters to the RPC invocation.

```
Request = {
  "method": "execute",
  "params": {
    "api": string,
    "method": string,
    "params": ?Object,
  },
}

Response = {
  "success": Object,
} | {
  "error": Object,
}
```

## Error Reporting

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:
```
Request = {
  error: {
    message: string,
    stacktrace: string,
  }
}
```
While in development mode, Flipper will display any client errors next to javascript errors in the Electron/Chrome DevTools console.

## Testing
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.

```
test("GetPlugins", {
  let connection = new MockConnection();
  let client = new FlipperClient(connection);
  let plugin = {id: "test"};

  client.addPlugin(plugin);
  client.start();

  connection.onReceive({
    id: 1,
    method: "getPlugins",
  });

  assert(connection.sentMessages, contains({
    id: 1,
    success:{
      plugins: ["test"],
    },
  }));
});
```
```
test("InitDeinit", {
  let connection = new MockConnection();
  let client = new FlipperClient(connection);
  let plugin = {id: "test", connected: false};

  client.addPlugin(plugin);
  client.start();

  assertFalse(plugin.connected);

  connection.onReceive({
    id: 1,
    method: "init",
    params: {
      plugin: "test",
    },
  });

  assertTrue(plugin.connected);

  connection.onReceive({
    id: 1,
    method: "deinit",
    params: {
      plugin: "test",
    },
  });

  assertFalse(plugin.connected);
});
```
```
test("Disconnect", {
  let connection = new MockConnection();
  let client = new FlipperClient(connection);
  let plugin = {id: "test", connected: false};

  client.addPlugin(plugin);
  client.start();

  assertFalse(plugin.connected);

  connection.onReceive({
    id: 1,
    method: "init",
    params: {
      plugin: "test",
    },
  });

  assertTrue(plugin.connected);
  connection.disconnect();
  assertFalse(plugin.connected);
});
```
```
test("Execute", {
  let connection = new MockConnection();
  let client = new FlipperClient(connection);
  let plugin = {
    id: "test",
    reverse: (params, responder) => {
      responder.success({word: params.word.reverse()});
    },
  };

  client.addPlugin(plugin);
  client.start();

  connection.onReceive({
    id: 1,
    method: "init",
    params: {
      plugin: "test",
    },
  });

  connection.onReceive({
    id: 1,
    method: "execute",
    params: {
      api: "test",
      method: "reverse",
      params: {
        word: "hello"
      },
    },
  });

  assert(connection.sentMessages, contains({
    id: 1,
    success:{
      word: "olleh",
    },
  }));
});
```