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

이 문서는 SDK 0.3.0에서 Cocos3 Web 플랫폼을 연결하는 방법을 설명합니다. 플랫폼이 H5·광고 설정을 준비하고 게임은 액션만 보냅니다.

플랫폼 담당자는 게임과 같은 웹 문서에 H5를 설치하고 운영하는 역할입니다. 게임사가 직접 게임을 호스팅한다면 같은 팀에서 이 역할을 맡습니다.

설치 전에 필수 Creator 버전과 SDK 지원 범위를 확인합니다.

1. Cocos3 설치 파일 받기

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

플랫폼 담당자는 H5 호스트 안내에 따라 광고 설정·동의와 H5·CSS를 게임이 실행되는 같은 문서에 준비합니다. 게임과 플랫폼 파일은 같은 SDK 버전으로 맞춥니다.

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

1. 프로젝트를 백업합니다. 기존 연동이 있으면 아래 업데이트 절차부터 확인합니다.
2. Assets의 컨텍스트 메뉴에서 Import Asset Package를 열고 에디터 ZIP을 선택합니다. 내용을 확인한 뒤 Import / Confirm으로 가져옵니다. 설치 위치는 assets/EasterAd입니다.
3. 장면의 노드 하나에 제공된 EasterAdActions.ts의 EasterAdPlatformActions 컴포넌트를 붙입니다. 컴포넌트의 시작 처리가 플랫폼 연결과 ready()를 수행합니다.

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

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

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

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

기존 어댑터·bootstrap·게임 내 H5 사본은 해당 연동을 명시적으로 정리해 중복 실행을 막습니다. 과거 버전 사이의 이관은 프로젝트별 확인이 필요합니다.

4. 연결 제거하기

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

수동으로 연결하기

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