browsingContext.downloadWillBegin event

Event data

The params field in the event notification is an object with the following fields:

context

A string that contains the ID of the context in which the download was triggered.

download

A string that contains the UUID that uniquely identifies this download. The same ID is included in the corresponding browsingContext.downloadEnd event, so you can correlate the two.

navigation

A string that contains the UUID that uniquely identifies the associated navigation, or null if the download is not associated with a navigation. If the navigation was started using the browsingContext.navigate or browsingContext.reload command, this ID matches the navigation value in the command's response. The same ID is shared by other events that fire for this navigation, such as browsingContext.navigationStarted and network module events.

suggestedFilename

A string that contains the filename that the browser suggests for the download.

timestamp

A non-negative integer that represents the time when the event was fired, as milliseconds elapsed since the epoch.

url

A string that contains the URL of the download.

Description

A download can start in several ways. For example, it can start when a link with the download attribute is activated. It can also start when the browser receives a response with a Content-Disposition header that marks the resource as an attachment.

After this event fires, the browser determines whether to allow the download and where to save it, based on the download behavior configured using browser.setDownloadBehavior.

Examples

Receiving an event when a download starts

Assume you have a WebDriver BiDi connection, an active session, and a subscription to browsingContext.downloadWillBegin active.

Suppose a link on the page points to https://example.com/files/report.pdf. Before starting the download, the browser sends the following notification:

{
  "type": "event",
  "method": "browsingContext.downloadWillBegin",
  "params": {
    "context": "93ee5bd6-d256-4608-a002-9a8995cc0e5f",
    "download": "6bfa8781-e33c-4f2c-8e63-4d0f6dc5d1a1",
    "navigation": "0e2f4d20-8f0a-4de7-9749-1b12a0d6c8b0",
    "suggestedFilename": "report.pdf",
    "timestamp": 1737033600000,
    "url": "https://example.com/files/report.pdf"
  }
}

Specifications

Browser compatibility

See also

• browsingContext.downloadEnd event
• browser.setDownloadBehavior command
• session.subscribe command