ブラウザ自動化のワークフローに 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` など）を開きます。
    *   `apiKey` フィールドに API キーを貼り付けます。
3.  **Chrome に読み込む**:
    *   `chrome://extensions/` を開きます。
    *   **デベロッパーモード** を有効にします。
    *   **Load unpacked** をクリックし、変更した拡張機能のフォルダを選択します。

> [!IMPORTANT]
> 自動化フレームワークが、パッケージ化されていない拡張機能の読み込みを許可するように設定されていることを確認してください。Selenium では `ChromeOptions` で設定します。

### Firefox の場合

1.  **XPI をダウンロードする**: [Firefox アドオンストア](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=new`）では動作しません。Linux のサーバーでは `--headless=old` または仮想フレームバッファ（Xvfb）を使ってください。
*   **プロキシのサポート**: ほとんどの拡張機能は、自動化フレームワークで設定したブラウザのシステムプロキシ設定に従います。

---

## 6. まとめ

CaptchaSonic 拡張機能を組み込むと、ブラウザ自動化のタスクで対話型チャレンジを処理する複雑さを大幅に減らせます。

技術サポートやカスタムの連携について相談したい場合は、[ダッシュボード](https://captchasonic.com/app) からチームにお問い合わせください。
