wuling-overseas-dealer-expansion-skill/references/adspower-setup.md

AdsPower Setup

Use this reference when launching, connecting, or troubleshooting browser automation through AdsPower.

Preconditions

1. Install and start AdsPower.
2. Enable the local API. Default base URL: http://127.0.0.1:50325.
3. Create or choose a browser profile for the target platform.
4. Log in to the platform account inside that profile before running collection or outreach.
5. Install Python dependencies in the active environment: playwright, requests, pandas, openpyxl.
6. Install Playwright Chromium once with playwright install chromium.

If automatic translation is needed, install deep-translator. Translation failure should not block collection; scripts should keep the original text.

Playwright Browser Rule

All browser work in this skill must be implemented through Playwright. AdsPower provides the isolated logged-in browser profile and CDP websocket only; Playwright performs page navigation, DOM extraction, locator-based clicking, typing, scrolling, screenshots, and verification. v4.1 hard rule: never close or stop the user's AdsPower browser; only stop the Playwright connection when a script exits.

Do not implement browser actions with screenshot coordinates, OS-level mouse/keyboard automation, extension scripts, or generic “bottom-most input” heuristics. If Playwright cannot reliably locate a Facebook Messenger input, LinkedIn page element, Google Maps detail panel, local auto website listing, or merchant website link, stop and report the blocker instead of falling back to unsafe interaction.

For Facebook website extraction, use Playwright to read a[href], visible link text, aria labels, action buttons, and body text. Bare domains visible in the About/contact area should be parsed as website candidates, while Instagram, WhatsApp, YouTube, TikTok, LinkedIn, Google Maps, and Facebook links must remain excluded from 公司官网.

Browser Pacing Levels

Browser automation uses layered pacing. Major steps wait 90-200 seconds, minor page-level steps wait 30-90 seconds, and technical waits remain short at about 0.5-8 seconds. Major steps include opening a new target page, moving to the next customer, submitting a search, completing Follow, completing DM send, or moving from Facebook to website deep scraping. Minor steps include opening About/Contact/Services pages, scrolling, expanding page sections, opening Messenger, and waiting before Enter. Technical waits are only for Playwright locator readiness, DOM load, popup appearance, and textbox availability.

Pacing is for throttling and reducing accidental rapid-fire operations. It is not anti-detection or platform-evasion behavior. If verification, rate limit, suspicious activity, identity confirmation, or temporary block appears, stop the workflow and keep AdsPower open.

Profile Isolation

Use separate profiles for different platforms or account types:

• Facebook collection profile
• Facebook outreach profile
• LinkedIn profile
• TikTok profile
• Google Maps or browser research profile

Avoid mixing high-volume collection and human outreach in the same profile when possible.

Connection Modes

Mode	Use case	Script
Start or attach to an AdsPower browser	Batch collection where the script may open/connect but must leave the browser running	scripts/scraper/search_facebook.py, scripts/scraper/search_active_dealers.py
Connect to an already-open AdsPower browser	User has manually logged in or wants to keep the browser open	scripts/scraper/control_opened_browser_v2.py

Active Browser Connection

When connecting to an already-open profile:

1. Call AdsPower GET /api/v1/browser/active?user_id=<profile_id>.
2. Read the returned websocket endpoint.
3. Connect Playwright with connect_over_cdp(ws_endpoint).
4. Open a new page in the existing context.
5. Stop Playwright after completion, but never close or stop the user's AdsPower browser.

Example Commands

Start a Facebook search:

python scripts/scraper/search_facebook.py `
  --query "Chery Maroc" `
  --region "Maroc" `
  --profile-id "YOUR_PROFILE_ID" `
  --ads-power-url "http://127.0.0.1:50325" `
  --max-results 10 `
  --output "facebook_scraped.json"

Connect to an already-open profile:

python scripts/scraper/control_opened_browser_v2.py `
  --profile-id "YOUR_PROFILE_ID" `
  --query "Chery Maroc" `
  --stay 60

Troubleshooting

• If AdsPower cannot connect, confirm the local API is enabled and the port is correct.
• If Playwright cannot connect, restart the profile and retry.
• If the account is logged out, log in manually inside AdsPower before automation.
• If Facebook layout changes, prefer deep single-page verification before running a batch.
• If Excel write fails with PermissionError, close the workbook in Excel and rerun the write step.