라이프사이클과 결과 처리

Item.Load()로 광고를 요청하고 상태와 진단 이벤트로 결과를 확인합니다.

1. 광고 상태 확인하기

아래 상태에 따라 광고 표시 여부와 다음 작업을 확인합니다.

stateDiagram-v2
    direction LR
    accTitle: Item 광고 생명주기 상태 전이
    accDescr: None에서 Ready, Loading을 거쳐 Loaded, Impressing, Impressed로 진행합니다. Loading 실패 시 NoFill, Failed, Disabled로 전이됩니다.

    [*] --> None
    None --> Ready: 초기화 완료
    Ready --> Loading: Load() 호출

    Loading --> Loaded: 광고 수신 성공
    Loading --> NoFill: 송출 광고 없음 (정상 응답)
    Loading --> Failed: 네트워크/통신 에러
    Loading --> Disabled: 정책/플랫폼 비활성

    Loaded --> Impressing: 노출 영역 진입
    Impressing --> Impressed: 유효 노출 기준 충족

    Loaded --> Interacting: 사용자 클릭/상호작용
    Interacting --> Interacted: 상호작용 종료

주요 상태 정의 및 특징

상태 (State)	의미와 다음 작업
`None`	지면 초기화 전 상태입니다.
`Ready`	광고를 요청할 수 있습니다.
`Loading`	광고를 불러오는 중입니다.
`Loaded`	광고가 지면에 표시됩니다.
`Impressing`	광고 노출이 진행 중입니다.
`Impressed`	유효 노출이 기록되었습니다.
`NoFill`	표시할 광고가 없는 정상 결과입니다.
`Interacting`	이용자가 광고와 상호작용 중입니다. 종료 시 `EndInteraction()`을 호출합니다.
`Interacted`	광고 상호작용이 완료되었습니다.
`Failed`	네트워크 타임아웃이나 파싱 오류 등 예외가 발생한 상태입니다.
`Disabled`	심사 미승인, 비활성 지면 또는 플랫폼 정책에 따라 요청이 차단된 상태입니다.

2. NoFill 응답 대응 가이드

다음 씬으로 전환하거나 새 게임을 시작할 때 Item.Load()를 다시 호출합니다. NoFill 발생 후 재요청은 게임 코드에서 수행합니다.

3. 진단 이벤트 모니터링 (`AdRequestObserved`)

광고 요청 결과는 EasterAdSdk.Instance.AdRequestObserved 이벤트를 구독하여 확인합니다.

using EasterAd;
using UnityEngine;

public class AdDiagnosticsListener : MonoBehaviour
{
    private bool subscribed;

    void Update()
    {
        if (!subscribed && EasterAdSdk.OnceInitialized)
        {
            EasterAdSdk.Instance.AdRequestObserved += HandleAdRequestObserved;
            subscribed = true;
        }
    }

    void OnDisable()
    {
        if (subscribed && EasterAdSdk.OnceInitialized)
        {
            EasterAdSdk.Instance.AdRequestObserved -= HandleAdRequestObserved;
        }
        subscribed = false;
    }

    private void HandleAdRequestObserved(AdRequestDiagnostics diagnostics)
    {
        // diagnostics.Outcome: Success, NoFill, Failed, Disabled 등
        // diagnostics.AdUnitId: 대상 광고 단위 식별자
        // diagnostics.Error: 에러 발생 시 상세 정보
        Debug.Log($"[EasterAd] 지면 {diagnostics.AdUnitId} 요청 결과: {diagnostics.Outcome}");
    }
}

4. 플레이어 클릭 및 외부 링크 상호작용

광고 클릭 시 외부 브라우저 이동을 지원하려면 다음 절차를 따릅니다.

광고를 로드하기 전에 인스펙터 또는 코드에서 item.interactable = true로 설정합니다.
광고를 클릭하면 item.StartInteraction()으로 목적지 URL을 얻고 게임의 확인 팝업을 표시합니다. 아래 UIManager.ShowConfirmPopup은 게임에서 구현한 팝업으로 바꿉니다. 확인·취소·닫힘 중 한 결과만 전달하도록 연결합니다.

using EasterAd;
using UnityEngine;

public class AdInteractionHandler : MonoBehaviour
{
    public void OnAdObjectClicked(Item item)
    {
        string targetUrl = item.StartInteraction();
        if (string.IsNullOrEmpty(targetUrl)) return;

        // 게임의 확인 팝업으로 교체합니다. 확인·취소·닫힘 중 한 콜백만 호출합니다.
        UIManager.ShowConfirmPopup("외부 페이지로 이동합니다.", () => {
            Application.OpenURL(targetUrl);
            item.EndInteraction();
        }, () => {
            item.EndInteraction();
        });
    }
}

5. 스크린샷 및 영상 녹화 시 광고 숨김 (`Capture`)

캡처할 지면의 hideDuringCapture를 true로 설정하고 BeginAdHiddenCapture()로 광고를 숨긴 상태에서 촬영합니다.

using EasterAd;
using UnityEngine;

public class PhotoModeManager : MonoBehaviour
{
    public void CaptureCleanScreenshot()
    {
        // Using 블록 범위 동안 hideDuringCapture가 true인 모든 지면이 숨겨집니다.
        using (EasterAdSdk.Instance.BeginAdHiddenCapture())
        {
            ScreenCapture.CaptureScreenshot("PromotionalCleanScreen.png");
        }
        // Using 블록을 벗어나면 원래 광고 텍스처가 즉시 복원됩니다.
    }
}

6. 표시할 소재 확인하기

Unity 지면에는 PNG·JPEG 정지 이미지를 사용합니다. 세부 파일 규격은 소재 요건에서 확인합니다.

7. 개인정보 보호 및 요청 제어 API

게임사의 개인정보 정책에 따라 아래 API로 광고 요청과 맞춤형 광고를 제어합니다.

API 메서드	설명
`SetAdRequestsEnabled(bool)`	`false`로 설정해 신규 광고 요청을 중단하고 진행 중인 모바일 광고 작업을 취소합니다.
`SetChildDirected(bool)`	아동 대상 서비스 여부를 지정합니다. `true`로 설정하면 맞춤형 광고를 즉시 비활성화합니다.
`SetPrivacyConsent(adRequestsAllowed, personalizedAdsAllowed, consentString, privacyRegion, childDirected)`	요청·맞춤형 광고 허용 여부를 `bool`로 전달합니다. 동의 문자열과 지역은 `string`이며 기본값은 빈 문자열입니다. 아동 대상 여부는 `bool`이며 기본값은 `false`입니다.
`ConfigurePrivacy(EasterAdPrivacyOptions)`	개인정보 정책 옵션을 구조체 하나로 일괄 적용합니다.

다음 단계

모바일(Android/iOS) 연결 모듈: Android/iOS 환경에서 기존 모바일 광고 벤더 SDK와 연동하는 방법을 확인합니다.