광고 단위 배치하기

Unity 환경에서 광고 지면은 게임 월드 속 3D 오브젝트에 투사하거나 2D UI 레이아웃에 배치할 수 있습니다. EasterAd SDK는 이를 위해 두 가지 전용 컴포넌트(Plane, CanvasItem)를 제공하며, 둘 다 기본 광고 컴포넌트인 EasterAd.Item을 상속합니다.

1. 광고 컴포넌트 선택

구현하려는 게임 화면의 특성에 맞춰 적절한 컴포넌트를 선택하세요.

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

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

게임 월드 속 3D 표면에 광고를 띄우는 단계입니다.

flowchart LR
    A["평면 Mesh GameObject 준비"] --> B["EasterAd.Plane 컴포넌트 추가"]
    B --> C["MaterialManager 추가 (필수)"]
    C --> D["비율/회전 조정 & ID 연결"]

오브젝트 준비: 패키지에 포함된 PlaneItem 프리팹을 씬에 배치하거나, MeshFilter와 MeshRenderer가 포함된 평면(Quad 또는 커스텀 메시) GameObject를 생성합니다.
컴포넌트 추가: 대상 GameObject에 EasterAd.Plane과 MaterialManager 컴포넌트를 함께 추가합니다.
- MaterialManager는 광고 텍스처를 게임 쉐이더 머티리얼에 올바르게 바인딩하고 메모리를 관리하는 필수 컴포넌트입니다.
크기 및 비율 조정: 대시보드에 등록된 인벤토리의 비율 정책(예: 16:9, 1:1)에 맞게 Quad의 가로/세로 비율을 맞춥니다.

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

UGUI를 활용해 UI 인터페이스 내부에 광고를 띄우는 단계입니다.

UI 오브젝트 생성: 씬의 Canvas 하위에 빈 GameObject를 생성하고 RawImage 컴포넌트를 추가합니다.
크기 설정: RectTransform의 Width와 Height를 0이 아닌 유효한 크기(소재 비율과 일치)로 지정합니다.
컴포넌트 추가: 같은 GameObject에 EasterAd.CanvasItem 컴포넌트를 추가합니다. 런타임에 수신된 광고 텍스처가 RawImage에 자동으로 적용됩니다.

4. 광고 단위 ID 연결 방법

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

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

씬에 정적으로 배치된 지면인 경우 가장 간편한 방식입니다.

씬에서 Plane 또는 CanvasItem GameObject를 선택합니다.
인스펙터의 Ad Unit Id 필드에 24자리 ID를 붙여넣습니다.

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

절차적으로 생성되는 지면이거나 런타임에 광고 지면을 결정해야 할 때 사용합니다. 인스펙터에서 자동 로드 옵션을 끈 뒤 스크립트에서 명시적으로 초기화합니다.

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를 위임 연동하는 방법을 확인합니다.