본문으로 건너뛰기

Ad API

Ad API​

보상형 비디오·배너·공유 등 리워드 액션은 v0.2.0부터 하나의 슬롯 모델로 통합되었습니다. 사전 조회 API(getRewardedAdSlots / getRewardedAdSlot)로 활성 슬롯을 받아 렌더링하고, 사용자가 탭하면 showRewardedAd({ slotId }) 한 번으로 실행합니다. 슬롯 없이 보상형 비디오 광고만 표시하려면 showRewardedAd({ adUnitId }) 를 그대로 사용할 수 있습니다.

showRewardedAd(options) (권장)​

보상형 광고/리워드를 한 번의 호출로 실행합니다. slotId 가 있으면 해당 슬롯의 액션 (영상/배너/공유)으로 실행하고, 없으면 adUnitId 를 사용한 보상형 비디오 광고로 실행합니다. 로드, 표시, 실패 시 재시도 및 안내를 플랫폼이 자동으로 처리합니다.

옵션:

파라미터타입필수설명
slotIdstring△리워드 슬롯 ID (getRewardedAdSlots / getRewardedAdSlot 에서 획득). 우선 처리됩니다.
adUnitIdstring△광고 단위 ID. slotId 미지정 시 보상형 비디오 광고로 실행합니다.
successfunction-성공 콜백
failfunction-실패 콜백
completefunction-완료 콜백

slotId 와 adUnitId 는 모두 선택이지만 최소 하나는 제공해야 합니다. 둘 다 있으면 slotId 가 우선합니다.

성공 응답:

필드타입설명
isEndedboolean리워드 완료 여부 (보상 지급 대상)
errMsgstring결과 메시지
// 1) 리워드 슬롯 실행 (권장)
TudadaSDK.showRewardedAd({
  slotId: slot.slotId,
  success: (res) => {
    if (res.isEnded) {
      giveReward();   // 보상 지급은 게임이 직접 수행
    }
  },
  fail: (err) => console.error('리워드 실행 실패:', err.errMsg),
});

// 2) 보상형 비디오 광고 직접 실행
TudadaSDK.showRewardedAd({
  adUnitId: 'your-ad-unit-id',
  success: (res) => {
    if (res.isEnded) giveReward();
  },
});

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

showRewardedAdAsync(options)​

showRewardedAd() 의 Promise 버전입니다. 옵션은 동일하며, 리워드 완료 여부를 Promise<ShowRewardedAdResult> 로 반환합니다.

const result = await TudadaSDK.showRewardedAdAsync({ slotId: slot.slotId });
if (result.isEnded) {
  giveReward();
}

통합 리워드 슬롯​

리워드 슬롯은 보상형 비디오·배너·공유를 하나의 모델로 다루는 v0.2.0 통합 API입니다. 게임은 활성 슬롯 목록을 받아 slotData 로 직접 렌더링하고, 사용자가 탭하면 showRewardedAd({ slotId }) 로 실행합니다.

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

필드타입설명
slotIdstring슬롯 식별자 (실행 시 지정)
actionstring액션 유형 ('REWARD_VIDEO' | 'BANNER' | 'SHARE')
slotDataobject?게임 렌더용 데이터 (선택)
slotData.imageUrlstring?슬롯 이미지 URL (게임이 직접 렌더링)
slotData.titlestring?슬롯 제목
slotData.expiresAtnumber?만료 시각 (Unix ms)

기본 보상형 비디오·공유 슬롯은 렌더링할 시각 요소가 없어 slotData 가 없을 수 있습니다. 배너 슬롯은 보통 slotData.imageUrl 을 포함합니다.

getRewardedAdSlots(options?)​

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

옵션:

파라미터타입필수설명
successfunction-성공 콜백
failfunction-실패 콜백
completefunction-완료 콜백

성공 응답:

필드타입설명
slotsRewardedAdSlot[]활성 슬롯 목록
errMsgstring결과 메시지
TudadaSDK.getRewardedAdSlots({
  success: ({ slots }) => {
    slots.forEach((slot) => {
      if (slot.slotData?.imageUrl) renderSlot(slot);
    });
  },
});

getRewardedAdSlotsAsync()​

getRewardedAdSlots() 의 Promise 버전입니다.

const { slots } = await TudadaSDK.getRewardedAdSlotsAsync();

getRewardedAdSlot(options)​

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

옵션:

파라미터타입필수설명
slotIdstring✅조회할 슬롯 ID
successfunction-성공 콜백
failfunction-실패 콜백 (슬롯 없음 포함)
completefunction-완료 콜백

성공 응답:

필드타입설명
slotRewardedAdSlot슬롯 정보
errMsgstring결과 메시지
TudadaSDK.getRewardedAdSlot({
  slotId: 'main_menu_reward',
  success: ({ slot }) => renderSlot(slot),
  fail: (err) => console.warn('슬롯 없음:', err.errMsg),
});

getRewardedAdSlotAsync(slotId)​

getRewardedAdSlot() 의 Promise 버전입니다. 슬롯 ID를 인자로 직접 전달하며, 슬롯이 없으면 reject됩니다.

try {
  const { slot } = await TudadaSDK.getRewardedAdSlotAsync('main_menu_reward');
  renderSlot(slot);
} catch (e) {
  // 슬롯에 표시할 리워드가 없음 — UI 비표시
}

전체 흐름:

// 1) 활성 슬롯 조회
const { slots } = await TudadaSDK.getRewardedAdSlotsAsync();

// 2) 슬롯 렌더링 (게임이 직접)
slots.forEach((slot) => {
  if (!slot.slotData?.imageUrl) return;
  const el = renderSlotButton(slot.slotData);

  // 3) 사용자 탭 시 실행
  el.onclick = async () => {
    const res = await TudadaSDK.showRewardedAdAsync({ slotId: slot.slotId });
    if (res.isEnded) giveReward();   // 보상 지급은 게임이 직접 수행
  };
});

createRewardedVideoAd(options) (레거시)​

지원 종료 예정 (Deprecated)

createRewardedVideoAd 는 레거시 API로 다음 버전에서 제거될 예정입니다. 통합 API showRewardedAd() 또는 showRewardedAdAsync() 를 사용하세요.

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

옵션:

파라미터타입필수설명
adUnitIdstring✅광고 단위 ID
multitonboolean-다중 인스턴스 모드

참고: 현재 단일 광고만 지원하며, 광고 ID는 플랫폼에서 제어하므로 adUnitId에는 임의의 문자열을 입력해도 됩니다.

인스턴스 메서드:

멤버타입설명
load()Promise<void>광고 로드
show()Promise<void>광고 표시
destroy()void인스턴스 파괴
onLoad(callback)void로드 완료 이벤트
onError(callback)void에러 이벤트
onClose(callback)void닫기 이벤트
offLoad(callback?)void로드 이벤트 해제
offError(callback?)void에러 이벤트 해제
offClose(callback?)void닫기 이벤트 해제
// 광고 인스턴스 생성
const rewardedAd = TudadaSDK.createRewardedVideoAd({
  adUnitId: 'your-ad-unit-id',
});

// 이벤트 리스너 등록
rewardedAd.onLoad(() => {
  console.log('광고 로드 완료');
});

rewardedAd.onError((err) => {
  console.error('광고 에러:', err.errMsg, err.errCode);
});

rewardedAd.onClose((res) => {
  if (res.isEnded) {
    // 사용자가 광고를 끝까지 시청함 → 보상 지급
    console.log('보상 지급!');
    giveReward();
  } else {
    // 사용자가 중간에 닫음
    console.log('광고 중간 종료');
  }
});

// 광고 로드 및 표시
rewardedAd.load()
  .then(() => rewardedAd.show())
  .catch((err) => console.error('광고 표시 실패:', err));
지원 종료 예정 (Deprecated)

배너 광고 API(getAvailableBannerIds / getBanner / runBannerAction)는 통합 리워드 슬롯으로 대체되었으며 호환을 위해 유지됩니다. 신규 연동은 getRewardedAdSlots() 로 슬롯을 받아 showRewardedAd({ slotId })(action=BANNER)로 실행하세요.

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

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

getAvailableBannerIds(options)​

활성화된 배너 슬롯 ID 목록을 조회합니다. 보통 게임은 자기 슬롯 이름을 알고 있으므로 이 API는 운영 메타데이터 용도입니다.

옵션:

파라미터타입필수설명
successfunction-성공 콜백
failfunction-실패 콜백
completefunction-완료 콜백

성공 응답:

필드타입설명
bannerIdsstring[]활성 슬롯 이름 배열
errMsgstring결과 메시지
TudadaSDK.getAvailableBannerIds({
  success: ({ bannerIds }) => {
    console.log('활성 슬롯:', bannerIds);
  },
});

getAvailableBannerIdsAsync()​

getAvailableBannerIds()의 Promise 버전입니다.

const { bannerIds } = await TudadaSDK.getAvailableBannerIdsAsync();

getBanner(options)​

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

옵션:

파라미터타입필수설명
bannerIdstring✅슬롯 이름을 겸하는 배너 ID
successfunction-성공 콜백
failfunction-실패 콜백 (매칭 없음 포함)
completefunction-완료 콜백

성공 응답:

필드타입설명
banner.bannerIdstring슬롯 이름을 겸하는 배너 ID
banner.imageUrlstring배너 이미지 URL (게임이 직접 렌더링)
banner.expiresAtnumber?만료 시각 (Unix ms, 선택)
errMsgstring결과 메시지
TudadaSDK.getBanner({
  bannerId: 'main_menu_top',
  success: ({ banner }) => {
    const img = document.createElement('img');
    img.src = banner.imageUrl;
    document.body.appendChild(img);
  },
  fail: (err) => {
    console.warn('이 슬롯에는 표시할 광고가 없습니다:', err.errMsg);
  },
});

getBannerAsync(bannerId)​

getBanner()의 Promise 버전입니다. 매칭되는 광고가 없으면 reject됩니다.

try {
  const { banner } = await TudadaSDK.getBannerAsync('main_menu_top');
  renderBanner(banner.imageUrl);
} catch (e) {
  // 슬롯에 매칭된 광고 없음 — UI 비표시
}

runBannerAction(options)​

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

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

옵션:

파라미터타입필수설명
bannerIdstring✅슬롯 이름을 겸하는 배너 ID
successfunction-성공 콜백 — 게임이 보상 지급 등 후처리
failfunction-실패 콜백
completefunction-완료 콜백
img.onclick = () => {
  TudadaSDK.runBannerAction({
    bannerId: 'main_menu_top',
    success: () => {
      grantReward();   // 게임 내부 보상 지급
    },
    fail: (err) => {
      showToast(err.errMsg);
    },
  });
};

runBannerActionAsync(bannerId)​

runBannerAction()의 Promise 버전입니다.

img.onclick = async () => {
  try {
    await TudadaSDK.runBannerActionAsync('main_menu_top');
    grantReward();
  } catch (e) {
    showToast('처리 실패');
  }
};