브라우저 자동화 워크플로에 CaptchaSonic을 연동하면 수동 개입 없이 복잡한 CAPTCHA 챌린지를 통과할 수 있습니다. 이 가이드는 자동화 환경에서 CaptchaSonic 확장 프로그램의 설치, 설정, 사용법을 다룹니다.

> [!TIP]
> **권장 방식**: 대규모 자동화에는 API를 직접 사용하는 것을 권장합니다. 다만 실제 브라우저 환경이 필요한 Selenium, Puppeteer, Playwright 같은 도구에는 브라우저 확장 프로그램이 적합합니다.

---

## 1. 시작하기

자동화 스크립트에서 확장 프로그램을 사용하려면 CaptchaSonic 대시보드에서 발급받은 유효한 API 키가 필요합니다.

1.  **계정 만들기**: [captchasonic.com](https://captchasonic.com)에서 가입합니다.
2.  **API 키 발급받기**: [대시보드](https://captchasonic.com/app)에 로그인하여 고유한 API 키를 복사합니다.

![CaptchaSonic 대시보드 출력](/guides/CR/guide.7.png)

---

## 2. 설치 및 설정

### Chrome/Chromium 기반 브라우저

영구 브라우저 프로필을 사용하지 않는 경우, 자동화 프레임워크에는 API 키를 "하드코딩"해야 하는 경우가 많습니다.

1.  **소스 다운로드**: [CaptchaSonic 확장 프로그램 저장소](https://github.com/Captcha-Sonic/CaptchaSonic-Extension/releases/latest)를 클론하거나 내려받습니다.
2.  **API 키 설정**:
    *   확장 프로그램 소스의 `config` 폴더로 이동합니다.
    *   기본 설정 파일(보통 `config.json` 또는 유사한 파일)을 엽니다.
    *   API 키를 `apiKey` 필드에 붙여 넣습니다.
3.  **Chrome에 로드하기**:
    *   `chrome://extensions/`를 엽니다.
    *   **Developer Mode**를 켭니다.
    *   **Load unpacked**를 클릭하고 수정한 확장 프로그램 폴더를 선택합니다.

> [!IMPORTANT]
> 자동화 프레임워크가 압축 해제된 확장 프로그램 로드를 허용하도록 설정되어 있는지 확인하세요. Selenium에서는 `ChromeOptions`로 설정합니다.

### Firefox

1.  **XPI 다운로드**: [Firefox Add-ons 스토어](https://addons.mozilla.org/en-US/firefox/addon/captchasonic/)에서 설치하거나, [CaptchaSonic 확장 프로그램 릴리스](https://github.com/Captcha-Sonic/CaptchaSonic-Extension/releases/latest)에서 최신 빌드를 받으세요.
2.  **수동 설치**: `about:addons`로 이동해 톱니바퀴 아이콘을 클릭하고 **Install Add-on From File**을 선택합니다.

---

## 3. 자동화 프레임워크 연동

코드에서 확장 프로그램을 사용하려면 확장 프로그램 폴더 또는 파일의 경로를 지정해야 합니다.

### Selenium (Python)

```python
from selenium import webdriver
from selenium.webdriver.chrome.options import Options

chrome_options = Options()
chrome_options.add_argument("--load-extension=/path/to/extracted/extension")

driver = webdriver.Chrome(options=chrome_options)
driver.get("https://web.captcha-target.com")
```

### Playwright (Node.js)

```javascript
const { chromium } = require('playwright');

(async () => {
  const pathToExtension = require('path').join(__dirname, 'my-extension');
  const userDataDir = '/tmp/test-user-data-dir';
  const browserContext = await chromium.launchPersistentContext(userDataDir, {
    headless: false,
    args: [
      `--disable-extensions-except=${pathToExtension}`,
      `--load-extension=${pathToExtension}`,
    ],
  });
  // ... your automation logic
})();
```

---

## 4. 파라미터 설정

확장 프로그램 팝업 또는 설정 파일에서 CAPTCHA 처리 방식을 세부적으로 조정할 수 있습니다:

*   **Auto-Solve**: CAPTCHA가 감지되면 풀이 프로세스를 자동으로 시작합니다.
*   **Solve Delay**: 풀이 전에 자연스러운 지연 시간을 추가해 사람의 행동을 모방합니다.
*   **Target Types**: reCAPTCHA, hCaptcha, GeeTest 등 특정 솔버를 켜거나 끕니다.

---

## 5. 배포 시 고려 사항

*   **Headless Mode**: 일반 확장 프로그램은 "진정한 헤드리스" 모드(`--headless=new`)에서 동작하지 않습니다. Linux 서버에서는 `--headless=old` 또는 가상 프레임버퍼(Xvfb)를 사용하세요.
*   **Proxy Support**: 대부분의 확장 프로그램은 자동화 프레임워크에서 설정한 브라우저 시스템 프록시 설정을 따릅니다.

---

## 6. 마무리

CaptchaSonic 확장 프로그램을 연동하면 브라우저 자동화 작업에서 인터랙티브 챌린지를 처리하는 복잡도를 크게 줄일 수 있습니다.

추가 기술 지원이나 맞춤 연동 요청은 [대시보드](https://captchasonic.com/app)를 통해 팀에 문의하세요.
