플랫폼 H5 호스트 설치와 설정

Cocos 게임을 호스팅하는 플랫폼 담당자가 수행하는 절차입니다. 게임 개발자는 엔진별 설치·연결 안내를 따릅니다.

1. 같은 릴리스 자산 설치하기

호스트 설정 ZIP을 작업 디렉터리에 풉니다.
host/INSTALL.txt에 따라 host/와 cdn/의 상대 배치를 유지합니다. H5·CSS·게임 플러그인은 모두 SDK 0.3.0을 사용합니다.
게임이 실행되는 동일한 웹 문서에 아래 H5와 CSS를 게임보다 먼저 로드합니다. iframe에서 게임을 실행하면 iframe 문서에 설치합니다.

<link rel="stylesheet" href="https://www.easterad.com/assets/easterad/0.3.0/0.3.0-platform-8fff3b6a9275ab67/easterad-h5.css" integrity="sha256-vIvNY5IPLaAo7rdqEnZJt1IJRHfPLXa0dTN/F1hbrfE=" crossorigin="anonymous">
<script src="https://www.easterad.com/assets/easterad/0.3.0/0.3.0-platform-8fff3b6a9275ab67/easterad-h5.umd.es5.global.js" integrity="sha256-fe03zpcVjLypDPZt/50/v4OxXQ4rZB8549ZgO0qJP5w=" crossorigin="anonymous"></script>

호스트 ZIP에 포함된 파일과 타입 선언을 사용합니다.

2. 플랫폼 설정과 동의 준비하기

콘솔에서 게임 ID와 광고 단위 ID를 확인합니다.
연동 문의로 게임 ID·Creator 버전·게임 실행 주소를 전달하고 광고 API 기본 주소인 baseUrl을 받습니다.
동의 문서를 고지하고 이용자의 선택을 보관합니다. 문서 조회용 서버 API 키는 퍼블리셔 서버에 보관합니다.
동의·회원 정보를 준비합니다.

3. 광고 지면 설정을 한 번 제공하기

아래 startHost 함수를 작성하고 게임 이벤트와 광고 단위를 연결합니다.

export function startHost(
  options: Omit<Parameters<typeof window.EasterAdH5.initializePlatform>[0], 'inventoryProvider'>,
  adUnits: { loading: string; normal: string; revive: string }
) {
  return window.EasterAdH5.initializePlatform({
    ...options,
    maxPreparedAds: 2, preloadTtlMs: 120000, loadingTimeoutMs: 30000,
    inventoryProvider: async ({ signal }) => {
      signal.throwIfAborted();
      return {
        inventories: {
          startup: { product: 'interstitial', adUnitId: adUnits.loading, mediaCapabilities: [{ video: { mimes: ['video/mp4'] } }] },
          between_levels: { product: 'interstitial', adUnitId: adUnits.normal, mediaCapabilities: [{ video: { mimes: ['video/mp4'] } }] },
          second_chance: { product: 'rewarded', adUnitId: adUnits.revive, mediaCapabilities: [{ video: { mimes: ['video/mp4'] } }] }
        },
        loading: 'startup', warmOnReady: ['second_chance'],
        events: { level_started: { prepare: 'between_levels' }, level_completed: { present: 'between_levels' } },
        rewards: { revive: 'second_chance' }
      };
    }
  });
}

게임 문서에 <div id="ad-loading"></div>를 준비하고 아래처럼 호출합니다. 주소와 ID는 실제 값으로 바꿉니다. 예제는 SDK 키를 생략한 테스트 연결이며 동의를 받기 전의 빈 동의 목록을 사용합니다.

const host = startHost({
  baseUrl: 'https://<EasterAd_광고_API_주소>',
  appId: '0123456789abcdef01234567',
  mount: document.getElementById('ad-loading')!,
  session: {},
  publisherContext: { consent: { grants: [] } }
}, {
  loading: '000000000000000000000002',
  normal: '000000000000000000000005',
  revive: '000000000000000000000006'
});

startHost(...) 반환값을 host로 보관합니다. 입력 항목을 아래 기준으로 확인합니다.

항목	입력·확인 방법
`baseUrl`	연동 문의로 받은 광고 API 기본 주소를 입력합니다.
`appId` / `adUnits`	콘솔의 게임 ID와 해당 게임에서 만든 광고 단위 ID를 입력합니다.
`mount`	호스트 로딩 요소를 전달합니다.
`session`	별도 설정이 없어도 `{}`를 전달합니다.
`publisherContext`	이용자의 실제 동의와 고지·동의받은 회원 정보를 전달합니다.
`sdkKey`	테스트에서는 생략합니다. 라이브 전환 시 H5 심사 승인과 해당 게임의 유효한 키를 모두 확인하고 `initializePlatform` 최상위 옵션에 입력합니다.
`inventoryProvider`	필요한 지면과 액션 연결 설정을 반환합니다. 아래 항목을 사용합니다.

광고 설정	용도
`inventories`	사용할 지면을 정의합니다.
`loading`	게임 시작 전 로딩 단계에 표시할 지면을 지정합니다.
`warmOnReady`	게임 준비 완료 후 미리 로드할 지면을 지정합니다.
`events`	일반 액션의 `prepare`·`present`와 지면을 연결합니다.
`rewards`	보상 요청 이름과 지면을 연결합니다. 예제에서 게임은 `revive`를 요청합니다.
`mediaCapabilities`	호스트에서 재생할 수 있는 형식을 전달합니다. 동영상의 `video.mimes`에는 `video/mp4`를 포함해야 합니다.

예제의 준비 광고 2개, 보관 시간 120초, 시작 대기 30초는 설정 예시이므로, 게임의 장면 전환 속도와 로딩 시간을 고려해 조정합니다.

4. 로딩 단계 뒤 게임 시작하기

await host.startReady가 완료되면 게임 플레이를 시작합니다. 광고가 없거나 설정 실패, 재생 실패, 로딩 시간 초과가 발생하더라도 게임을 계속 진행합니다. 광고별 준비 여부와 영상 재생 완료 여부는 각 요청 결과로 확인합니다.
시작 도우미를 선택했다면 아래 방식으로 게임 시작을 연결합니다.

시작 도우미	사용 방법
`startPlatform(options, launchGame)`	`launchGame`에 게임 시작 함수를 전달합니다.
`startHostedGame(options, resolveInventory, launchGame)`	1회 실행할 지면 조회 함수를 `resolveInventory`로, 게임 시작 함수를 `launchGame`으로 전달합니다.

두 도우미를 사용할 때는 반환값의 controller를 이 안내의 host로 사용하고, 게임 시작 결과는 gameStarted로 확인합니다. 게임은 도우미에 전달한 launchGame 한 곳에서만 시작합니다.

호스트를 교체하거나 종료하려면 게임 연결을 먼저 종료하고 await host.destroy()가 완료되기를 기다립니다.

5. 장시간 플레이 중 세션 만료에 대응하기

action()·requestReward() 결과의 reason 또는 호스트 getStatus().lastReason이 session_unavailable이면 광고 없이 게임을 계속 진행합니다. 다음 게임 실행 전에 아래 순서로 다시 연결합니다.

게임 개발자는 진행 중인 보상 요청의 결과를 처리하고, 직접 연결은 await actions.destroy(), ZIP 컴포넌트는 await component.shutdown()으로 정리를 완료합니다.
플랫폼 담당자는 게임 연결을 정리한 후 await host.destroy()가 완료되기를 기다립니다.
플랫폼 담당자는 이용자의 동의·회원 정보와 테스트 또는 라이브 키 설정으로 새 호스트를 초기화합니다.
게임 개발자는 새 연결이나 새 컴포넌트로 다음 게임을 시작합니다. 요청과 콜백도 새 연결에 맞게 준비합니다.

정리가 실패하면 광고 없이 게임을 계속 진행합니다. 새 호스트는 기존 연결 정리가 완료된 뒤에 생성합니다.