인앱 광고

앱인토스 유니티 SDK를 사용하면 C# 코드만으로 인앱 광고를 연동할 수 있어요.

Unity SDK의 전면형/보상형 광고 API는 앱인토스 WebView SDK 통합 광고와 같은 load → show 모델을 사용해요. 함수명만 Unity C# 환경에 맞게 loadFullScreenAd() 대신 AIT.LoadFullScreenAd()처럼 제공돼요.

배너 광고는 SDK가 Unity 화면 위치에 맞춰 배너 DOM(Document Object Model) 컨테이너를 생성하고 관리해요.

참고하세요

• 이 가이드에서는 최신 통합 광고 API인 AIT.LoadFullScreenAd(), AIT.ShowFullScreenAd(), AITBannerAd.Show(), AITBannerAdView 중심으로 안내해요.
• 실제 광고 렌더링은 토스 앱 환경에서 확인해 주세요. Unity Editor와 일반 브라우저에서는 Mock 로그나 실패 이벤트가 발생할 수 있어요.

---

광고 유형

광고 유형	사용하는 API	설명
전면형 광고	AIT.LoadFullScreenAd() → AIT.ShowFullScreenAd()	화면 전체를 덮는 광고예요. 화면 전환이나 주요 액션 이후에 사용할 수 있어요.
보상형 광고	AIT.LoadFullScreenAd() → AIT.ShowFullScreenAd()	광고 시청 완료 후 userEarnedReward 이벤트로 보상을 지급하는 광고예요.
배너 광고	AITBannerAd.Show() 또는 AITBannerAdView	화면 상단/하단 또는 RectTransform 영역에 배너 광고를 표시해요.

전면형 광고와 보상형 광고는 같은 API를 사용해요. 어떤 광고가 노출되는지는 콘솔에서 발급받은 광고 그룹 ID(adGroupId)로 결정돼요.

---

전면형/보상형 광고

전면형/보상형 광고는 광고를 먼저 불러온 뒤, 불러오기가 완료되면 보여주는 순서로 호출해요.

호출 흐름

1. AIT.LoadFullScreenAd()로 광고를 미리 불러와요.
2. loaded 이벤트를 받으면 광고를 보여줄 수 있어요.
3. AIT.ShowFullScreenAd()로 광고를 보여줘요.
4. dismissed 이벤트를 받으면 다음 광고를 위해 다시 Load해야 해요.
5. 보상형 광고는 userEarnedReward 이벤트를 기준으로 보상을 지급해요.

API

API	설명
AIT.LoadFullScreenAd()	광고를 미리 불러오고 이벤트를 구독해요
AIT.ShowFullScreenAd()	불러온 광고를 사용자에게 보여줘요

개발 단계에서 광고 호출을 확인할 때는 테스트용 광고 ID를 사용할 수 있어요.

유형	테스트 ID
전면형 광고	ait-ad-test-interstitial-id
보상형 광고	ait-ad-test-rewarded-id

이벤트

이벤트 타입	발생 시점
loaded	광고 불러오기가 완료됐어요
requested	광고 표시 요청이 전달됐어요
show	광고가 화면에 표시됐어요
impression	광고 노출이 기록됐어요
clicked	사용자가 광고를 클릭했어요
dismissed	사용자가 광고를 닫았어요
failedToShow	광고 표시에 실패했어요
userEarnedReward	보상형 광고에서 사용자가 보상을 획득했어요

샘플 코드

using System;
using AppsInToss;
using UnityEngine;

public class FullScreenAdExample : MonoBehaviour
{
    private const string InterstitialAdGroupId = "ait-ad-test-interstitial-id";
    private const string RewardedAdGroupId = "ait-ad-test-rewarded-id";

    private Action _loadDisposer;
    private Action _showDisposer;
    private bool _isAdLoaded;
    private string _loadedAdGroupId;

    public void LoadInterstitialAd()
    {
        LoadAd(InterstitialAdGroupId);
    }

    public void LoadRewardedAd()
    {
        LoadAd(RewardedAdGroupId);
    }

    private void LoadAd(string adGroupId)
    {
        _loadDisposer?.Invoke();
        _isAdLoaded = false;
        _loadedAdGroupId = null;

        _loadDisposer = AIT.LoadFullScreenAd(
            adGroupId: adGroupId,
            onEvent: (result) =>
            {
                if (result.Type == "loaded")
                {
                    _isAdLoaded = true;
                    _loadedAdGroupId = adGroupId;
                    Debug.Log("광고 불러오기 완료");
                }
            },
            onError: (error) =>
            {
                _isAdLoaded = false;
                _loadedAdGroupId = null;
                Debug.LogError($"광고 불러오기 실패: {error.ErrorCode} - {error.Message}");
            }
        );
    }

    public void ShowLoadedAd()
    {
        if (!_isAdLoaded || string.IsNullOrEmpty(_loadedAdGroupId))
        {
            Debug.LogWarning("아직 불러온 광고가 없어요.");
            return;
        }

        _showDisposer?.Invoke();

        _showDisposer = AIT.ShowFullScreenAd(
            adGroupId: _loadedAdGroupId,
            onEvent: (result) =>
            {
                switch (result.Type)
                {
                    case "requested":
                        Debug.Log("광고 표시 요청");
                        break;
                    case "show":
                        Debug.Log("광고 표시");
                        break;
                    case "impression":
                        Debug.Log("광고 노출 기록");
                        break;
                    case "clicked":
                        Debug.Log("광고 클릭");
                        break;
                    case "dismissed":
                        Debug.Log("광고 닫힘");
                        _isAdLoaded = false;
                        _loadedAdGroupId = null;
                        break;
                    case "failedToShow":
                        Debug.LogWarning("광고 표시 실패");
                        _isAdLoaded = false;
                        _loadedAdGroupId = null;
                        break;
                    case "userEarnedReward":
                        if (result.Data != null)
                        {
                            GrantReward(result.Data.UnitType, result.Data.UnitAmount);
                        }
                        break;
                }
            },
            onError: (error) =>
            {
                Debug.LogError($"광고 표시 실패: {error.ErrorCode} - {error.Message}");
            }
        );
    }

    private void GrantReward(string unitType, double unitAmount)
    {
        // 보상형 광고 시청 완료 후 지급할 게임 보상 로직을 구현해요.
        Debug.Log($"보상 지급: {unitType} {unitAmount}");
    }

    private void OnDestroy()
    {
        _loadDisposer?.Invoke();
        _showDisposer?.Invoke();
    }
}

안정적으로 운영하려면 이렇게 구현해 주세요

• 광고는 반드시 Load → Show → 다음 Load 순서로 호출해 주세요.
• 같은 adGroupId 기준으로는 한 번에 하나의 광고만 미리 불러오는 것을 권장해요.
• dismissed 또는 failedToShow 이벤트를 받으면 다음 노출 전에 다시 Load해 주세요.
• 보상형 광고 보상은 userEarnedReward 이벤트 기준으로 지급해 주세요.
• iOS에서 광고가 불러와지지 않으면 앱 추적 모드(App Tracking Transparency) 설정을 확인해 주세요.

---

배너 광고

배너 광고는 HTML/CSS를 직접 다루지 않고 Unity 코드로 표시할 수 있어요. SDK가 배너 DOM 컨테이너를 만들고, Unity 화면 위치와 크기에 맞게 광고를 오버레이해요.

사용 방식

방식	API	언제 사용하나요
화면 고정 배너	AITBannerAd.Show()	화면 상단 또는 하단에 배너를 한 개만 표시할 때 사용해요. 재호출하면 기존 배너를 교체해요.
영역 추적 배너	AITBannerAdView	Canvas 아래 RectTransform 영역을 따라 배너를 배치할 때 사용해요. 여러 개를 동시에 표시할 수 있어요.

배너의 강조 유형과 노출 정책은 콘솔에서 발급받은 광고 그룹 ID(adGroupId) 설정으로 결정돼요. 이미지 강조형처럼 렌더 높이가 달라지는 배너는 Resized 이벤트로 실제 높이를 전달해요.

이벤트

이벤트 종류	발생 시점
Initialized	배너 광고 SDK 초기화가 완료됐어요
InitializationFailed	배너 광고 SDK 초기화에 실패했어요
Rendered	배너가 렌더링됐어요
Viewable	배너가 화면에 보이는 상태가 됐어요
Impression	배너 노출이 집계됐어요
Clicked	사용자가 배너를 클릭했어요
Resized	렌더된 배너 크기가 변경됐어요
FailedToRender	배너 렌더링에 실패했어요
NoFill	채울 수 있는 광고가 없어요

개발 단계에서 배너 렌더링을 확인할 때는 테스트용 광고 ID를 사용할 수 있어요.

유형	테스트 ID
배너 광고 - 리스트형	ait-ad-test-banner-id
배너 광고 - 피드형	ait-ad-test-native-image-id

샘플 코드: 화면 상단/하단 고정 배너

using AppsInToss;
using UnityEngine;

public class StaticBannerAdExample : MonoBehaviour
{
    private const string TextBannerAdGroupId = "ait-ad-test-banner-id";
    private const string ImageBannerAdGroupId = "ait-ad-test-native-image-id";

    private void OnEnable()
    {
        AITBannerAd.OnAdEvent += HandleBannerEvent;
        AITBannerAd.OnError += HandleBannerError;
    }

    public void ShowTopBanner()
    {
        AITBannerAd.Show(TextBannerAdGroupId, AITBannerPosition.Top);
    }

    public void ShowBottomBanner()
    {
        AITBannerAd.Show(ImageBannerAdGroupId, AITBannerPosition.Bottom);
    }

    public void HideBanner()
    {
        AITBannerAd.Hide();
    }

    private void HandleBannerEvent(AITBannerAdEvent evt)
    {
        Debug.Log($"배너 이벤트: {evt}");
    }

    private void HandleBannerError(string message)
    {
        Debug.LogWarning($"배너 오류: {message}");
    }

    private void OnDisable()
    {
        AITBannerAd.OnAdEvent -= HandleBannerEvent;
        AITBannerAd.OnError -= HandleBannerError;
        AITBannerAd.Hide();
    }
}

샘플 코드: RectTransform 영역에 배너 표시하기

using AppsInToss;
using UnityEngine;
using UnityEngine.UI;

public class BannerAdViewExample : MonoBehaviour
{
    [SerializeField] private RectTransform bannerArea;
    [SerializeField] private LayoutElement bannerLayout;

    private AITBannerAdView _bannerView;

    private void Start()
    {
        _bannerView = bannerArea.gameObject.AddComponent<AITBannerAdView>();
        _bannerView.AdGroupId = "ait-ad-test-banner-id";
        _bannerView.Placement = AITBannerAdPlacement.FollowRectTransform;

        // LayoutGroup이 높이를 제어하는 경우 직접 preferredHeight를 반영해요.
        _bannerView.AutoResizeHeight = false;
        _bannerView.OnAdEvent += HandleBannerEvent;
    }

    public void ShowBanner()
    {
        _bannerView.Show();
    }

    public void HideBanner()
    {
        _bannerView.Hide();
    }

    private void HandleBannerEvent(AITBannerAdEvent evt)
    {
        Debug.Log($"배너 이벤트: {evt}");

        if (evt.Kind == AITBannerAdEventKind.Resized && _bannerView.RenderedHeightLocal > 0f)
        {
            bannerLayout.preferredHeight = _bannerView.RenderedHeightLocal;
        }
    }

    private void OnDestroy()
    {
        if (_bannerView != null)
        {
            _bannerView.OnAdEvent -= HandleBannerEvent;
            _bannerView.Hide();
        }
    }
}

어떤 방식을 선택해야 하나요?

• 화면 상단 또는 하단에 배너 하나만 고정으로 띄우려면 AITBannerAd.Show()를 사용해 주세요.
• 특정 UI 영역 안에 배너를 배치하거나 여러 배너를 동시에 띄워야 하면 AITBannerAdView를 사용해 주세요.
• AITBannerAdView는 OnEnable 때 자동 표시되는 설정을 가지고 있어요. Inspector에서 Ad Group Id를 설정했다면 별도 Show() 호출 없이 표시될 수 있어요.
• 레이아웃 그룹이 높이를 제어하는 영역에서는 AutoResizeHeight = false로 두고, Resized 이벤트에서 RenderedHeightLocal을 LayoutElement.preferredHeight에 반영해 주세요.

---

테스트와 운영 주의사항

TIP

• 인앱 광고는 토스 앱에서 QR 코드를 통해 테스트해 주세요.
• Unity Editor와 일반 브라우저에서는 실제 광고 네트워크 호출이 동작하지 않을 수 있어요.
• 전면형/보상형 광고는 loaded 이벤트를 받은 뒤에만 Show해 주세요.
• 보상형 광고의 보상 지급은 userEarnedReward 이벤트 기준으로 처리해 주세요.
• 화면을 벗어날 때는 구독 해제 함수와 AITBannerAd.Hide() 또는 AITBannerAdView.Hide()로 광고 리소스를 정리해 주세요.