광고 단위 배치하기

게임 월드 속 3D 오브젝트나 2D UI 레이아웃에 광고 지면을 배치할 수 있습니다. 3D 표면에는 Plane을, UI에는 CanvasItem을 선택합니다. 스크립트에서 두 컴포넌트를 공통으로 제어할 때는 EasterAd.Item 타입을 사용합니다.

1. 광고 컴포넌트 선택

구현하려는 게임 화면의 특성에 맞춰 컴포넌트를 선택합니다.

컴포넌트	렌더링 영역	권장 활용 위치	필수 부착 요소
`Plane`	게임 월드의 3D 평면	인게임 건물 외벽 간판, 도로변 빌보드, 경기장 전광판 등	`MeshFilter` + `MeshRenderer` + `MaterialManager`
`CanvasItem`	UGUI Canvas 계층 구조	메인 로비 배너, 일시정지 메뉴 UI, 스테이지 클리어 결과창 등	`RectTransform` (크기 > 0) + `RawImage`

2. 3D 지면 배치 (`Plane`)

패키지에 포함된 PlaneItem 프리팹을 씬에 배치하거나, MeshFilter와 MeshRenderer가 포함된 평면(Quad 또는 커스텀 메시) GameObject를 생성합니다.
대상 GameObject에서 EasterAd.Plane과 MaterialManager를 확인하고 빠진 컴포넌트를 추가합니다.
대시보드에 등록된 인벤토리의 비율 정책(예: 16:9, 1:1)에 맞게 Quad의 가로/세로 비율을 조정합니다.

3. UI 지면 배치 (`CanvasItem`)

씬의 Canvas 하위에 빈 GameObject를 생성하고 RawImage 컴포넌트를 추가합니다.
RectTransform의 Width와 Height를 0보다 큰 유효한 크기(소재 비율과 일치)로 설정합니다.
같은 GameObject에 EasterAd.CanvasItem 컴포넌트를 추가합니다.

4. 광고 단위 ID 연결 방법

대시보드에서 발급받은 24자리 16진수 광고 단위 ID를 컴포넌트에 연결하는 방법은 두 가지입니다.

방법 A: 에디터 인스펙터에서 고정 연결 (권장)

씬에 정적으로 배치된 지면에 적용합니다.

씬에서 Plane 또는 CanvasItem GameObject를 선택합니다.
인스펙터의 Ad Unit Id 필드에 24자리 광고 단위 ID를 입력합니다.

방법 B: 런타임 스크립트에서 동적 연결

절차적으로 생성되는 지면이거나 런타임에 광고 지면을 결정해야 할 때 사용합니다.

인스펙터에서 autoInitialize, loadOnStart, enableRefresh 설정을 해제합니다.
스크립트에서 InitializeWithAdUnitId 메서드를 호출해 24자리 광고 단위 ID를 전달하고 초기화합니다.

using EasterAd;
using UnityEngine;

public class DynamicAdSpawner : MonoBehaviour
{
    [SerializeField] private Item adItem;
    [SerializeField] private string targetAdUnitId = "65a123456789abcdef012345";

    void Awake()
    {
        // 인스펙터에서 autoInitialize, loadOnStart, enableRefresh를 꺼둔 상태에서 호출합니다.
        adItem.InitializeWithAdUnitId(targetAdUnitId);
    }
}

5. 인스펙터 주요 설정 옵션

Plane과 CanvasItem 컴포넌트의 인스펙터에서 동작 방식을 설정할 수 있습니다.

설정 필드	기본값	설명 및 활용 가이드
`adUnitId`	(비어 있음)	대시보드에서 발급받은 24자리 광고 단위 ID입니다.
`autoInitialize`	`true`	SDK가 준비된 후 해당 지면을 자동으로 초기화합니다.
`loadOnStart`	`true`	Unity의 `Start()` 생명주기 시점에 첫 광고 로드를 즉시 시작합니다.
`allowImpression`	`true`	노출 유효성 검증 조건을 충족했을 때 공식 유효 노출(Impression)로 집계할지 여부입니다.
`interactable`	`false`	이용자의 클릭/상호작용을 허용할지 여부입니다. 반드시 광고 로드 전에 설정해야 합니다.
`enableRefresh`	`true`	노출 또는 클릭 상호작용이 완료된 후 다음 광고로 자동 교체(새로고침)할지 여부입니다.
`refreshTime`	`10초`	자동 갱신 타이머 대기 시간입니다. (노출 또는 상호작용이 완료된 후 카운트다운을 시작합니다.)
`hideDuringCapture`	`true`	스크린샷이나 인게임 캡처 시 광고 렌더링을 일시적으로 숨길지 여부입니다.

다음 단계

라이프사이클과 결과 처리: 광고 로드 상태 흐름, NoFill 대응, 진단 이벤트 수신 및 클릭 처리를 알아봅니다.
모바일(Android/iOS) 연결 모듈: 모바일 환경에서 벤더 광고 SDK를 위임 연동하는 방법을 확인합니다.