Ad API

v0.2.0 부터 보상형 비디오·배너·공유가 하나의 리워드 슬롯 모델로 통합되었습니다. 활성 슬롯 목록을 조회해 렌더링하고, 사용자가 탭하면 ShowRewardedAd(slot) 한 번으로 실행합니다. 슬롯 없이 보상형 비디오만 표시하려면 아래 ShowRewardedAd(adUnitId, ...)를 그대로 사용할 수 있습니다.

통합 리워드 슬롯

각 슬롯은 다음 구조입니다.

RewardedAdSlot:

필드	타입	설명
`slotId`	`string`	슬롯 식별자 (실행 시 지정)
`action`	`string`	액션 유형 (`"REWARD_VIDEO"` / `"BANNER"` / `"SHARE"`)
`slotData`	`RewardSlotData`	게임 렌더용 데이터 (선택 — 아래 참고)

RewardSlotData:

필드	타입	설명
`imageUrl`	`string`	슬롯 이미지 URL (게임이 직접 렌더링)
`title`	`string`	슬롯 제목
`expiresAt`	`long`	만료 시각 (Unix ms, 0이면 미설정)

slotData 는 기본 보상형 비디오·공유 슬롯에서 비어 있을 수 있습니다(렌더링할 시각 요소 없음). 배너 슬롯은 보통 slotData.imageUrl 을 포함합니다. JsonUtility 특성상 slotData 가 빈 객체로 전달될 수 있으니, 사용 전 imageUrl 등 필드가 비었는지 확인하세요.

`GetRewardedAdSlots(onSuccess, onFail)`

활성 리워드 슬롯 전체 목록을 조회합니다.

파라미터:

파라미터	타입	필수	설명
`onSuccess`	`Action<GetRewardedAdSlotsResult>`	-	성공 콜백 (`slots`)
`onFail`	`Action<string>`	-	실패 콜백

성공 응답 (GetRewardedAdSlotsResult):

필드	타입	설명
`slots`	`RewardedAdSlot[]`	활성 슬롯 목록

TudadaSDK.Instance.GetRewardedAdSlots(
    onSuccess: (res) => {
        if (res.slots.Length == 0) return;
        foreach (var slot in res.slots)
            Debug.Log($"{slot.slotId} / {slot.action}");
    },
    onFail: (err) => Debug.LogWarning("슬롯 조회 실패: " + err)
);

`GetRewardedAdSlot(slotId, onSuccess, onFail)`

slotId 로 단일 슬롯을 조회합니다. 슬롯이 없으면 onFail 이 호출됩니다.

파라미터:

파라미터	타입	필수	설명
`slotId`	`string`	✅	조회할 슬롯 ID
`onSuccess`	`Action<GetRewardedAdSlotResult>`	-	성공 콜백 (`slot`)
`onFail`	`Action<string>`	-	실패 콜백 (슬롯 없음 포함)

`ShowRewardedAd(slot, onSuccess, onFail)` (권장)

슬롯을 실행합니다. 슬롯의 action(영상/배너/공유)에 따라 플랫폼이 자동으로 디스패치합니다. 로드·표시·실패 시 재시도 및 안내를 플랫폼이 자동 처리합니다.

파라미터:

파라미터	타입	필수	설명
`slot`	`RewardedAdSlot`	✅	`GetRewardedAdSlots` / `GetRewardedAdSlot` 에서 받은 슬롯
`onSuccess`	`Action<ShowRewardedAdResult>`	-	성공 콜백 (`isEnded`)
`onFail`	`Action<string>`	-	실패 콜백

TudadaSDK.Instance.GetRewardedAdSlots(
    onSuccess: (res) => {
        if (res.slots.Length == 0) return;
        var slot = res.slots[0];
        TudadaSDK.Instance.ShowRewardedAd(slot,
            onSuccess: (r) => { if (r.isEnded) GiveReward(); }, // 보상 지급은 게임이 직접
            onFail: (err) => Debug.LogError("리워드 실행 실패: " + err)
        );
    });

리워드 지급은 게임이 직접

isEnded 가 true 이면 보상 지급 대상이며, 실제 보상 지급은 게임이 직접 수행합니다. 로드 실패 시 플랫폼이 자동 재시도하고, 최종 실패 시 안내 팝업을 표시하므로 게임에서 별도 에러 UI를 구현할 필요가 없습니다.

`ShowRewardedAd(adUnitId, onSuccess, onFail)` (보상형 비디오)

슬롯 없이 보상형 비디오 광고만 한 번의 호출로 표시합니다. 광고 로드, 표시, 실패 시 재시도 및 안내를 플랫폼이 자동으로 처리합니다.

파라미터:

파라미터	타입	필수	설명
`adUnitId`	`string`	✅	광고 단위 ID
`onSuccess`	`Action<ShowRewardedAdResult>`	-	성공 콜백
`onFail`	`Action<string>`	-	실패 콜백

성공 응답 (ShowRewardedAdResult):

필드	타입	설명
`isEnded`	`bool`	광고 시청 완료 여부

TudadaSDK.Instance.ShowRewardedAd("ad-unit-id",
    onSuccess: (result) => {
        if (result.isEnded)
        {
            Debug.Log("보상 지급!");
            GiveReward();
        }
    },
    onFail: (err) => {
        Debug.LogError("광고 표시 실패: " + err);
    }
);

참고: 광고 로드 실패 시 플랫폼이 자동으로 재시도하고, 최종 실패 시 안내 팝업을 표시합니다. 게임에서 별도의 에러 처리 UI를 구현할 필요가 없습니다.

`CreateRewardedVideoAd(adUnitId)` (레거시)

보상형 비디오 광고 인스턴스를 생성합니다.

지원 종료 예정: 이 레거시 인스턴스 API는 통합 ShowRewardedAd() 로 대체됐으며 다음 버전에서 제거될 예정입니다([System.Obsolete] 특성 — 사용 시 컴파일 경고).

파라미터:

파라미터	타입	필수	설명
`adUnitId`	`string`	✅	광고 단위 ID

인스턴스 멤버 (TudadaRewardedVideoAd):

멤버	타입	설명
`Load(onSuccess?, onFail?)`	메서드	광고 로드
`Show(onSuccess?, onFail?)`	메서드	광고 표시
`Destroy()`	메서드	인스턴스 파괴
`IsLoaded`	`bool`	로드 완료 여부
`IsDestroyed`	`bool`	파괴 여부
`AdUnitId`	`string`	광고 단위 ID
`OnLoad`	이벤트	로드 완료
`OnError`	이벤트	에러 발생
`OnClose`	이벤트	닫기 (`isEnded` 포함)

// 광고 인스턴스 생성
TudadaRewardedVideoAd rewardedAd = TudadaSDK.Instance.CreateRewardedVideoAd("ad-unit-id");

// 이벤트 등록
rewardedAd.OnLoad += () => {
    Debug.Log("광고 로드 완료");
};

rewardedAd.OnError += (err) => {
    Debug.LogError("광고 에러: " + err.errMsg);
};

rewardedAd.OnClose += (result) => {
    if (result.isEnded)
    {
        // 사용자가 끝까지 시청 → 보상 지급
        Debug.Log("보상 지급!");
        GiveReward();
    }
    else
    {
        // 중간에 닫음
        Debug.Log("광고 중간 종료");
    }

    // 다음 광고를 위해 재로드
    rewardedAd.Load();
};

// 광고 로드
rewardedAd.Load(
    onSuccess: (result) => Debug.Log("로드 성공"),
    onFail: (err) => Debug.LogError("로드 실패: " + err)
);

광고 표시:

// 로드 완료 후 표시
if (rewardedAd.IsLoaded)
{
    rewardedAd.Show(
        onSuccess: (result) => Debug.Log("광고 표시"),
        onFail: (err) => Debug.LogError("표시 실패: " + err)
    );
}

중요: 사용이 끝난 광고 인스턴스는 Destroy()를 호출하여 정리하세요.

v0.2.0 통합 리워드 슬롯(action: "BANNER")으로 대체를 권장합니다. 아래 배너 API는 호환을 위해 유지됩니다.

배너 광고는 게임이 화면에 정의한 슬롯(예: "main_menu_top")에 광고를 받아 직접 그리는 방식입니다. SDK가 이미지 URL과 액션 처리만 담당하고, 렌더링·탭 감지·후처리는 게임이 자유롭게 통제합니다.

bannerId는 게임이 정의한 슬롯 이름을 겸하는 식별자입니다.
사용자가 배너를 탭하면 RunBannerAction(bannerId)을 호출해 액션 처리를 SDK에 위임합니다.
응답은 success / fail 신호만 받으며, 보상 등 후처리는 게임 내부에서 수행합니다.

`GetAvailableBannerIds(onSuccess, onFail)`

활성화된 배너 슬롯 ID 목록을 조회합니다.

파라미터:

파라미터	타입	필수	설명
`onSuccess`	`Action<GetAvailableBannerIdsResult>`	-	성공 콜백
`onFail`	`Action<string>`	-	실패 콜백

TudadaSDK.Instance.GetAvailableBannerIds(
    onSuccess: (result) => {
        foreach (var slotName in result.bannerIds)
        {
            Debug.Log("활성 슬롯: " + slotName);
        }
    },
    onFail: (err) => Debug.LogWarning("조회 실패: " + err)
);

`GetBanner(bannerId, onSuccess, onFail)`

슬롯 이름으로 그 슬롯에 매칭된 배너 데이터를 가져옵니다. 슬롯에 매칭된 광고가 없으면 onFail이 호출됩니다.

파라미터:

파라미터	타입	필수	설명
`bannerId`	`string`	✅	슬롯 이름을 겸하는 배너 ID
`onSuccess`	`Action<GetBannerResult>`	-	성공 콜백
`onFail`	`Action<string>`	-	실패 콜백 (매칭 없음 포함)

성공 응답 (GetBannerResult.banner):

필드	타입	설명
`bannerId`	`string`	슬롯 이름을 겸하는 배너 ID
`imageUrl`	`string`	배너 이미지 URL (게임이 직접 렌더링)
`expiresAt`	`long`	만료 시각 (Unix ms, 0이면 미설정)

TudadaSDK.Instance.GetBanner("main_menu_top",
    onSuccess: (result) => {
        // result.banner.imageUrl을 텍스처로 다운로드하여 UI에 표시
        StartCoroutine(LoadBannerTexture(result.banner.imageUrl));
    },
    onFail: (err) => Debug.LogWarning("이 슬롯에는 표시할 광고가 없습니다: " + err)
);

`RunBannerAction(bannerId, onSuccess, onFail)`

사용자가 배너를 탭한 시점에 게임이 호출합니다. SDK가 액션을 처리하고 success / fail 신호만 통지합니다.

보상 등 후처리는 게임 내부에서 수행합니다.

파라미터:

파라미터	타입	필수	설명
`bannerId`	`string`	✅	슬롯 이름을 겸하는 배너 ID
`onSuccess`	`Action`	-	성공 콜백 — 게임이 보상 지급 등 후처리
`onFail`	`Action<string>`	-	실패 콜백

// 사용자가 배너를 탭한 시점에 호출
bannerButton.onClick.AddListener(() => {
    TudadaSDK.Instance.RunBannerAction("main_menu_top",
        onSuccess: () => GrantReward(),
        onFail: (err) => Debug.LogError("처리 실패: " + err)
    );
});

Ad API​

통합 리워드 슬롯​

GetRewardedAdSlots(onSuccess, onFail)​

GetRewardedAdSlot(slotId, onSuccess, onFail)​

ShowRewardedAd(slot, onSuccess, onFail) (권장)​

ShowRewardedAd(adUnitId, onSuccess, onFail) (보상형 비디오)​

CreateRewardedVideoAd(adUnitId) (레거시)​

배너 광고 (슬롯 모델)​

GetAvailableBannerIds(onSuccess, onFail)​

GetBanner(bannerId, onSuccess, onFail)​

RunBannerAction(bannerId, onSuccess, onFail)​

Ad API

통합 리워드 슬롯

`GetRewardedAdSlots(onSuccess, onFail)`

`GetRewardedAdSlot(slotId, onSuccess, onFail)`

`ShowRewardedAd(slot, onSuccess, onFail)` (권장)

`ShowRewardedAd(adUnitId, onSuccess, onFail)` (보상형 비디오)

`CreateRewardedVideoAd(adUnitId)` (레거시)

배너 광고 (슬롯 모델)

`GetAvailableBannerIds(onSuccess, onFail)`

`GetBanner(bannerId, onSuccess, onFail)`

`RunBannerAction(bannerId, onSuccess, onFail)`