Skip to main content

TossAds.attachBanner

Attaches a banner ad slot to a DOM element and returns a result object containing a destroy function. This is the recommended replacement for the deprecated TossAds.attach.

Signature​

attachBanner is exposed as a member of the TossAds namespace object.

import { TossAds } from '@apps-in-toss/web-framework';

declare const TossAds: {
  attachBanner: ((
    adGroupId: string,
    target: string | HTMLElement,
    options?: AttachBannerOptions,
  ) => AttachBannerResult) & {
    isSupported: () => boolean;
  };
};

interface AttachBannerOptions {
  theme?: 'auto' | 'light' | 'dark';
  tone?: 'blackAndWhite' | 'grey';
  variant?: 'card' | 'expanded';
  callbacks?: BannerSlotCallbacks;
}

interface AttachBannerResult {
  destroy: () => void;
}

Parameters​

NameTypeRequiredDescription
adGroupIdstring✓Ad group unit ID issued from the console.
targetstring | HTMLElement✓DOM element or CSS selector string to insert the ad into.
optionsAttachBannerOptions—Theme, tone, layout variant, and callback options.
options.theme'auto' | 'light' | 'dark'—Ad theme.
options.tone'blackAndWhite' | 'grey'—Ad color tone.
options.variant'card' | 'expanded'—Ad layout variant.
options.callbacksBannerSlotCallbacks—Callbacks for rendered, viewable, clicked, impression, and failed events.

Returns​

  • AttachBannerResult — { destroy: () => void }. Call destroy to remove the slot from the DOM.

Permission​

No permission required — TossAds.attachBanner is not bound to a PermissionName. For the typical permission flow used by other namespaces, see Guides — Permissions pattern.

Examples​

Minimal​

import { TossAds } from '@apps-in-toss/web-framework';

const { destroy } = TossAds.attachBanner('ad-group-id-here', '#ad-container');

// Remove the slot when no longer needed
destroy();

Realistic — banner ad in a React component​

import { TossAds } from '@apps-in-toss/web-framework';
import { useEffect, useRef } from 'react';

const AD_GROUP_ID = 'ad-group-id-here';

function AdBanner() {
  const containerRef = useRef<HTMLDivElement>(null);

  useEffect(() => {
    if (!containerRef.current) return;
    if (!TossAds.attachBanner.isSupported()) return;

    const { destroy } = TossAds.attachBanner(AD_GROUP_ID, containerRef.current, {
      theme: 'auto',
      callbacks: {
        onAdRendered: (payload) => {
          console.log('Ad rendered', payload.slotId);
        },
        onAdFailedToRender: (payload) => {
          console.error('Ad failed to render', payload.error.message);
        },
      },
    });

    // Clean up the slot on component unmount
    return destroy;
  }, []);

  return <div ref={containerRef} />;
}

Try it live​

Open the Ads page in sdk-example to try ad-related APIs live.

Open in sdk-example

External references​