설치와 프로젝트 설정

EasterAd Cocos SDK(@easterad/h5-cocos2-adapter)는 Cocos Creator 웹 빌드 환경에서 전면 및 보상형 광고를 표시할 수 있도록 지원하는 브리지 패키지입니다. 기본 배포 패키지는 Cocos Creator 2.4.15의 Web Desktop 및 Web Mobile 빌드에 최적화되어 있습니다.

참고

설치형 네이티브 모바일 앱(Android/iOS), 메신저 인앱 게임(텔레그램, 라인 등), 또는 다른 엔진 버전으로의 도입이 필요한 경우 지원 매트릭스를 참고하거나 EasterAd 담당자에게 문의해 주세요.

---

1. 전체 설치 워크플로우

설치는 패키지 설치부터 빌드 검증까지 4단계로 진행됩니다.

flowchart LR
    A["1. 비공개 npm 설치"] --> B["2. 부트스트랩 스크립트 임포트"]
    B --> C["3. CSS & 빌드 템플릿 적용"]
    C --> D["4. doctor CLI 무결성 검증"]

---

2. 패키지 설치 (Private npm)

@easterad/h5-cocos2-adapter는 비공개(Private) npm 레지스트리 패키지입니다. EasterAd로부터 발급받은 읽기 전용 토큰을 환경 변수로 설정하여 설치합니다.

1) .npmrc 설정

프로젝트 루트의 .npmrc 파일에 다음 내용을 추가합니다.

.npmrc

@easterad:registry=https://registry.npmjs.org/
//registry.npmjs.org/:_authToken=${NPM_READ_TOKEN}

토큰 유출 방지

토큰 값을 .npmrc 파일에 평문으로 하드코딩하여 Git 저장소에 커밋하지 마세요. 반드시 ${NPM_READ_TOKEN}과 같이 환경 변수 형태로 참조해야 합니다.

2) npm 패키지 설치

EasterAd에서 안내받은 정확한 버전으로 설치합니다.

npm install --save-exact @easterad/h5-cocos2-adapter@<안내받은_버전>

---

3. 부트스트랩 스크립트 배치 및 플러그인 설정

어댑터가 Cocos 엔진 초기화보다 먼저 로드되도록 부트스트랩 파일을 프로젝트 에셋으로 복사합니다.

node_modules/@easterad/h5-cocos2-adapter/dist/easterad-cocos2-bootstrap.es5.global.js
  → assets/EasterAd/00-easterad-cocos2-bootstrap.es5.global.js

1. 위 경로의 파일을 assets/EasterAd/ 디렉터리로 복사합니다.
2. Cocos Creator 에디터의 에셋 창에서 복사된 00-easterad-cocos2-bootstrap.es5.global.js 파일을 선택합니다.
3. 인스펙터 창에서 Import as Plugin 체크박스를 활성화합니다.
4. 플랫폼 옵션 중 Load in Web만 체크하고, Load in Native 및 Load in Editor는 반드시 체크 해제합니다.

스크립트 파일 규칙 준수

• 파일명의 00- 접두사는 일반 게임 스크립트보다 먼저 실행되도록 보장하는 필수 네이밍 규칙입니다.
• 파일 내용을 임의로 수정하거나 다시 번들링/압축하지 마세요. 런타임 해시 무결성 검증에 실패하여 실행이 차단됩니다.
• 프로젝트 내에 기존 버전의 EasterAd 스크립트가 남아 있다면 모두 제거하고 새 부트스트랩 스크립트 하나만 남겨두어야 합니다.

---

4. 스타일시트 및 빌드 템플릿 구성

웹 화면 위에 광고 오버레이를 올바르게 표시하기 위해 전용 스타일시트와 빌드 템플릿을 설정합니다.

1) CSS 파일 복사

두 웹 빌드 템플릿 디렉터리에 easterad-h5.css를 각각 복사합니다.

build-templates/web-desktop/easterad-h5.css
build-templates/web-mobile/easterad-h5.css

2) 빌드 템플릿 적용

• 신규 프로젝트의 경우: 패키지에 포함된 완성형 템플릿을 그대로 복사하여 사용합니다.

  node_modules/@easterad/h5-cocos2-adapter/cocos2-template/web-desktop/index.html → build-templates/web-desktop/index.html
  node_modules/@easterad/h5-cocos2-adapter/cocos2-template/web-mobile/index.html  → build-templates/web-mobile/index.html

• 기존 커스텀 템플릿이 있는 경우: 패키지에 동봉된 index.html.patch를 참고하여 병합하세요. CSS 링크 1회 추가 및 엔진 부팅 시 캔버스 tabindex 덮어쓰기 방지 코드가 포함되어 있습니다.

스타일시트 누락 시 광고 표시 즉시 차단

웹 빌드 산출물에 easterad-h5.css가 누락되거나 내용이 훼손되면, 스타일이 깨진 채로 광고가 나가는 대신 show() 호출이 즉시 차단되며 PRESENTATION_SURFACE_UNAVAILABLE 오류가 반환됩니다. (Cocos의 MD5 Cache 옵션 사용 시 easterad-h5.<해시>.css 형태도 정상 인식됩니다.)

---

5. Doctor CLI 도구로 설치 무결성 점검

설치와 빌드가 올바르게 완료되었는지 검증하기 위해 CLI 진단 도구를 제공합니다. (Node.js 18 이상 필요)

# 빌드 산출물 검증 실행 (읽기 전용 점검)
npm exec -- easterad-cocos doctor --project . --export build/web-desktop --export build/web-mobile

• 성공 시: 종료 코드 0을 반환하며 모든 검증 항목이 통과됩니다.
• 점검 항목: 부트스트랩 스크립트 누락/중복 여부, 플러그인 설정 적합성, CSS 배치 상태, 이전 레거시 버전 잔여물 유무 등을 종합 진단합니다.
• 지원 요청용 리포트 생성: 기술 지원 요청 시 --format json --out doctor-report.json 플래그를 추가하여 점검 결과를 파일로 추출해 전달할 수 있습니다.

---

다음 단계

• 초기화와 광고 표시: SDK 초기화 파라미터 설정, 전면/보상형 광고 사전 로드 및 보상 판정 로직을 구현합니다.