설치 및 ApiServer 구성

Mbbrowser의 Playwright 통합은 세 가지 언어를 지원합니다. 팀의 숙련도에 가장 적합한 언어를 선택할 수 있습니다. 각 언어별 설치 단계가 약간 다르므로 해당 섹션을 주의 깊게 읽어주십시오.

---

언어 선택

TIP

• JavaScript (Node.js): Puppeteer와 유사하며 스크립트가 간결합니다. 프론트엔드 개발자에게 권장합니다.
• Python: 데이터 분석이나 웹 스크래핑에 이상적입니다. Mbbrowser가 사용자를 대신해 가상 환경을 관리해 줍니다.
• Java: 기업 프로젝트나 이미 Java 스택을 사용 중인 팀에 적합합니다.

---

1. JavaScript / TypeScript 환경

1. Node.js 설치

Node.js 공식 웹사이트에서 LTS 버전(예: Node.js 20.x)을 다운로드하여 설치합니다.

설치 확인:

node -v   # v20.x.x 이상이 출력되어야 합니다.
npm -v

2. 프로젝트 생성 및 Playwright 설치

# 프로젝트 폴더 생성
mkdir mb-playwright && cd mb-playwright

# npm 프로젝트 초기화
npm init -y

# Playwright 설치 (핵심 라이브러리만 설치. 브라우저는 Mbbrowser를 사용하므로 내장 브라우저 다운로드는 불필요)
npm install playwright

NOTE

설치 중에 Playwright가 브라우저 파일을 다운로드하려고 시도할 수 있습니다. Mbbrowser의 브라우저를 사용할 것이므로 다음 환경 변수를 설정하여 이 단계를 건너뛸 수 있습니다.

set PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1
npm install playwright

3. axios 설치 (Mbbrowser ApiServer 호출용)

npm install axios

---

2. Python 환경

1. Python 설치

Python 공식 웹사이트에서 Python 3.8 이상을 다운로드합니다.

설치 중에 반드시 ✅ Add Python to PATH를 체크하십시오.

2. Mbbrowser Playwright Python 가상환경(Venv)

IMPORTANT

Mbbrowser는 설치 경로의 python\Playwright\ 하위 디렉토리에 Playwright Python을 위한 독립적인 가상 환경을 내장하고 있습니다.

Mbbrowser 클라이언트의 스크립트 관리자 내에서 실행할 때는 Mbbrowser가 이 가상 환경을 자동으로 활성화합니다.

명령줄을 통해 독립적으로 디버깅하려는 경우에는 수동 활성화가 필요합니다.

# Mbbrowser 설치 경로 내의 python 디렉토리로 이동
cd "C:\Program Files (x86)\Mbbrowser_vX.X.X\python"
# 가상 환경 활성화
Playwright\Scripts\activate
# 이제 평소처럼 pip를 사용하거나 playwright 명령을 실행할 수 있습니다.

3. Playwright Python 라이브러리 설치

가상 환경이 활성화된 상태에서 다음을 실행합니다.

pip install playwright requests

NOTE

playwright는 필요한 의존성을 설치하지만, 브라우저 다운로드를 위해 playwright install을 실행할 필요는 없습니다.

---

3. Java 환경

1. JDK 설치

Adoptium에서 JDK 11 또는 17(17 LTS 권장)을 다운로드하여 설치합니다.

2. Mbbrowser Playwright Java 드라이버

IMPORTANT

Mbbrowser는 설치 디렉토리에 Playwright Java를 위한 필요한 JAR 파일들을 함께 제공합니다.

Mbbrowser_설치_경로\
└── lib\
    ├── playwright-1.48.0.jar
    ├── driver-bundle-1.48.0.jar
    └── gson-2.x.jar

Mbbrowser 스크립트 관리자를 통해 Java 스크립트를 실행하면 자동으로 driver-bundle을 추출하고 환경을 구성합니다.

3. Maven / Gradle 의존성

Maven을 사용하는 경우:

<dependency>
  <groupId>com.microsoft.playwright</groupId>
  <artifactId>playwright</artifactId>
  <version>1.50.0</version>
</dependency>

---

4. Mbbrowser ApiServer 활성화 (모든 언어 공통)

IMPORTANT

언어 선택과 관계없이, 스크립트가 Mbbrowser와 통신하려면 먼저 ApiServer를 시작해야 합니다!

앱 인증 정보 획득

1. Mbbrowser 클라이언트를 열고 로그인합니다.
2. 개인 센터 → API 설정으로 이동합니다.
3. 자신의 APP_ID와 APP_KEY를 확인(또는 생성)합니다.

ApiServer 시작

관리자 권한으로 CMD를 열고 Mbbrowser 설치 디렉토리로 이동합니다.

apiserver.exe --port=8186 --app_id=사용자_APP_ID --app_key=사용자_APP_KEY --hide=off

매개변수	설명	권장 값
--port	리스닝 포트	8186 (기본값)
--app_id	인증 ID	개인 센터 정보
--app_key	인증 키	개인 센터 정보
--hide	브라우저 숨김 여부	off (디버깅을 위해 보이는 것이 좋습니다)

성공 시:

ApiServer started at http://127.0.0.1:8186

---

5. 환경 Session_ID 확인

Mbbrowser 메인 패널에서 대상 환경을 찾습니다.

• 마우스 오른쪽 버튼 클릭 → 환경 ID 복사 (Copy Environment ID / Session_ID).
• 형식: 32자리 16진수 문자열 (예: 373808cb37bd63f5f7d92415e736e85f).

---

6. ApiServer 응답 이해 (ws 필드)

/api/v1/browser/start 호출 시 반환되는 데이터 구조는 다음과 같습니다.

{
  "code": 0,
  "message": "success",
  "data": {
    "http": "127.0.0.1:9222",
    "ws": "ws://127.0.0.1:9222/devtools/browser/사용자-브라우저-ID"
  }
}

필드	의미	Playwright에서의 용도
data.http	HTTP 디버깅 주소	주로 Selenium용.
data.ws	WebSocket CDP 주소	Playwright에 필수 ✅

---

7. 설치 체크리스트

다음 장으로 넘어가기 위해 아래 사항을 확인하십시오.

• [ ] 언어 런타임 (JS/Python/Java)이 설치되었는가?
• [ ] playwright 라이브러리가 설치되었는가?
• [ ] ApiServer가 실행 중이며 http://127.0.0.1:8186/에 접속 가능한가?
• [ ] 대상 환경의 Session_ID를 알고 있는가?
• [ ] data.ws가 Playwright에 필요한 WebSocket 주소임을 이해하고 있는가?

---

TIP

준비되셨나요? 다음 장 빠른 시작: 연결하기에서 세 가지 언어 모두를 위한 실행 가능한 전체 스크립트를 제공합니다.