> ## Documentation Index
> Fetch the complete documentation index at: https://guide.daro.so/llms.txt
> Use this file to discover all available pages before exploring further.

# 네이티브 광고

> Unity 프로젝트에서 DARO 네이티브 광고를 구현하는 방법을 알아봅니다.

## 네이티브 광고 형태 소개

* 앱 UI에 맞게 광고 자산을 직접 배치하는 광고입니다.
* Unity UI 프리팹에 `DaroNativeAdView`를 붙여 슬롯을 연결하거나, `DaroNativeAd.Info`를 직접 읽어 커스텀 UI에 바인딩할 수 있습니다.

<img src="https://mintcdn.com/delightroom-5a71a6a8/dxU0bpsPoPvkYh_g/sdk-integration/common-img/ad-formats/native-example-elements-ko.png?fit=max&auto=format&n=dxU0bpsPoPvkYh_g&q=85&s=3f2c4b8e38bff2137e0bac37c1254931" alt="네이티브 광고 구성 요소 예시" style={{ width: "100%" }} width="1968" height="2888" data-path="sdk-integration/common-img/ad-formats/native-example-elements-ko.png" />

***

## 광고 연동하기

<Steps>
  <Step title="Native Ad View 준비">
    Unity UI 프리팹 루트에 `DaroNativeAdView`를 추가하고 `TitleText`, `BodyText`, `IconImage`, `CtaButton`, `MediaContainer` 슬롯을 연결합니다.

    `MediaContainer`는 선택 항목입니다. media asset이 없는 광고가 바인딩되면 `DaroNativeAdView`가 `MediaContainer`를 자동으로 숨깁니다.

    `Bind(ad)`는 Android와 iOS에서 `CtaButton` 탭을 네이티브 클릭 흐름에 자동으로 연결합니다.
  </Step>

  <Step title="광고 인스턴스 생성">
    ```csharp theme={null}
    private DaroNativeAd ad;
    [SerializeField] private DaroNativeAdView adView;

    ad = new DaroNativeAd("your-native-ad-unit-id");
    ```
  </Step>

  <Step title="이벤트 핸들러 등록">
    ```csharp theme={null}
    ad.OnAdLoaded += info => adView.Bind(ad);
    ad.OnAdFailedToLoad += error => Debug.LogWarning(error.Message);
    ad.OnAdImpression += info => Debug.Log("impression");
    ad.OnAdClicked += info => Debug.Log("clicked");
    ```
  </Step>

  <Step title="광고 로드">
    ```csharp theme={null}
    adView.LoadFor(ad);
    ```
  </Step>

  <Step title="광고 해제">
    ```csharp theme={null}
    adView.Unbind();
    ad?.Dispose();
    ad = null;
    ```
  </Step>
</Steps>

<Tip>
  커스텀 uGUI에서는 `ad.WireCtaButton(ctaButton)`으로 실제 CTA 터치 영역을 연결하세요. AdChoices 위치를 지정했다면 `ad.WireAdChoices(fullAdRectTransform)`으로 전체 광고 영역도 연결합니다. 표시·숨김에 맞춰 `NotifyVisible()`·`NotifyHidden()`을 호출하고, 광고 클릭 결과는 Unity 버튼의 `onClick` 대신 `OnAdClicked`로 받으세요. `NotifyClicked()` 호출만으로 실제 기기의 CTA 터치 영역을 연결할 수는 없습니다.
</Tip>

<Warning>
  `Info.Icon`과 `Info.MediaImage` 텍스처는 `DaroNativeAd`가 소유하며, 광고를 다시 로드하거나 해제할 때 정리됩니다. `Unbind()`와 `Dispose()` 후에 해당 텍스처를 보관하거나 다시 사용하지 마세요.
</Warning>

***

## 로드·표시와 자동 갱신

`LoadFor(ad)`는 광고를 로드하며, 로드 완료 후 `Bind(ad)`를 호출해야 화면에 표시됩니다. iOS에서도 로드만 한 상태에는 네이티브 광고 표시가 나타나지 않습니다. 바인딩된 뷰의 GameObject를 비활성화하면 네이티브 표시와 터치도 숨겨지고, 다시 활성화하면 복원됩니다. 사용을 끝낼 때는 `Unbind()`와 `Dispose()`를 호출하세요.

자동 갱신은 서버의 광고 지면 설정을 따릅니다. 갱신 주기가 0이면 주기 갱신을 하지 않고, 양수이면 광고를 주기적으로 갱신합니다. `Load()`를 한 번 호출한 뒤에도 로드 콜백이 다시 발생할 수 있으며, 이 자체는 오류가 아닙니다. 갱신할 때마다 별도 인스턴스를 만들 필요는 없습니다. 위 예제의 `OnAdLoaded` 처리로 최신 광고를 바인딩하고, 클릭은 `OnAdClicked`로 받으세요.

## AdChoices 위치 지정

`0.5.0-rc.4`부터 생성자에서 위치를 지정할 수 있습니다.

```csharp theme={null}
ad = new DaroNativeAd(adUnitId, DaroAdChoicesPosition.TopLeft);
ad.OnAdLoaded += info => adView.Bind(ad);
adView.LoadFor(ad);
```

`TopLeft`, `TopRight`, `BottomRight`, `BottomLeft`를 제공합니다. `DaroNativeAdView`의 전체 RectTransform을 기준으로 배치하므로 광고 전체 영역에 맞게 크기를 설정하세요. CTA 영역과 AdChoices 영역은 별개입니다. 위치를 생략한 기존 생성자는 기본 배치를 유지합니다.

<Note>
  개별 광고 디맨드가 제공하는 AdChoices UI에 따라 지정 위치가 그대로 적용되지 않을 수 있습니다. iOS의 일부 광고에서는 왼쪽 위치를 지정해도 오른쪽에 표시되는 동작이 확인됐습니다. 사용하는 디맨드와 화면 방향에서 표시 위치 및 터치를 확인하세요.
</Note>

## Example

```csharp expandable theme={null}
using Daro;
using UnityEngine;

public sealed class NativeAdHost : MonoBehaviour
{
    [SerializeField] private string adUnitId = "your-native-ad-unit-id";
    [SerializeField] private DaroNativeAdView adView;
    private DaroNativeAd ad;

    private void OnEnable()
    {
        ad = new DaroNativeAd(adUnitId);
        ad.OnAdLoaded += info => adView.Bind(ad);
        ad.OnAdFailedToLoad += error => Debug.LogWarning(error.Message);
        adView.LoadFor(ad);
    }

    private void OnDisable()
    {
        adView.Unbind();
        ad?.Dispose();
        ad = null;
    }
}
```

## 에셋 수신 여부로 UI 분기하기

* `DaroNativeAd.OnNativeAdAssetLoaded` 이벤트로 특정 에셋이 없는 경우에 대응할 수 있습니다.
* 이벤트 타입은 `Action<ISet<NativeAdAssetType>>`이며 `ad.Info.AssetTypes`에서도 `ISet<NativeAdAssetType>`을 읽을 수 있습니다.
* `iconContainer`는 고객사의 아이콘 UI 컨테이너입니다.

| 값 | 의미 |
| - | - |
| `Title` | 광고 제목 |
| `Body` | 광고 본문 |
| `Icon` | 광고 아이콘 |
| `Media` | 광고 이미지 또는 동영상 |
| `CallToAction` | 행동 유도 버튼 문구 ( 예: 설치하기 ) |
| `Advertiser` | 광고주명 ( iOS ) |

```csharp theme={null}
using Daro;

bool hasReceivedMedia = false;
ad.OnNativeAdAssetLoaded += assetTypes =>
{
    hasReceivedMedia = assetTypes.Contains(NativeAdAssetType.Media);
};
ad.OnAdLoaded += info =>
{
    adView.Bind(ad);
    iconContainer.SetActive(ad.Info != null &&
        ad.Info.AssetTypes.Contains(NativeAdAssetType.Icon));
};
```

* `Advertiser`는 수신 여부만 전달하며 `Info`의 광고주명 필드나 전용 뷰 슬롯은 제공하지 않습니다.
* `Media`는 네이티브 SDK의 수신 신호입니다. Unity 미디어 텍스처 전달은 지원하지 않으므로 이 값만으로 `Info.MediaImage`가 있다고 가정하지 마세요.