session.subscribe command

Syntax

{
  "method": "session.subscribe",
  "params": {
    "events": ["<event name>"]
  }
}

Parameters

The input is an object with the following fields:

events

An array of one or more strings that specifies event names for subscription. Each string can be either a specific event name (for example, "log.entryAdded") or a module name (for example, "log") that subscribes the client to all events in that module.

contexts Optional

An array of one or more browsing context IDs, each corresponding to a tab or frame. If specified, events are received only for those contexts and their descendants. This field cannot be used if userContexts is also specified.

userContexts Optional

An array of one or more user context IDs, each corresponding to a browser profile or container. If specified, events are received only for those user contexts. This field cannot be used if contexts is also specified.

If neither contexts nor userContexts is provided, the subscription is global, so events are received for all browsing contexts.

Return value

An object with the following fields:

subscription

A string that contains the unique identifier for this subscription.

Errors

invalid argument

The events array is empty or omitted, an event name is not recognized, contexts or userContexts is provided but empty, or values for both contexts and userContexts were provided in the same request.

Examples

Subscribing to an event globally

With a WebDriver BiDi connection and an active session, send the following message to subscribe to the log.entryAdded event for all browsing contexts:

{
  "id": 2,
  "method": "session.subscribe",
  "params": {
    "events": ["log.entryAdded"]
  }
}

The browser responds with a subscription ID as follows:

{
  "id": 2,
  "type": "success",
  "result": {
    "subscription": "c7b7b3a2-1f4b-4b4e-8a1f-2a3b4c5d6e7f"
  }
}

Subscribing to multiple events

With a WebDriver BiDi connection and an active session, send the following message to subscribe to all events in the log module and a specific event from the network module:

{
  "id": 3,
  "method": "session.subscribe",
  "params": {
    "events": ["log", "network.beforeRequestSent"]
  }
}

The browser responds with a subscription ID as follows:

{
  "id": 3,
  "type": "success",
  "result": {
    "subscription": "e9d0a5c4-3h6d-6d6g-0c3h-4c5d6e7f8g9h"
  }
}

Specifications

Browser compatibility

See also

• session.unsubscribe command
• session.new command
• session.end command