Cocos2 게임에 플랫폼 ZIP 연결하기

이 문서는 SDK 0.3.0의 Cocos2 Web 플랫폼 연결 절차를 설명합니다. 게임 개발자는 게임 내 액션과 보상 요청을 연결하고, 플랫폼 담당자는 웹 문서에 H5와 CSS를 설치하여 광고 환경을 관리합니다. Cocos3 게임의 경우 Cocos3 ZIP 안내를 확인합니다.

설치 전에 엔진 버전과 SDK 지원 범위를 확인합니다.

1. Cocos2 설치 파일 받기

프로젝트의 Creator 버전이 필수 엔진 버전의 Cocos2 Web 조건과 정확히 일치하는지 확인하고, Cocos2 에디터 ZIP을 받습니다. 플랫폼 담당자에게 같은 SDK 버전의 호스트 ZIP을 전달합니다. 라이선스도 프로젝트의 라이선스 기록과 함께 보관합니다.

플랫폼 담당자는 H5 호스트 안내에 따라 H5·CSS와 광고 설정·동의를 준비합니다. 플랫폼과 게임은 같은 SDK 버전을 사용하며, H5·CSS가 게임이 실행되는 같은 문서에 있어야 합니다.

2. 에디터에서 처음 가져오기

1. 프로젝트를 백업합니다. 기존 EasterAd 연동이 있다면 아래 업데이트 절차부터 확인합니다.
2. File → Import Asset → Find ZIP에서 에디터 ZIP을 선택합니다.
3. Import at ASSETS ROOT → Yes로 가져옵니다. 결과는 assets/EasterAd입니다. 별도의 EasterAd 하위 폴더를 선택하지 않습니다.
4. 장면의 노드 하나에 제공된 EasterAdActions 컴포넌트를 붙입니다. 컴포넌트의 시작 처리가 플랫폼 연결과 ready()를 수행합니다.

게임 입력에서 컴포넌트의 action(name, options) 또는 requestReward(name, options)를 직접 호출합니다. 보상은 requestReward()가 반환한 Promise에서 완료와 reward: 'granted'를 모두 확인한 경우에만 지급합니다. 광고 단위와 사용자 동의는 플랫폼 담당자가 H5 호스트에서 관리합니다.

3. 기존 SDK 파일 업데이트하기

같은 이름·클래스의 에디터 ZIP을 다시 가져오면 스크립트가 갱신되지 않을 수 있으므로, 업데이트할 때는 아래 절차로 SDK 파일을 교체합니다.

1. Creator를 닫고 프로젝트를 백업합니다. 같은 SDK 버전의 Cocos2 업데이트 ZIP을 프로젝트 밖에 풉니다.
2. ZIP의 assets/EasterAd에 해당하는 파일만 기존 SDK 위치에 복사합니다. 제공된 .meta 파일, 기존 폴더와 선언 파일의 메타데이터를 보존하고, 게임 파일·장면·다른 자산은 유지합니다. ZIP 전체를 프로젝트에 풀지 않습니다.
3. Creator를 다시 열고 Plugin Script의 Web 전용 설정과 장면·컴포넌트 참조를 확인합니다. 첫 가져오기에서 경로·UUID를 변경했거나 SDK 파일을 수정했다면 참조를 확인하며 이관합니다.

기존 Web/root 어댑터·bootstrap·게임 내 H5 사본이 있다면 해당 연동을 명시적으로 정리해 어댑터가 중복 실행되지 않게 합니다. 서로 다른 과거 버전 사이의 이관은 프로젝트별 참조 확인이 필요합니다.

4. 연결 제거하기

1. Cocos Creator에서 게임 실행을 종료합니다.
2. 장면의 EasterAdActions 컴포넌트와 버튼 이벤트 참조를 해제합니다.
3. 프로젝트에서 assets/EasterAd SDK 전용 파일을 삭제합니다. 플랫폼의 H5·CSS는 플랫폼 담당자가 별도로 제거합니다.

수동으로 연결하기

컴포넌트 대신 직접 연결하는 경우 수동 초기화 API를 사용합니다.