라이프사이클과 결과 처리

EasterAd Unity SDK의 광고 지면(Item)은 비동기 생명주기(Lifecycle)에 따라 동작합니다. 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`	컴포넌트가 인스턴스화되었으나 아직 SDK에 등록되지 않은 상태입니다.
`Ready`	SDK 초기화가 완료되고 광고 단위를 바인딩하여 광고를 요청할 준비가 된 상태입니다.
`Loading`	서버에 광고 소재를 요청하고 텍스처를 다운로드 중인 비동기 상태입니다.
`Loaded`	광고 소재 수신이 완료되어 지면에 텍스처가 렌더링된 상태입니다.
`Impressing`	플레이어 시야(카메라 Frustum)에 들어와 노출 검증 조건을 만족 중인 상태입니다.
`Impressed`	유효 노출 조건을 완전히 충족하여 공식 실적으로 확정된 상태입니다.
`NoFill`	현재 타깃팅 조건에 부합하는 활성 캠페인이 없는 정상 응답 상태입니다.
`Failed`	네트워크 타임아웃, 파싱 오류 등 예외가 발생한 상태입니다.
`Disabled`	심사 미승인, 비활성 지면 또는 플랫폼 정책에 의해 요청이 차단된 상태입니다.

2. NoFill 응답 대응 가이드

NoFill은 시스템 장애나 에러가 아니라, “현재 시점에 해당 지면과 플레이어에게 매칭될 수 있는 라이브 광고가 없다”는 정상적인 비즈니스 응답입니다.

자동 재시도 미지원: SDK는 NoFill 응답을 받았을 때 자동으로 다시 요청하지 않습니다. 불필요한 네트워크 트래픽 낭비와 배터리 소모를 방지하기 위함입니다.
개발 권장 사항: 짧은 간격(예: 1~2초)으로 Item.Load()를 반복 호출하는 재시도 루프를 작성하지 마세요. 다음 씬으로 넘어가거나 플레이어가 새로운 게임 세션을 시작하는 등 충분한 시간 간격을 둔 비즈니스 이벤트 시점에 다음 로드를 요청하는 것이 모범 사례입니다.

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

SDK에서 광고 요청의 성공/실패 여부를 코드로 감지할 수 있는 유일한 공식 창구는 EasterAdSdk.Instance.AdRequestObserved 이벤트입니다.

using EasterAd;
using UnityEngine;

public class AdDiagnosticsListener : MonoBehaviour
{
    void OnEnable()
    {
        // SDK 초기화가 완료된 상태에서 이벤트를 구독합니다.
        if (EasterAdSdk.OnceInitialized)
        {
            EasterAdSdk.Instance.AdRequestObserved += HandleAdRequestObserved;
        }
    }

    void OnDisable()
    {
        // 메모리 누수를 방지하기 위해 반드시 해제합니다.
        if (EasterAdSdk.OnceInitialized)
        {
            EasterAdSdk.Instance.AdRequestObserved -= HandleAdRequestObserved;
        }
    }

    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를 설정해야 합니다.
외부 링크 확인 UI 연동: 광고를 누르면 바로 이동하지 않고 게임 내 확인 팝업을 띄우는 흐름을 권장합니다.

using EasterAd;
using UnityEngine;

public class AdInteractionHandler : MonoBehaviour
{
    void Start()
    {
        // 외부 URL 이동 요청 감지 시 게임 내 확인 팝업 오픈
        EasterAdInteraction.ExternalNavigationRequested += OnNavigationRequested;
    }

    public void OnAdObjectClicked(Item item)
    {
        // 클릭 상호작용 시작
        EasterAdInteraction.StartAndRequestOpen(item);
    }

    private void OnNavigationRequested(string targetUrl)
    {
        // 게임 내 '외부 브라우저로 이동하시겠습니까?' 팝업 표시
        UIManager.ShowConfirmPopup("외부 페이지로 이동합니다.", () => {
            Application.OpenURL(targetUrl);
        }, () => {
            // 취소 또는 팝업 닫힘 시 반드시 상호작용 종료를 1회 알려야 합니다.
            currentAdItem.EndInteraction();
        });
    }
}

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

홍보용 스크린샷을 찍거나 게임 내 포토 모드 기능을 지원할 때, 임시로 광고 텍스처를 가리고 기본 인게임 머티리얼로 되돌릴 수 있습니다.

using EasterAd;
using UnityEngine;

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

6. 소재(Creative) 지원 사양 및 제약

지원 포맷: Unity SDK가 인게임 오브젝트에 자체 렌더링하는 소재는 PNG 및 JPEG 정지 이미지뿐입니다.
미지원 포맷: GIF 애니메이션이나 동영상(MP4 등) 소재는 렌더링을 지원하지 않으며, 해당 소재가 매칭되면 자동으로 NoFill 처리됩니다.
자세한 파일 규격 및 해상도는 소재 요건을 확인하세요.

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

EasterAd SDK는 글로벌 개인정보 보호 규정(GDPR, COPPA 등) 준수를 위해 클라이언트 로컬 정책 제어 API를 제공합니다.

API 메서드	설명
`SetAdRequestsEnabled(bool)`	로컬 킬 스위치(Kill Switch)입니다. `false`로 설정하면 모든 신규 광고 요청이 차단되고 진행 중이던 모바일 모듈 작업도 즉시 취소됩니다.
`SetChildDirected(bool)`	아동 대상 서비스 여부를 지정합니다. `true`로 설정하면 맞춤형 광고가 로컬에서 즉시 비활성화됩니다. (COPPA 대응)
`SetPrivacyConsent(...)`	일반 동의 상태, 맞춤형 광고 허용 여부, 동의 문자열(TCF 등), 관할 지역을 전달합니다.
`ConfigurePrivacy(...)`	위의 모든 개인정보 정책 옵션을 구조체 하나로 일괄 적용합니다.

다음 단계

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