Kết nối Playwright với AdsPower qua Local API

Playwright là framework tự động hoá trình duyệt hiện đại, được nhóm đọc kỹ thuật ưa chuộng nhờ API bất đồng bộ rõ ràng và khả năng chạy song song tốt. Bài này hướng dẫn cách gắn Playwright vào một hồ sơ AdsPower đang chạy.

Nguyên lý chung: Kết nối qua cdp

Giống như Selenium và Puppeteer, Playwright không tự mở trình duyệt riêng khi làm việc với AdsPower. Thay vào đó, Playwright hỗ trợ sẵn phương thức connectOverCDP() — cho phép gắn vào bất kỳ trình duyệt Chromium nào đang expose giao thức gỡ lỗi từ xa (Chrome DevTools Protocol, viết tắt CDP). AdsPower khởi động SunBrowser (nhân Chromium) và trình duyệt này expose CDP theo cơ chế chuẩn của Chromium, nên Playwright gắn vào được bằng đúng phương thức này.

Điều kiện cần trước khi bắt đầu

• Tài khoản AdsPower ở bậc Professional trở lên.
• Ứng dụng AdsPower đang mở và đăng nhập trên máy chạy script.
• Đã cài Playwright (npm install playwright cho Node.js, hoặc pip install playwright cho Python — bài này minh hoạ bằng Node.js).
• Hồ sơ dùng nhân SunBrowser (Chromium).

Luồng kết nối tổng quát

Bước 1: Gọi Local API để mở hồ sơ

Gọi endpoint mở hồ sơ theo tài liệu Postman chính hãng (documenter.getpostman.com/view/45822952/2sB34hEzQH). Phản hồi trả về địa chỉ CDP của trình duyệt vừa khởi động:

// Thay URL bên dưới bằng đúng endpoint mở hồ sơ trong tài liệu chính hãng.
const res = await fetch(
  "http://<local-api-host>:<port>/<endpoint-mo-ho-so-theo-tai-lieu>?profile_id=ID_HO_SO_CAN_MO"
);
const data = await res.json();

// Tên trường thật lấy theo tài liệu Postman — đây là biến giữ chỗ minh hoạ.
const cdpEndpoint = data.giu_cho_dia_chi_cdp; // ví dụ dạng "http://127.0.0.1:9222"

Bước 2: Gắn Playwright vào trình duyệt đang chạy

const { chromium } = require("playwright");

const browser = await chromium.connectOverCDP(cdpEndpoint);

// Trình duyệt AdsPower đang chạy sẽ có sẵn ít nhất một context và một trang
const context = browser.contexts()[0];
const page = context.pages()[0] ?? (await context.newPage());

await page.goto("https://example.com");
console.log(await page.title());

Bước 3: Thao tác bình thường như mọi script Playwright khác

Sau khi gắn thành công, các API quen thuộc của Playwright (page.click(), page.fill(), page.waitForSelector(), page.locator()…) dùng bình thường, không khác gì khi Playwright tự mở trình duyệt.

Bước 4: Ngắt kết nối đúng cách

Dùng browser.close() cần cẩn trọng — với kết nối qua connectOverCDP(), hành vi đóng trình duyệt phụ thuộc vào cách bạn kết nối; nên kiểm tra kỹ trong tài liệu Playwright phiên bản đang dùng xem close() có đóng luôn tiến trình trình duyệt gốc hay chỉ ngắt kết nối. Cách an toàn nhất là để AdsPower chủ động đóng hồ sơ qua Local API sau khi script hoàn tất, thay vì để Playwright tự đóng trình duyệt.

Vì sao nhóm đọc kỹ thuật hay chọn Playwright hơn cho việc này?

Khi cần chạy song song hàng chục hồ sơ AdsPower cùng lúc, việc quản lý nhiều kết nối bất đồng bộ rõ ràng (async/await nhất quán, Promise.all để chạy song song) là điểm mạnh tự nhiên của Playwright so với API dựa trên callback cũ hơn. Đây là ưu điểm chung của framework, không phải điểm mạnh riêng cho AdsPower — nhưng nó có ý nghĩa thực tế khi bạn viết script điều khiển nhiều hồ sơ đồng thời và cần xử lý lỗi từng luồng độc lập mà không làm sập toàn bộ tiến trình.

Những lỗi thường gặp

• Gọi connectOverCDP() với địa chỉ sai hoặc chưa mở hồ sơ trước: Local API phải trả về kết quả thành công ở bước 1 thì địa chỉ CDP mới hợp lệ để kết nối.
• Nhầm lẫn giữa context có sẵn và tạo context mới: khi gắn vào trình duyệt đã chạy, nên lấy context có sẵn (browser.contexts()[0]) thay vì gọi browser.newContext() — tạo context mới có thể không mang theo đúng cấu hình dấu vân tay và cookie của hồ sơ.
• Chạy nhiều script mở nhiều hồ sơ cùng lúc mà không giãn cách lệnh gọi API: dễ chạm giới hạn tốc độ gọi. Xem cách xử lý tại bài xử lý khi chạm trần giới hạn tốc độ gọi API.

So với Selenium và Puppeteer

Cả ba framework đều dùng chung nguyên lý gắn vào địa chỉ gỡ lỗi lấy từ Local API, chỉ khác cú pháp gọi. Xem bài kết nối Selenium Python với AdsPower nếu quen Python hơn, hoặc kết nối Puppeteer Node.js với AdsPower nếu chỉ cần thao tác đơn giản hơn trên Node.js.

Tài liệu tham khảo chính xác

Tên endpoint, tham số truyền vào và cấu trúc JSON phản hồi thật của Local API nằm trong tài liệu Postman chính hãng tại documenter.getpostman.com/view/45822952/2sB34hEzQH. Tìm hiểu khái niệm nền tảng tại bài API cục bộ AdsPower là gì, và bậc giá cần có tại trang AdsPower.