实时信令

实时信令（Real-time Signaling） 是一套先进的事件驱动系统，用于处理自动化工作流中的异步通信。这种基于信号的架构可实现自动化脚本与外部系统之间的无缝交互，其中 多因素认证（MFA）处理 是其最关键的应用之一。

概述

实时信令系统为管理自动化工作流中的异步事件提供了一个稳健的框架。虽然 MFA 验证 是其主要用例，但该系统灵活的架构支持多样化的事件驱动场景。

多因素认证（MFA） 是一项关键的安全功能，但它往往会成为自动化工作流的瓶颈，导致流程失败或账户被锁定。

为什么 MFA 处理对自动化至关重要：

✅ 确保不中断的访问：处理意外出现的短信验证码、邮件 OTP 或 TOTP 认证，而不会中断工作流

✅ 防止工作流崩溃：传统自动化在出现 MFA 提示时会卡死，而 Agent Browser 能够顺畅地处理这些情况

✅ 保持稳定的会话：长时间运行的任务通过安全的验证状态管理保持登录状态

✅ 降低账户风险：类人的验证行为可降低触发安全机制的可能性

超越 MFA：通用事件系统

信令系统的能力不仅限于认证，还可以处理：

表单提交 与状态更新
任务进度 通知
API 回调 与 webhook
用户交互 与状态变更
跨系统的 流程协调
实时监控 与告警

完整的信令解决方案：

可靠的 MFA 验证（主要用例）
面向自动化需求的 通用事件处理
用于传入验证码和数据的 多种输入方式
异步处理（非阻塞）
完整的 CDP 与 HTTP API 支持
与认证流程的 通用兼容性

支持的 API

Scrapeless 同时支持 CDP 与 HTTP 接口用于实时信令：

API	CDP Method	HTTP Endpoint	说明
发送信号	`Signal.send`	`POST /signal/send`	向事件通道发送数据
等待信号	`Signal.wait`	`GET /signal/wait`	等待事件通道上的数据
列出事件	`Signal.list`	`GET /signal/list`	列出所有待处理的事件名称
获取统计信息	`Signal.stats`	`GET /signal/stats`	获取队列统计信息
清除事件	`Signal.clear`	`DELETE /signal/clear`	清除指定或全部事件

CDP API

CDP Signal API 允许你在浏览器自动化工作流中通过事件通道发送和接收信号。了解更多

Signal.send

向指定的事件通道发送信号数据。

请求格式：

{
  "method": "Signal.send",
  "params": {
    "event": "string",
    "data": "object"
  }
}

参数：

参数	类型	是否必填	说明
event	string	✓	事件通道的名称
data	object	✓	要通过通道发送的数据

示例：

await client.send('Signal.send', {
  event: 'mfa_code',
  data: { code: '123456', type: 'sms' }
});

Signal.wait

等待指定事件通道上的信号数据。

请求格式：

{
  "method": "Signal.wait",
  "params": {
    "event": "string",
    "timeout": 60000
  }
}

参数：

参数	类型	是否必填	说明
event	string	✓	要等待的事件通道名称
timeout	number	X	最长等待时间，单位为毫秒（默认：60000）

示例：

const result = await client.send('Signal.wait', {
  event: 'mfa_code',
  timeout: 60000
});
console.log('Received MFA code:', result.data);

Signal.list

列出队列中所有待处理的事件名称。

请求格式：

{
  "method": "Signal.list",
  "params": {}
}

参数： 无需参数

示例：

const list = await client.send('Signal.list');
console.log('Pending events:', list.events);
// Output: ["mfa_code", "captcha_result", "order_status"]
 
// Check for specific event
if (list.events.includes('mfa_code')) {
  console.log('MFA code in queue');
}

Signal.stats

获取队列统计信息和订阅者信息。

请求格式：

{
  "method": "Signal.stats",
  "params": {}
}

参数： 无需参数

响应字段：

字段	类型	说明
events	number	所有待处理事件名称的列表
waiters	number	关于等待中订阅者的信息

示例：

const client = await page.target().createCDPSession();
 
// Get statistics
const stats = await client.send('Signal.stats');
console.log('Pending events:', stats.events);
console.log('Waiting subscribers:', stats.waiters);

Signal.clear

从队列中清除指定或全部事件。

请求格式：

{
  "method": "Signal.clear",
  "params": {
    "event": "string (optional)"
  }
}

参数：

参数	类型	是否必填	说明
event	string	X	要清除的特定事件。若省略，则清除所有事件

HTTP REST API

对于外部系统而言，HTTP REST 端点提供了比 CDP 连接设置更简单的替代方案。这样无需为每次数据传输都建立 WebSocket 连接。了解更多

默认浏览器端点前缀： https://browser.scrapeless.com/browser/{taskId}

POST /signal/send

通过 HTTP 发送信号。

请求格式：

POST https://browser.scrapeless.com/browser/{taskId}/signal/send?x-api-token={API_KEY}
Content-Type: application/json
 
{
  "event": "string",
  "data": "object"
}

参数：

参数	类型	是否必填	说明
event	string	✓	事件通道的名称
data	object	✓	要通过通道发送的数据

示例：

curl -X POST 'https://browser.scrapeless.com/browser/{taskId}/signal/send?x-api-token={API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
    "event": "mfa_code",
    "data": { "code": "123456", "type": "sms" }
  }'

GET /signal/wait

通过 HTTP GET 请求等待信号。

请求格式：

GET https://browser.scrapeless.com/browser/{taskId}/signal/wait?x-api-token={API_KEY}&event={event}&timeout={timeout}

参数：

参数	类型	是否必填	说明
event	string	✓	要等待的事件通道名称
timeout	number	X	最长等待时间，单位为毫秒（默认：60000）

示例：

# Wait for MFA code with 60 second timeout
curl -X GET 'https://browser.scrapeless.com/browser/{taskId}/signal/wait?x-api-token={API_KEY}&event=mfa_code&timeout=60000'

GET /signal/list

列出所有待处理的事件名称。

请求格式：

GET https://browser.scrapeless.com/browser/{taskId}/signal/list?x-api-token={API_KEY}

参数： 无需参数

示例：

# List all pending events
curl -X GET 'https://browser.scrapeless.com/browser/{taskId}/signal/list?x-api-token={API_KEY}'

GET /signal/stats

获取队列统计信息。

请求格式：

GET https://browser.scrapeless.com/browser/{taskId}/signal/stats?x-api-token={API_KEY}

参数： 无需参数

示例：

# Get queue statistics
curl -X GET 'https://browser.scrapeless.com/browser/{taskId}/signal/stats?x-api-token={API_KEY}'

DELETE /signal/clear

从队列中清除事件。

请求格式：

DELETE https://browser.scrapeless.com/browser/{taskId}/signal/clear?x-api-token={API_KEY}
Content-Type: application/json
 
{
  "event": "string (optional)"
}

参数：

参数	类型	是否必填	说明
event	string	X	要清除的特定事件。若省略，则清除所有事件

示例：

# Clear specific event
curl -X DELETE 'https://browser.scrapeless.com/browser/{taskId}/signal/clear?x-api-token={API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{"event": "mfa_code"}'
 
# Clear all events
curl -X DELETE 'https://browser.scrapeless.com/browser/{taskId}/signal/clear?x-api-token={API_KEY}'

最佳实践

使用合适的超时时间

根据预期的验证延迟设置超时值。典型的 MFA 送达时间为 10-60 秒。

错误处理

始终检查响应状态码（200、408、400），以妥善处理成功、超时和错误情况。

队列监控

定期检查队列统计信息，以检测可能预示系统问题的积压情况。

事件通道命名

使用具有描述性的事件通道名称（例如 mfa_code、email_verification、totp_token），以避免在多事件场景中产生混淆。

异步处理

利用异步信号处理，在等待用户输入时防止脚本阻塞。

队列清理

及时清除队列中过时的事件，以维持系统性能并防止内存问题。

集成提示

信令系统设计上可与 CDP 和 HTTP 两种接口无缝协作，让你能够为具体用例选择最合适的方式。CDP 提供实时、低延迟的通信，而 HTTP REST 端点则为外部集成提供了简便性。

完整示例

const puppeteer = require('puppeteer-core');
 
(async () => {
    const API_TOKEN = 'API Key';
    const API_URL = 'https://api.scrapeless.com/api/v2/browser'; // Create session task API endpoint
 
    try {
        // Step 1: Get session taskId via HTTP API
        const sessionResponse = await fetch(API_URL, {
            method: 'GET',
            headers: {'x-api-token': API_TOKEN},
        });
 
        const {taskId} = await sessionResponse.json();
        console.log('Session created with task ID:', taskId);
 
        // Step 2: Connect to browser by taskId
        const browser = await puppeteer.connect({
            browserWSEndpoint: `wss://api.scrapeless.com/browser/${taskId}`,
            headers: {'x-api-token': API_TOKEN},
        });
 
        // Step 3: Navigate to page and wait for signal
        const page = await browser.newPage();
        await page.goto("https://example.com", {waitUntil: "domcontentloaded"});
 
        const client = await page.createCDPSession();
 
        console.log('Waiting for example event...');
        const result = await client.send('Signal.wait', {
            event: 'example_event',
            timeout: 60000
        });
 
        console.log('Received example data:', result.data);
 
        await browser.close();
    } catch (error) {
        console.error('Error occurred:', error);
    }
})();

Agent Browser 实时信令系统为在自动化工作流中处理多因素认证提供了一个稳健、灵活的框架。通过将 CDP 与 HTTP 接口和智能事件队列系统相结合，它能够在保持安全性和可靠性的同时，实现外部验证系统的无缝集成。

无论你是构建简单的自动化脚本，还是复杂的多系统编排，信令系统的异步、非阻塞架构都能确保你的工作流可靠地完成——即使需要进行 MFA 验证。

浏览器扩展自定义指纹