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 a WebSocket connection.

This page documents the API. For reference, use the FlipperConnectionManagerImpl.cpp.

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's important that you continue to attempt to reconnect to the Flipper server until it accepts your connection.

The WebSocket protocol is used for communication between desktop and client because it enables easy certificate pinning and functionality, such as with 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 a WebSocket client:

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

The URL parameters are detailed in the following table.

Parameter	Detail	Example
`OS`	The OS from which the connection is being established. 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.	`os=Android` (If your client is running on Android).
`DEVICE`	The name of the device running the application.	`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. The combination of `OS` + `DEVICE_ID` + `APP` uniquely identifies a connection.	`app=Facebook` (When connecting to a running facebook app).
`FOREGROUND` (Optional)	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. Though optional, this paramater is recommended.	`foreground=true`
`SDK_VERSION`	A number indicating the latest protocol version with which the client is compatible. You can find the current version in the 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 (RPC) 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.

Methods

The methods detailed in the following sub-sections 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.

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

This is the 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 such ases, you should also rely on the WebSocket 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 - the plugin id.
request.params.method - the method within the plugin to execute.
request.params.params - 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. If an error occurs during the execution of an RPC invocation, it returns 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 Chrome Developer Tools console.

Testing

Testing is incredibly important when building core infrastructure and tools. The following is pseudocode for tests any new FlipperClient implementation is expected to implement and correctly execute. To run tests, it's strongly recommended that you to build a mock for the WebSocket 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",
    },
  }));
});

Establishing a connection​

Responding to messages​

Methods​

getPlugins​

getBackgroundPlugins​

init​

deinit​

execute​

Error Reporting​

Testing​