TossAds

인라인 배너 광고 SDK예요. initialize로 초기화한 뒤 attachBanner로 슬롯에 배너를 붙여요.

TossAds.initialize

기능 설명

토스 배너 광고 SDK를 초기화해요. 초기화는 비동기로 진행되며 결과는 콜백으로 전달돼요. 배너를 부착하기 전에 반드시 한 번 호출해야 해요. 이미 초기화된 상태에서 다시 호출하면 중복 초기화 없이 onInitialized 콜백이 바로 호출돼요(멱등).

토스앱 5.239.0 이상에서 사용할 수 있어요. 호출 전에 TossAds.initialize.isSupported()로 지원 여부를 확인할 수 있어요.

타입

TossAds.initialize(options: TossAdsInitializeOptions): void;

Params

interface TossAdsInitializeOptions {
  callbacks?: {
    /** 초기화 성공 시 호출돼요. */
    onInitialized?: () => void;
    /** 초기화 실패 시 호출돼요. */
    onInitializationFailed?: (error: Error) => void;
  };
}

Response

없음.

에러

SDK 스크립트 로드나 초기화에 실패하면 onInitializationFailed 콜백으로 에러가 전달돼요.

예시 코드

import { Ads } from "@apps-in-toss/web-framework";

function initializeAds() {
  if (!TossAds.initialize.isSupported()) {
    console.warn("현재 환경에서는 배너 광고를 사용할 수 없어요.");
    return;
  }

  TossAds.initialize({
    callbacks: {
      onInitialized: () => {
        console.log("배너 광고 SDK 초기화 완료");
      },
      onInitializationFailed: (error) => {
        console.error("배너 광고 SDK 초기화 실패:", error);
      },
    },
  });
}

TossAds.attach

deprecated: TossAds.attach는 더 이상 권장되지 않아요. TossAds.attachBanner를 사용하세요.

기능 설명

특정 DOM 요소에 배너 광고를 부착해요. TossAds.initialize를 먼저 호출해서 SDK를 초기화한 후에 사용해야 해요.

토스앱 5.239.0 이상에서 사용할 수 있어요. 호출 전에 TossAds.attach.isSupported()로 지원 여부를 확인할 수 있어요.

타입

TossAds.attach(
  adGroupId: string,           // 광고 그룹 ID (앱인토스 콘솔에서 발급)
  target: string | HTMLElement, // DOM 셀렉터 또는 HTMLElement
  options?: TossAdsAttachOptions,
): void;

Params

interface TossAdsAttachOptions {
  /** 테마 설정이에요. 생략하면 시스템 기본값을 따라요. */
  theme?: "light" | "dark";
  /** CSS padding 값이에요 (예: '20px', '10px 20px'). List Banner 타입에만 적용돼요. */
  padding?: string;
  /** 배너 이벤트 콜백이에요. */
  callbacks?: TossAdsBannerSlotCallbacks;
}

Response

없음.

에러

빈 adGroupId, 초기화 전 호출, 존재하지 않는 target 등 부착에 실패하면 callbacks.onAdFailedToRender 콜백으로 에러가 전달돼요.

예시 코드

import { Ads } from "@apps-in-toss/web-framework";

let slotId = null;

TossAds.attach("AD_GROUP_ID", "#banner-container", {
  padding: "20px",
  callbacks: {
    onAdRendered: (payload) => {
      slotId = payload.slotId; // 나중에 TossAds.destroy에 사용
    },
    onAdFailedToRender: (payload) => {
      console.error("광고 렌더링 실패:", payload.error.message);
    },
  },
});

TossAds.attachBanner

기능 설명

스타일 프리셋(배경색, 라운딩, 패딩)이 적용된 배너 광고를 DOM 요소에 부착해요. TossAds.initialize를 먼저 호출해서 SDK를 초기화한 후에 사용해야 해요.

같은 요소에 attachBanner를 중복 호출하면 새로 부착하지 않고 기존 배너의 핸들을 그대로 반환해요. 다른 옵션으로 다시 부착하려면 기존 핸들의 destroy()를 먼저 호출해야 해요.

토스앱 5.239.0 이상에서 사용할 수 있어요. 호출 전에 TossAds.attachBanner.isSupported()로 지원 여부를 확인할 수 있어요.

타입

TossAds.attachBanner(
  adGroupId: string,           // 광고 그룹 ID (앱인토스 콘솔에서 발급)
  target: string | HTMLElement, // DOM 셀렉터 또는 HTMLElement
  options?: TossAdsAttachBannerOptions,
): TossAdsAttachBannerResult;

Params

interface TossAdsAttachBannerOptions {
  /** 테마 오버라이드예요. 기본값은 'auto'로, 시스템 다크 모드를 따라요. */
  theme?: "auto" | "light" | "dark";
  /** 배경 색상 톤이에요. 기본값은 'blackAndWhite'예요. */
  tone?: "blackAndWhite" | "grey";
  /** 배너 형태예요. 'card'는 라운딩과 좌우 여백이 있는 카드형, 'expanded'는 가로로 꽉 찬 형태예요. 기본값은 'expanded'예요. */
  variant?: "card" | "expanded";
  /** 배너 이벤트 콜백이에요. */
  callbacks?: TossAdsBannerSlotCallbacks;
}

interface TossAdsBannerSlotCallbacks {
  /** 광고가 렌더링됐을 때 호출돼요. slotId를 여기서 받아 저장할 수 있어요. */
  onAdRendered?: (payload: TossAdsBannerSlotEventPayload) => void;
  /** 광고가 화면에 노출됐을 때 호출돼요. */
  onAdViewable?: (payload: TossAdsBannerSlotEventPayload) => void;
  /** 사용자가 광고를 클릭했을 때 호출돼요. */
  onAdClicked?: (payload: TossAdsBannerSlotEventPayload) => void;
  /** 광고 노출이 기록됐을 때 호출돼요. (수익 발생 시점) */
  onAdImpression?: (payload: TossAdsBannerSlotEventPayload) => void;
  /** 광고 렌더링에 실패했을 때 호출돼요. */
  onAdFailedToRender?: (payload: TossAdsBannerSlotErrorPayload) => void;
  /** 표시할 광고가 없을 때 호출돼요. */
  onNoFill?: (payload: {
    slotId: string;
    adGroupId: string;
    adMetadata: Record<string, never>;
  }) => void;
}

interface TossAdsBannerSlotEventPayload {
  slotId: string; // 생성된 슬롯 ID. TossAds.destroy에 전달할 수 있어요.
  adGroupId: string; // 광고 그룹 ID
  adMetadata: {
    creativeId: string;
    requestId: string;
  };
}

interface TossAdsBannerSlotErrorPayload {
  slotId: string;
  adGroupId: string;
  adMetadata: Record<string, never>;
  error: { code: number; message: string; domain?: string };
}

Response

interface TossAdsAttachBannerResult {
  /** 부착한 배너와 래퍼 요소를 함께 제거해요. */
  destroy: () => void;
}

에러

빈 adGroupId, 초기화 전 호출, 존재하지 않는 target 등 부착에 실패하면 callbacks.onAdFailedToRender 콜백으로 에러가 전달되고, 아무 동작도 하지 않는 destroy를 가진 결과가 반환돼요.

예시 코드

import { Ads } from "@apps-in-toss/web-framework";

const container = document.querySelector("#banner-container");

const banner = TossAds.attachBanner("AD_GROUP_ID", container, {
  variant: "card",
  tone: "grey",
  callbacks: {
    onAdRendered: (payload) => {
      console.log("광고 렌더링 완료:", payload.slotId);
    },
    onAdImpression: () => {
      console.log("광고 노출 기록됨 (수익 발생)");
    },
    onNoFill: () => {
      console.warn("표시할 광고가 없어요.");
    },
    onAdFailedToRender: (payload) => {
      console.error("광고 렌더링 실패:", payload.error.message);
    },
  },
});

// 화면을 떠날 때 배너 제거
window.addEventListener("pagehide", () => {
  banner.destroy();
});

TossAds.destroy

기능 설명

특정 슬롯 ID의 배너를 제거해요. slotId는 배너 콜백의 payload.slotId로 받을 수 있어요. SDK가 초기화되지 않았으면 아무 동작도 하지 않아요.

토스앱 5.239.0 이상에서 사용할 수 있어요. 호출 전에 TossAds.destroy.isSupported()로 지원 여부를 확인할 수 있어요.

타입

TossAds.destroy(slotId: string): void;

Params

제거할 슬롯 ID예요.

Response

없음.

예시 코드

import { Ads } from "@apps-in-toss/web-framework";

let slotId = null;

TossAds.attachBanner("AD_GROUP_ID", "#banner-container", {
  callbacks: {
    onAdRendered: (payload) => {
      slotId = payload.slotId;
    },
  },
});

// 특정 배너 제거
function removeBanner() {
  if (slotId) {
    TossAds.destroy(slotId);
    slotId = null;
  }
}

TossAds.destroyAll

기능 설명

초기화된 모든 배너 슬롯을 한 번에 제거해요. attachBanner로 부착한 배너의 내부 상태도 함께 초기화되므로, 이후 같은 요소에 다시 부착할 수 있어요. SDK가 초기화되지 않았으면 아무 동작도 하지 않아요.

토스앱 5.239.0 이상에서 사용할 수 있어요. 호출 전에 TossAds.destroyAll.isSupported()로 지원 여부를 확인할 수 있어요.

타입

TossAds.destroyAll(): void;

Params

없음

Response

없음.

예시 코드

import { Ads } from "@apps-in-toss/web-framework";

// 페이지를 떠날 때 모든 배너 제거
window.addEventListener("pagehide", () => {
  TossAds.destroyAll();
});