Skip to content

Commit 1623974

Browse files
kathaylpedrosousa
kathayl
and
pedrosousa
authored
Add Live View and Human in the Loop feature docs (#29758)
* Add Live View and Human in the Loop feature docs * Reorder sidebar (Live View 1, HITL 2), fix CDP→Browser Sessions wording, add coming-soon handoff note, style fixes * Address review feedback on Live View and HITL docs - Remove Full viewing mode row (not yet tested) - Change Inspector URL to mode=devtools - Remove "Get the Live View URL programmatically" section (not yet shipped) - Condense Native Chrome DevTools pros/cons into single paragraph - Replace Cloudflare.getLiveView with includeTargets=true in HITL example - Add timeout and Slack/chat notes to HITL code comments - Add bot detection note to HITL page * Use targets=true instead of includeTargets=true in HITL example * Address second round of review feedback - Swap Tab/Inspector descriptions in viewing modes table - Use Sophia's wording for Native Chrome DevTools paragraph - Add 5-minute URL expiry note to HITL page - Clarify Tab description as 'Standalone page view' * Update src/content/docs/browser-rendering/features/live-view.mdx Co-authored-by: Pedro Sousa <680496+pedrosousa@users.noreply.github.com> * Update src/content/docs/browser-rendering/features/human-in-the-loop.mdx Co-authored-by: Pedro Sousa <680496+pedrosousa@users.noreply.github.com> * Update src/content/docs/browser-rendering/features/human-in-the-loop.mdx Co-authored-by: Pedro Sousa <680496+pedrosousa@users.noreply.github.com> * Update src/content/docs/browser-rendering/features/live-view.mdx Co-authored-by: Pedro Sousa <680496+pedrosousa@users.noreply.github.com> * Update src/content/docs/browser-rendering/features/live-view.mdx Co-authored-by: Pedro Sousa <680496+pedrosousa@users.noreply.github.com> * Update src/content/docs/browser-rendering/features/live-view.mdx Co-authored-by: Pedro Sousa <680496+pedrosousa@users.noreply.github.com> * Update src/content/docs/browser-rendering/features/live-view.mdx Co-authored-by: Pedro Sousa <680496+pedrosousa@users.noreply.github.com> --------- Co-authored-by: Pedro Sousa <680496+pedrosousa@users.noreply.github.com>
1 parent c2a3d03 commit 1623974

File tree

3 files changed

+207
-1
lines changed

3 files changed

+207
-1
lines changed

‎src/content/docs/browser-rendering/features/custom-fonts.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ pcx_content_type: how-to
33
title: Custom fonts
44
description: Learn how to add custom fonts to Browser Rendering for use in screenshots and PDFs.
55
sidebar:
6-
order: 1
6+
order: 3
77
---
88

99
import { Tabs, TabItem } from "~/components";

‎src/content/docs/browser-rendering/features/human-in-the-loop.mdx‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
---
2+
pcx_content_type: how-to
3+
title: Human in the Loop
4+
description: Temporarily hand off browser control to a human operator for authentication, sensitive actions, or tasks that are difficult to fully automate.
5+
sidebar:
6+
order: 2
7+
badge: Beta
8+
---
9+
10+
Some browser automation workflows require manual intervention. A login page may need multi-factor authentication, a form may require sensitive credentials you do not want to pass to an automation script, or a task may be too complex to fully automate. Human in the Loop lets a human step into a live browser session through [Live View](/browser-rendering/features/live-view/) to handle what automation cannot, then hand control back to the script.
11+
12+
## How it works
13+
14+
Human in the Loop works with any [Browser Session](/browser-rendering/#integration-methods) and uses [Live View](/browser-rendering/features/live-view/) to give humans access:
15+
16+
1. Your automation script navigates to a page that needs human input.
17+
2. The script retrieves the [Live View](/browser-rendering/features/live-view/) URL from the session's target list and shares it with a human operator (for example, by sending it via Slack, email, or displaying it in a user interface).
18+
3. The human operator opens the Live View URL and completes the required action (logging in, solving a CAPTCHA, entering sensitive data, etc.).
19+
4. The automation script detects that the human is done (for example, by waiting for a navigation event or polling for a page element) and resumes.
20+
21+
A more structured handoff flow where the agent can signal that it needs help and notify a human is coming soon.
22+
23+
## Example: login with human assistance
24+
25+
This example uses [Puppeteer](/browser-rendering/puppeteer/) connected to Browser Run via the [CDP](/browser-rendering/cdp/) endpoints. The script navigates to a login page, shares a Live View URL for a human to enter credentials, then continues the automation after login completes.
26+
27+
```js
28+
import puppeteer from "puppeteer-core";
29+
30+
const ACCOUNT_ID = "<your-account-id>";
31+
const API_TOKEN = "<your-api-token>";
32+
33+
// Create a browser session via CDP
34+
const response = await fetch(
35+
`https://api.cloudflare.com/client/v4/accounts/${ACCOUNT_ID}/browser-rendering/devtools/browser?keep_alive=600000&targets=true`,
36+
{
37+
method: "POST",
38+
headers: { Authorization: `Bearer ${API_TOKEN}` },
39+
}
40+
);
41+
const { webSocketDebuggerUrl, targets } = await response.json();
42+
const liveUrl = targets[0].devtoolsFrontendUrl;
43+
44+
// Connect Puppeteer to the session
45+
const browser = await puppeteer.connect({
46+
browserWSEndpoint: webSocketDebuggerUrl,
47+
headers: { Authorization: `Bearer ${API_TOKEN}` },
48+
});
49+
50+
const page = await browser.newPage();
51+
await page.goto("https://example.com/login");
52+
53+
// Share the Live View URL with the human operator (for example, send it via Slack, email, or display it in a UI)
54+
console.log(`Human input needed. Open this URL: ${liveUrl}`);
55+
56+
// Wait for the human to complete login (5 minute timeout — the script will continue after this period)
57+
await page.waitForNavigation({ waitUntil: "networkidle0", timeout: 300000 });
58+
59+
// Login complete, continue automation
60+
const cookies = await page.cookies();
61+
console.log("Login complete. Continuing automation...");
62+
63+
await page.goto("https://example.com/dashboard");
64+
const content = await page.content();
65+
66+
browser.disconnect();
67+
```
68+
69+
The Live View URL is valid for five minutes from when it was generated. If the URL expires before the human operator opens it, list the targets again to get a fresh URL.
70+
71+
## Use cases
72+
73+
- **Authentication flows**: Login pages with MFA, SSO, or CAPTCHA that cannot be bypassed programmatically
74+
- **Sensitive data entry**: Forms requiring credentials or personal information you do not want to pass to an automation script
75+
- **Complex interactions**: One-off tasks that are too difficult or not worth fully automating, such as configuring a dashboard or approving a workflow
76+
- **Verification steps**: Confirming an order, reviewing generated content, or approving an action before the script proceeds
77+
78+
:::note[Bot detection]
79+
Browser Rendering requests are [always identified as bot traffic](/browser-rendering/faq/#will-browser-rendering-be-detected-by-bot-management). Even with a human controlling the session, some third-party services may still block the request.
80+
:::

‎src/content/docs/browser-rendering/features/live-view.mdx‎

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
---
2+
pcx_content_type: how-to
3+
title: Live View
4+
description: View and interact with remote Browser Run sessions in real time using the hosted DevTools UI or native Chrome DevTools.
5+
sidebar:
6+
order: 1
7+
badge: Beta
8+
---
9+
10+
import { CURL, DashButton } from "~/components";
11+
12+
Live View lets you see and interact with a remote Browser Run session in real time. This is useful for debugging automation scripts, monitoring what a browser is doing, or manually stepping in when a task requires human intervention (see [Human in the Loop](/browser-rendering/features/human-in-the-loop/)).
13+
14+
Live View is available for any [Browser Session](/browser-rendering/#integration-methods), including sessions created with [Puppeteer](/browser-rendering/puppeteer/), [Playwright](/browser-rendering/playwright/), or the [CDP](/browser-rendering/cdp/) endpoints.
15+
16+
## How to access Live View
17+
18+
There are three ways to access Live View: through the Cloudflare dashboard, via the hosted user interface (UI) at `live.browser.run`, or using native Chrome DevTools.
19+
20+
### Cloudflare dashboard
21+
22+
In the Cloudflare dashboard, go to the **Browser Run** page and select the **Live Sessions** tab. This shows all active browser sessions in your account. Expand a session to see its tabs, then select **Open** to open the Live View for that tab.
23+
24+
<DashButton url="/?to=/:account/workers/browser-rendering" />
25+
26+
### Hosted UI (any browser)
27+
28+
When you create a session or list targets through the [CDP](/browser-rendering/cdp/) endpoints, the API response includes a `devtoolsFrontendUrl` for each target (tab). Open this URL in any browser to load the DevTools UI hosted at `live.browser.run`, which streams the remote session to your browser.
29+
30+
The hosted UI supports two viewing modes, controlled by the `mode` parameter in the URL:
31+
32+
| Mode | URL pattern | Description |
33+
| --- | --- | --- |
34+
| Tab | `https://live.browser.run/ui/view?mode=tab&wss=...` | Standalone page view |
35+
| Inspector | `https://live.browser.run/ui/view?mode=devtools&wss=...` | DevTools inspector panel (Elements, Console, Network, etc.) |
36+
37+
### Native Chrome DevTools (Chrome only)
38+
39+
Because Browser Run speaks standard CDP, you can connect Chrome's built-in DevTools directly to a remote session. Replace the `https://live.browser.run/ui/inspector?wss=` prefix in the `devtoolsFrontendUrl` with the `devtools://` protocol:
40+
41+
```txt
42+
devtools://devtools/bundled/inspector.html?wss=live.browser.run/api/devtools/browser/SESSION_ID/page/TARGET_ID?jwt=...
43+
```
44+
45+
Paste this URL into Chrome's address bar to connect native DevTools to the remote browser session. You will get the same DevTools interface you use for local debugging. The `devtools://` protocol is Chrome-only and limited to inspector viewing mode.
46+
47+
:::caution[URL validity]
48+
The `devtoolsFrontendUrl` is valid for five minutes from when it was generated. If you do not open the URL within this timeframe, list the targets again to get a fresh URL. Once the DevTools connection is established, it remains active as long as the browser session is alive.
49+
:::
50+
51+
## View a new session
52+
53+
1. Create a browser session with `targets=true` to include target URLs in the response:
54+
55+
<CURL
56+
url="https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/browser-rendering/devtools/browser"
57+
method="POST"
58+
headers={{
59+
Authorization: "Bearer $CLOUDFLARE_API_TOKEN",
60+
}}
61+
query={{
62+
keep_alive: "600000",
63+
targets: "true",
64+
}}
65+
/>
66+
67+
```json
68+
{
69+
"sessionId": "1909cef7-23e8-4394-bc31-27404bf4348f",
70+
"targets": [
71+
{
72+
"description": "",
73+
"devtoolsFrontendUrl": "https://live.browser.run/ui/inspector?wss=live.browser.run/api/devtools/browser/1909cef7-.../page/8E598E99...?jwt=...",
74+
"id": "8E598E996530FB09E46A22B8B7754F7F",
75+
"title": "about:blank",
76+
"type": "page",
77+
"url": "about:blank",
78+
"webSocketDebuggerUrl": "wss://live.browser.run/api/devtools/browser/1909cef7-.../page/8E598E99...?jwt=..."
79+
}
80+
],
81+
"webSocketDebuggerUrl": "wss://api.cloudflare.com/client/v4/accounts/{account_id}/browser-rendering/devtools/browser/1909cef7-..."
82+
}
83+
```
84+
85+
2. Copy the `devtoolsFrontendUrl` from `targets[0]` and open it in your browser. You now have a live, interactive view of the remote browser session.
86+
87+
## View an existing session
88+
89+
If you have a running session and want to connect to it:
90+
91+
1. List your active sessions:
92+
93+
<CURL
94+
url="https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/browser-rendering/devtools/session"
95+
method="GET"
96+
headers={{
97+
Authorization: "Bearer $CLOUDFLARE_API_TOKEN",
98+
}}
99+
/>
100+
101+
2. Using the session ID, list the targets in that session:
102+
103+
<CURL
104+
url="https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/browser-rendering/devtools/browser/$SESSION_ID/json/list"
105+
method="GET"
106+
headers={{
107+
Authorization: "Bearer $CLOUDFLARE_API_TOKEN",
108+
}}
109+
/>
110+
111+
112+
```json output {8}
113+
[
114+
{
115+
"id": "110850A800BDB8B593CDDA30676635CF",
116+
"type": "page",
117+
"url": "https://example.com",
118+
"title": "Example Domain",
119+
"description": "",
120+
"devtoolsFrontendUrl": "https://live.browser.run/ui/view?wss=live.browser.run/api/devtools/browser/28d75446-.../page/110850A8...?jwt=...",
121+
"webSocketDebuggerUrl": "wss://live.browser.run/api/devtools/browser/28d75446-.../page/110850A8...?jwt=..."
122+
}
123+
]
124+
```
125+
126+
3. Copy the `devtoolsFrontendUrl` and open it in your browser.

0 commit comments

Comments
 (0)