초기화와 광고 표시

Cocos Creator 웹 게임 환경에서는 전역 객체 window.EasterAdCocos2를 통해 SDK를 초기화하고, 전면(Interstitial) 및 보상형(Rewarded) 광고 단위를 생성하여 제어합니다. 플레이어의 게임 흐름을 방해하지 않고 안정적으로 광고를 서빙하기 위해서는 사전 로드(Preload) 패턴과 엄격한 보상 판정 규칙을 준수해야 합니다.

---

1. SDK 초기화 및 자원 해제

게임 진입 시점이나 메인 씬 로드 시 SDK 인스턴스를 생성합니다.

var sdk = window.EasterAdCocos2.initialize({
    baseUrl: 'https://<EasterAd_서빙_오리진>', // 경로/쿼리 없는 HTTP(S) 도메인 오리진
    appId: '<24자리_16진수_앱_ID>',
    // sdkKey: '<라이브_SDK_키>',    // 테스트 시 속성 자체를 생략 (빈 문자열 금지)
    session: {},                    // 기기/브라우저 환경 정보 자동 수집
    styles: { mode: 'external' }    // 빌드 템플릿의 easterad-h5.css 스타일시트 사용
});

• 테스트 vs 라이브 세션: sdkKey 프로퍼티를 아예 전달하지 않으면 자동으로 테스트 세션으로 동작합니다. 게임의 H5 플랫폼 심사가 승인된 이후에만 라이브 키를 입력하세요.
• 캔버스 자동 바인딩: 광고 오버레이는 cc.game.canvas 크기와 위치에 맞춰 자동으로 정렬 및 렌더링됩니다.
• 자원 정리 (sdk.destroy()): 씬 전환 시 메모리와 웹 리소스를 회수하기 위해 await sdk.destroy()를 호출합니다. 영속 노드(cc.game.addPersistRootNode)를 통해 전역 싱글톤으로 관리하는 경우에는 게임 종료 시점에 단 1회 호출하세요.

---

2. 지원 광고 상품 규격

용도에 따라 적절한 팩토리 메서드와 미디어 수용 능력(mediaCapabilities)을 지정합니다.

광고 상품	생성 팩토리 메서드	mediaCapabilities 설정	비고
HTML 전면 광고	createInterstitialAdUnit	[{ banner: {} }]	HTML5 반응형 웹 배너
VAST 동영상 전면	createInterstitialAdUnit	[{ video: { mimes: ['video/mp4'] } }]	전체화면 비디오 전면 광고
혼합 전면 광고	createInterstitialAdUnit	[{ banner: {} }, { video: { mimes: ['video/mp4'] } }]	배너와 비디오 중 입찰 경쟁
VAST 동영상 보상형	createRewardedAdUnit	[{ video: { mimes: ['video/mp4'] } }]	시청 완료 시 인게임 보상 지급

팁

비디오 소재를 요청하기 전, 실행 중인 브라우저가 MP4를 재생할 수 있는지 document.createElement('video').canPlayType('video/mp4')가 'maybe' 또는 'probably'인지 사전에 확인하는 것이 좋습니다.

---

3. 광고 로드와 표시 모범 사례 (사전 로드 패턴)

웹 브라우저의 오토플레이 정책과 사용자 인터랙션 타이밍을 지키기 위해, 광고 기회가 오기 전에 미리 로드(Preload)해 두고 클릭 시점에 즉시 표시하는 흐름을 권장합니다.

sequenceDiagram
    autonumber
    participant Scene as 게임 씬 (로비/스테이지)
    participant SDK as EasterAd Cocos Unit
    participant Server as EasterAd 서빙 서버
    participant User as 플레이어 (클릭)

    Scene->>SDK: 1. 미리 load() 호출 (비동기)
    SDK->>Server: 광고 소재 요청
    Server-->>SDK: 소재 다운로드 완료 ({ outcome: 'loaded' })
    Note over SDK: isReady() === true 상태 유지

    User->>Scene: 2. "광고 보고 부활하기" 버튼 탭
    Scene->>SDK: isReady() 확인 후 show() 호출
    SDK-->>User: 전체화면 광고 재생
    User-->>SDK: 시청 완료 및 닫기
    SDK-->>Scene: { outcome: 'completed', reward: 'granted' } 반환
    Scene->>Scene: 인게임 아이템/부활 보상 지급

구현 코드 예시

// 1. 광고 단위 객체 생성 (씬 초기화 시 1회 생성 권장)
var rewardedAd = sdk.createRewardedAdUnit({
    adUnitId: config.rewardedAdUnitId,
    mediaCapabilities: [{ video: { mimes: ['video/mp4'] } }],
    reloadMode: 'after_presentation' // 광고 표시가 끝나면 백그라운드에서 다음 광고 자동 로드
});

// 2. 사전에 미리 비동기 로드 시작
rewardedAd.load().catch(function (err) {
    console.warn('[EasterAd] 로드 실패:', err.code);
});

// 3. 사용자 액션 핸들러 (버튼 클릭 이벤트 등)
async function onRewardButtonClicked() {
    // 준비 상태 확인
    if (!rewardedAd.isReady()) {
        ui.showToast('광고를 준비 중입니다. 잠시 후 다시 시도해 주세요.');
        // 필요 시 백그라운드 로드 재시도
        rewardedAd.load().catch(() => {});
        return;
    }

    try {
        // 브라우저 팝업/제스처 조건을 유지하기 위해 클릭 즉시 show() 호출
        var result = await rewardedAd.show();

        // 4. 엄격한 보상 지급 검증
        if (result.outcome === 'completed' && result.reward === 'granted') {
            grantGameReward(result.rewardGrantId);
        } else {
            console.log('보상 미충족 또는 중도 닫힘:', result.outcome);
        }
    } catch (err) {
        handleAdError(err.code);
    }
}

---

4. 핵심 운영 및 보상 판정 규칙

안정적인 게임 서비스와 부정 수급 방지를 위해 아래 규칙을 엄격히 적용해야 합니다.

1) 보상 지급 판정의 필수 조건

보상은 반드시 result.outcome === 'completed'와 result.reward === 'granted' 두 조건이 동시에 충족될 때만 지급해야 합니다.

• 플레이어가 중간에 건너뛰거나 창을 닫은 경우(outcome === 'dismissed'), 또는 비디오 재생 오류가 발생한 경우에는 보상을 지급해서는 안 됩니다.
• result.rewardGrantId는 서버가 발급한 일회성 세션 식별자입니다. 중복 지급 사고를 방지하려면 게임 자체의 고유 트랜잭션 ID를 기준으로 수령 여부를 멱등하게 관리하세요.

2) NoFill (HTTP 204) 정상 응답 처리

• 광고 요청 결과가 { outcome: 'no_fill' }인 것은 오류가 아니라 “현재 송출 가능한 광고가 없다”는 정상적인 비즈니스 응답입니다.
• NoFill 수신 시 타이머를 돌려 짧은 주기로 반복 재요청하지 마세요. 다음 게임 라운드가 시작되거나 적절한 시점에 1회 다시 요청해야 합니다.

3) 사용자 제스처 컨텍스트 유지

• show() 메서드는 반드시 버튼 클릭(touch-end, click) 등 사용자 인터랙션 이벤트 핸들러 동기 범위 내에서 직접 호출되어야 브라우저의 오디오/비디오 자동 재생 차단 정책을 우회할 수 있습니다.

---

5. 이벤트 리스너와 에러 코드 카탈로그

광고 단위 객체는 on(eventName, listener) 메서드로 생명주기 이벤트를 구독할 수 있으며, 구독 해제 함수(Unsubscribe)를 반환합니다.

• 지원 이벤트 목록: state, loaded, noFill, started, completed, dismissed, creativeClick, error

주요 오류 코드 대응 가이드

에러 처리 시 메시지 문자열이 아닌 err.code 값으로만 분기하세요.

에러 코드 (code)	원인 및 권장 대응 방안
PRESENTATION_SURFACE_UNAVAILABLE	easterad-h5.css가 누락되었거나 게임 캔버스 DOM에 접근할 수 없습니다. 빌드 템플릿과 CSS 배치를 확인하세요.
AD_NOT_READY	광고 로드가 완료되기 전에 show()를 호출했습니다. 반드시 isReady()를 먼저 확인하세요.
PRESENTATION_BUSY	이미 다른 광고가 화면에 표시 중입니다. 이전 광고가 닫힌 후 호출하세요.
PLAYBACK_FAILED	비디오 코덱 미지원 또는 브라우저 미디어 재생 정책에 의해 재생이 차단되었습니다.
PLATFORM_UNSUPPORTED	미지원 브라우저이거나 비정상적인 실행 환경입니다.

---

6. 기술 지원용 데이터 수집 (createSupportCollector)

연동 과정에서 원인 파악이 어려운 이슈가 발생하면 안전한 진단 데이터 수집기를 활용하여 EasterAd 기술팀에 문의할 수 있습니다.

// 민감 정보가 마스킹된 이벤트 스트림 수집기 생성
var collector = window.EasterAdCocos2.createSupportCollector({ maxEvents: 100 });

var sdk = window.EasterAdCocos2.initialize({
    ...options,
    diagnostics: collector.diagnostics
});

// 오류 발생 시 스냅샷 추출 (JSON 형태)
function exportErrorReport() {
    var report = JSON.stringify(collector.snapshot());
    console.log('[EasterAd Error Dump]', report);
    // 기술 지원 문의 시 해당 JSON을 첨부
}

---

다음 단계

• SDK 플랫폼 지원 매트릭스: 지원 엔진 및 타깃 플랫폼별 기능 비교를 확인합니다.
• 광고 소재 요건: HTML5 배너 및 동영상 파일 규격을 점검합니다.