Web Replay Protocol

The Web Replay Protocol is used by tools to upload and inspect Web Replay recordings.

This protocol is preliminary and will grow substantially over time. Join the #protocol channel in our Slack community for news and discussions.

Web Replay

The Web Replay browser is used to make complete recordings of a tab which capture all JS, DOM, and other behaviors. These recordings are uploaded to Web Replay's cloud service, and clients can then connect to the cloud service and inspect the recordings. Both uploading and inspecting are performed via the Web Replay Protocol.

The Web Replay Protocol is separate from the Web Replay browser itself and the format of its recordings. Other ways to make recordings will be added in the future, and tools built on top of the Web Replay Protocol will be able to interact with any recording, regardless of how it was made.

Protocol Overview

The design of the Web Replay Protocol is based on the Chrome DevTools Protocol (which is in turn based on JSON-RPC). Connections and messages are handled in very similar ways, and when appropriate, messages and values sent over the Web Replay Protocol are structured in the same way as in the Chrome DevTools Protocol.

To connect to the Web Replay cloud service, open a websocket connection to wss://dispatch.webreplay.io. The protocol can then be used immediately, with no authentication (this will change soon).

The protocol is used by sending it requests over the websocket. Requests are stringified JSON objects with the following properties:

    id: String or integer which is unique for this request among all requests made over the connection.
    method: Name of the method used for the request.
    params: Object containing any parameters for the request. Keys in the object are the method's parameter names. This may be omitted for requests with no parameters.
    sessionId: String identifying any associated session. This is required for methods in certain domains, and omitted for others.
    pauseId: String identifying any associated pause. This is required for methods in certain domains, and omitted for others.

The cloud service will respond to a request with a response object. Responses are stringified JSON objects with the following properties:

    id: ID for the request being responded to, or null for requests whose ID could not be determined.
    result: Object containing the request's return values. This is always included for requests that succeeded. Keys in the object are the method's return value names.
    error: Error description object. This is always included for requests that failed. This has an integral code property, string message property, and optional data property which describe the error.

When uploading recordings, binary data messages can be sent over the protocol instead of a string request. See the Internal domain for details on this.

Events can be emitted by the cloud service which are not responses to a message. Events are stringified JSON objects with the following properties:

    method: Name of the event being emitted.
    params: Object containing any parameters for the event. Keys in the object are the event's parameter names. This may be omitted for events with no parameters.
    sessionId: String identifying any associated session. This is used for events in certain domains, and omitted for others.