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

Android·iOS에서는 게임이 사용하는 외부 모바일 광고 SDK(Google AdMob, Unity Ads, AppLovin 등)를 연결합니다.

IEasterAdMobileAdProvider를 구현하여 등록하고 Item.Load()로 모바일 광고를 호출합니다.

---

1. 모바일 광고 호출 순서

연결 모듈은 아래 호출 순서에 맞춰 구현합니다.

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)

---

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

외부 벤더 SDK와 연동하는 Provider 클래스를 구현합니다.

1. IEasterAdMobileAdProvider 인터페이스를 구현하는 Provider 클래스를 작성합니다.
2. LoadAndShow 메서드에서 request.PlacementKey와 화면 정보(Surface)를 벤더 지면 ID에 매핑합니다.
3. 벤더 광고 SDK의 표시 메서드를 호출하고 결과에 맞춰 completion 콜백을 1회 호출합니다.
4. 작업 취소 요청 시 벤더 광고 호출을 취소하는 동기식 IDisposable 핸들을 반환합니다.

아래 VendorSdk, MapToVendorPlacement, ActionDisposable은 게임에서 구현할 연결 코드의 예시 이름입니다. 선택한 광고 SDK의 표시·결과·취소 기능에 맞춰 구현합니다.

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. 연결 모듈 등록과 해제

1. 외부 벤더 광고 SDK의 초기화를 완료합니다.
2. 씬에서 첫 Item.Load()가 호출되거나 loadOnStart = true인 지면이 로드되기 전에 EasterAdSdk.RegisterMobileAdProvider를 호출하여 Provider를 등록합니다.
3. 진행 중인 광고 작업이 없을 때 필요에 따라 EasterAdSdk.UnregisterMobileAdProvider를 호출하여 등록을 해제합니다.

using EasterAd;
using UnityEngine;

public class GameInitializer : MonoBehaviour
{
    private readonly CustomMobileAdProvider provider = new CustomMobileAdProvider();

    void Awake()
    {
        // 벤더 광고 SDK 초기화 완료 후 등록
        EasterAdSdk.RegisterMobileAdProvider(provider);
    }

    // 게임에서 진행 중인 광고 작업이 모두 끝난 뒤 호출합니다.
    public void UnregisterAfterAdsFinish()
    {
        EasterAdSdk.UnregisterMobileAdProvider(provider);
    }
}

---

4. 연결 모듈 구현 조건

모바일 연결 모듈을 구현할 때는 다음 요구사항과 제약을 준수합니다.

콜백 1회 호출 원칙

• completion 콜백은 취소되지 않은 일반 호출 흐름에서 정확히 1회 호출합니다. 다음 광고를 요청할 수 있도록 작업 종료 결과를 전달합니다.

취소 핸들(IDisposable)의 무결성

• Dispose()는 동기식으로 정리를 완료하고, 여러 번 호출해도 같은 결과를 유지하며 예외 없이 반환합니다.
• Dispose()에서 처리되지 않은 예외가 발생하면 해당 앱 프로세스가 끝날 때까지 모바일 광고 기능이 차단됩니다. 재시작 후 사용하려면 먼저 연결 모듈의 정리 오류를 수정합니다.

모바일 광고 표시 범위

• 모바일 광고는 등록한 연결 모듈에서만 표시합니다. 모듈이 등록되지 않았거나 오류 또는 NoFill이 발생하면 광고 없이 게임을 계속 진행합니다.

인스펙터 옵션의 동작 범위

• 외부 광고 SDK의 전체화면·네이티브 UI는 해당 SDK의 설정으로 제어합니다. EasterAd 인스펙터의 allowImpression, interactable, enableRefresh, hideDuringCapture는 인게임 지면에 적용됩니다.

Displayed() 결과와 보상 처리

EasterAdMobileAdResult.Displayed()는 외부 벤더 SDK에서 광고 화면이 정상적으로 표시되고 닫힌 상태만 나타냅니다. 보상은 외부 광고 SDK의 보상 결과를 별도로 확인하여 처리합니다.

---

다음 단계

• 라이프사이클과 결과 처리에서 상태와 요청 제어 방법을 확인합니다.