콘텐츠로 이동
EasterAdEasterAdDocs

모바일(Android/iOS) 연결 모듈

EasterAd Unity SDK는 크로스 플랫폼 개발 생산성을 위해 단일 광고 코드 인터페이스를 제공합니다. 단, Android 및 iOS 환경에서는 EasterAd가 자체 렌더링을 수행하지 않으며, 호스트 게임이 사용하는 외부 모바일 광고 SDK(Google AdMob, Unity Ads, AppLovin 등)에 로드 및 표시를 전적으로 위임(Delegation)합니다.

개발자는 IEasterAdMobileAdProvider 인터페이스를 단 한 번만 구현하여 등록하면, Windows 환경의 인게임 3D/2D 지면과 모바일 환경의 네이티브 광고를 동일한 Item.Load() 코드로 제어할 수 있습니다.

1. 모바일 위임 아키텍처

섹션 제목: “1. 모바일 위임 아키텍처”

호스트 게임이 Provider를 등록하면 모바일 런타임에서 다음과 같은 위임 흐름이 동작합니다.

sequenceDiagram
    autonumber
    participant Game as 호스트 게임
    participant Item as EasterAd Item
    participant Provider as 모바일 광고 Provider
    participant Vendor as 서드파티 벤더 SDK (AdMob 등)

    Game->>Item: Item.Load() 호출
    Item->>Provider: LoadAndShow(request, completion)
    Provider->>Vendor: 벤더 광고 로드 및 표시 요청
    Vendor-->>Provider: 표시 완료 / NoFill / 오류
    Provider-->>Item: completion(EasterAdMobileAdResult)
    Note over Item: 결과에 따라 내부 상태 업데이트

2. 인터페이스 구현 (IEasterAdMobileAdProvider)

섹션 제목: “2. 인터페이스 구현 (IEasterAdMobileAdProvider)”

외부 벤더 SDK와의 브리지 역할을 수행하는 Provider 클래스를 작성합니다.

using System;
using EasterAd;
using UnityEngine;


public sealed class CustomMobileAdProvider : IEasterAdMobileAdProvider
{
    public IDisposable LoadAndShow(
        EasterAdMobileAdRequest request,
        Action<EasterAdMobileAdResult> completion)
    {
        // 1. request.PlacementKey와 Surface(Plane/Canvas)를 벤더 지면 ID에 매핑
        string vendorPlacementId = MapToVendorPlacement(request.PlacementKey);


        // 2. 벤더 SDK 로드 및 표시 호출
        VendorSdk.ShowAd(vendorPlacementId, (vendorResult) =>
        {
            // 전체 작업 종료 후 completion 콜백을 정확히 1회 호출합니다.
            if (vendorResult.IsSuccess)
            {
                completion(EasterAdMobileAdResult.Displayed());
            }
            else if (vendorResult.IsNoFill)
            {
                completion(EasterAdMobileAdResult.NoFill());
            }
            else
            {
                completion(EasterAdMobileAdResult.Failed(EasterAdMobileAdFailure.ProviderError));
            }
        });


        // 3. 작업 취소용 핸들 반환 (멱등적이어야 하며 예외 발생 금지)
        return new ActionDisposable(() => VendorSdk.CancelAd(vendorPlacementId));
    }
}

3. Provider 등록 시점과 생명주기

섹션 제목: “3. Provider 등록 시점과 생명주기”

벤더 SDK 초기화가 완료된 후, 씬에서 첫 Item.Load()(또는 loadOnStart = true인 지면)가 실행되기 전에 등록해야 합니다.

using EasterAd;
using UnityEngine;


public class GameInitializer : MonoBehaviour
{
    void Awake()
    {
        // 벤더 광고 SDK 초기화 완료 후 등록
        EasterAdSdk.RegisterMobileAdProvider(new CustomMobileAdProvider());
    }


    void OnDestroy()
    {
        // 안전한 시점에 등록 해제 가능 (진행 중인 광고 작업이 없을 때)
        // EasterAdSdk.UnregisterMobileAdProvider(provider);
    }
}

4. 엄격한 구현 요구사항 및 주의사항

섹션 제목: “4. 엄격한 구현 요구사항 및 주의사항”

모바일 연결 모듈을 구현할 때는 안정성을 위해 아래의 제약 사항을 반드시 준수해야 합니다.

콜백 1회 호출 원칙

섹션 제목: “콜백 1회 호출 원칙”
  • completion 콜백은 취소되지 않은 일반적인 흐름에서 반드시 정확히 한 번만 호출되어야 합니다. 중복 호출하거나 호출을 누락하면 내부 상태 머신이 교착 상태에 빠질 수 있습니다.

취소 핸들(IDisposable)의 무결성

섹션 제목: “취소 핸들(IDisposable)의 무결성”
  • 반환하는 취소 핸들의 Dispose() 메서드는 동기적이고 멱등적(Idempotent)이어야 하며, 어떠한 경우에도 예외를 던져서는 안 됩니다.
  • 만약 정리(Dispose) 도중 처리되지 않은 예외가 발생할 경우, 해당 앱 프로세스 내에서 EasterAd 모바일 광고 기능이 영구 차단되며 런타임 복구 API가 제공되지 않습니다.

인게임 렌더러 폴백 미지원

섹션 제목: “인게임 렌더러 폴백 미지원”
  • 모바일 플랫폼에서 등록된 Provider가 없거나, Provider에서 오류/NoFill이 반환되면 인게임 3D 렌더러로 대체 폴백하지 않고 즉시 종료됩니다.

인스펙터 옵션의 동작 범위

섹션 제목: “인스펙터 옵션의 동작 범위”
  • 모바일 플랫폼에서는 인스펙터의 allowImpression, interactable, enableRefresh, hideDuringCapture 등의 옵션이 외부 벤더 SDK의 전체화면이나 네이티브 UI를 제어하지 않습니다.

다음 단계

섹션 제목: “다음 단계”