Banner Ads

Implementation Methods

You can implement banner ads in two ways.

Method	Description	Recommended
Data Attributes	Simple implementation using HTML attributes only	Quick implementation
renderAd	Direct control over ad loading timing	When fine-grained control is needed

Use the test unit ID in development: PUBLIC_TEST_UNIT_ID_320_100

1. Data Attributes Method

The simplest method - just add the data-adrop-unit attribute and the SDK will automatically load the ad.

function BannerAd() {
  return (
    <div
      data-adrop-unit="YOUR_UNIT_ID"
      data-adrop-context-id="YOUR_CONTEXT_ID"
      data-adrop-theme="light"
      data-adrop-custom-click="true"  // Enable custom click handling
    />
  );
}

Data Attributes

string

required

Unit ID created in Ad Control Console

string

Context ID for Contextual Targeting

string

default:"light"

Theme setting (light or dark) - See Dark Mode Settings

boolean

default:false

Enable custom click handling - When true, SDK will not automatically navigate to the destination URL on click, only emit adClicked event with destination URL. Allows developers to implement custom click behavior.

string

default:"responsive"

Backfill ad rendering mode (responsive or fixed). See the Backfill Rendering Mode guide for details. (SDK 1.2.3+)

string

Advertising identifier — required for the View on Device feature to preview a draft creative on a registered test device. Do not hard-code in production.

Refreshing Ads

Change the React key to remount the component and request a new ad.

function App() {
  const [adKey, setAdKey] = useState(0);

  const reloadAd = () => {
    setAdKey(prev => prev + 1);
  };

  return (
    <>
      <div key={adKey} data-adrop-unit="YOUR_UNIT_ID" />
      <button onClick={reloadAd}>Refresh Ad</button>
    </>
  );
}

2. renderAd Method

Use this when you want direct control over ad loading timing.

import { useEffect, useRef } from 'react';
import { Adrop } from '@adrop/ads-web-sdk';

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

  useEffect(() => {
    const adrop = Adrop.instance();

    if (containerRef.current) {
      adrop.renderAd(containerRef.current, {
        unit: 'YOUR_UNIT_ID',
        contextId: 'YOUR_CONTEXT_ID',
        theme: 'light',
        useCustomClick: true  // Enable custom click handling
      });
    }

  }, []);

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

renderAd Options

string

required

Unit ID created in Ad Control Console

string

User identifier (used to override SDK-level setting for individual placements)

string

Context ID for Contextual Targeting

string

default:"light"

Theme setting (light or dark) - See Dark Mode Settings

boolean

default:false

'responsive' | 'fixed'

default:"responsive"

Backfill ad rendering mode. See the Backfill Rendering Mode guide for details. (SDK 1.2.3+)

string

Advertising identifier — required for the View on Device feature to preview a draft creative on a registered test device. Do not hard-code in production.

Refreshing Ads

Call renderAd() again to request a new ad. Can also be used on placements created with Data Attributes.

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

  const reloadAd = () => {
    const adrop = Adrop.instance();
    if (containerRef.current) {
      adrop.renderAd(containerRef.current, {
        unit: 'YOUR_UNIT_ID'
      });
    }
  };

  return (
    <>
      <div ref={containerRef} />
      <button onClick={reloadAd}>Refresh Ad</button>
    </>
  );
}

When calling renderAd() on a placement created with Data Attributes, you only need to pass items that don’t exist in data attributes or items you want to modify.

Removing Ads

Call clear() to remove the ad from the container.

const adrop = Adrop.instance();
adrop.clear(containerRef.current);

Ad Size

Recommended: responsive width + aspect-ratio matching the registered unit size. The slot scales with the device width and the height is locked by the ratio (no CLS).

<div
  data-adrop-unit="YOUR_UNIT_ID"
  data-adrop-backfill-mode="fixed"
  style={{ width: '100%', aspectRatio: '320 / 100' }}
/>

Fixed pixel size is also supported when pixel-precise alignment is required.

<div
  data-adrop-unit="YOUR_UNIT_ID"
  style={{ width: 320, height: 100 }}
/>

Type	Size Setting	Alignment
Direct Ads	Responsive support, height required	Horizontal/Vertical center
Backfill Ads	Auto-matched to container width (`responsive`) or stretched to container height (`fixed`)	Horizontal center

For container sizing patterns and how to choose a backfill rendering mode, see the Backfill Rendering Mode guide.

Event Handling

You can detect ad status changes and handle the UI appropriately.

import { useEffect, useRef } from 'react';
import { Adrop } from '@adrop/ads-web-sdk';

function BannerAd({ unitId }: { unitId: string }) {
  const containerRef = useRef<HTMLDivElement>(null);

  useEffect(() => {
    const adrop = Adrop.instance();

    // Ad received successfully
    const handleReceived = (unit: string, adData: any) => {
      console.log('Ad received:', unit);
    };

    // No direct ads available
    const handleNoFill = (unit: string) => {
      console.warn('No ad available:', unit);
    };

    // Request failed
    const handleFailed = (unit: string) => {
      console.error('Ad failed:', unit);
    };

    // Impression
    const handleImpression = (unit: string, adData: any) => {
      console.log('Ad impression:', unit);
    };

    // Click
    const handleClicked = (unit: string, adData: any) => {
      console.log('Ad clicked:', unit);
    };

    // No backfill ad available
    const handleBackfillNoFill = (unit: string) => {
      console.warn('No backfill ad:', unit);
    };

    // Video playback started
    const handleVideoStart = (unit: string, adData: any) => {
      console.log('Video started:', unit);
    };

    // Video playback ended
    const handleVideoEnd = (unit: string, adData: any) => {
      console.log('Video ended:', unit);
    };

    // Filter for specific unit only
    const filter = { unit: unitId };

    adrop.on(Adrop.Events.AD_RECEIVED, handleReceived, filter);
    adrop.on(Adrop.Events.AD_NO_FILL, handleNoFill, filter);
    adrop.on(Adrop.Events.AD_FAILED, handleFailed, filter);
    adrop.on(Adrop.Events.AD_IMPRESSION, handleImpression, filter);
    adrop.on(Adrop.Events.AD_CLICKED, handleClicked, filter);
    adrop.on(Adrop.Events.AD_BACKFILL_NO_FILL, handleBackfillNoFill, filter);
    adrop.on(Adrop.Events.AD_VIDEO_START, handleVideoStart, filter);
    adrop.on(Adrop.Events.AD_VIDEO_END, handleVideoEnd, filter);

    if (containerRef.current) {
      adrop.renderAd(containerRef.current, { unit: unitId });
    }

    return () => {
      adrop.off(Adrop.Events.AD_RECEIVED, handleReceived);
      adrop.off(Adrop.Events.AD_NO_FILL, handleNoFill);
      adrop.off(Adrop.Events.AD_FAILED, handleFailed);
      adrop.off(Adrop.Events.AD_IMPRESSION, handleImpression);
      adrop.off(Adrop.Events.AD_CLICKED, handleClicked);
      adrop.off(Adrop.Events.AD_BACKFILL_NO_FILL, handleBackfillNoFill);
      adrop.off(Adrop.Events.AD_VIDEO_START, handleVideoStart);
      adrop.off(Adrop.Events.AD_VIDEO_END, handleVideoEnd);
    };
  }, [unitId]);

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

Supported Events

Event	Constant	Description
Ad Received	`AD_RECEIVED`	Ad request successful
No Ad	`AD_NO_FILL`	No direct ads available
Request Failed	`AD_FAILED`	Ad request failed
Impression	`AD_IMPRESSION`	Ad impression recorded
Click	`AD_CLICKED`	User clicked the ad
No Backfill	`AD_BACKFILL_NO_FILL`	No backfill ad available
Video Start	`AD_VIDEO_START`	Video ad playback started
Video End	`AD_VIDEO_END`	Video ad playback ended

Always remove event listeners using off() when the component unmounts.

AdData

Ad data passed to event handlers. See Reference > AdData for detailed field information.

Custom Click Handling

When useCustomClick is enabled, the SDK will not automatically navigate to the destination URL. Instead, you can handle the click event and implement custom behavior.

import { useEffect, useRef } from 'react';
import { Adrop } from '@adrop/ads-web-sdk';

function CustomClickBannerAd({ unitId }: { unitId: string }) {
  const containerRef = useRef<HTMLDivElement>(null);

  useEffect(() => {
    const adrop = Adrop.instance();
    const filter = { unit: unitId };

    // Handle ad click with custom behavior
    const handleClicked = (unit: string, adData: any) => {
      console.log('Ad clicked:', unit);
      console.log('Destination URL:', adData.destinationURL);
      
      // Implement custom click behavior
      // For example: show confirmation dialog, track analytics, etc.
      const userConfirmed = confirm('Do you want to visit the advertiser page?');
      if (userConfirmed && adData.destinationURL) {
        window.open(adData.destinationURL, '_blank');
      }
    };

    adrop.on(Adrop.Events.AD_CLICKED, handleClicked, filter);

    if (containerRef.current) {
      adrop.renderAd(containerRef.current, {
        unit: unitId,
        useCustomClick: true
      });
    }

    return () => {
      adrop.off(Adrop.Events.AD_CLICKED, handleClicked);
    };
  }, [unitId]);

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

With custom click handling enabled, you have full control over what happens when users click the ad. The destinationURL is provided in the adClicked event data.

Complete Example

BannerAd.tsx

import { useEffect, useRef } from 'react';
import { Adrop } from '@adrop/ads-web-sdk';

interface BannerAdProps {
  unitId: string;
  contextId?: string;
  theme?: 'light' | 'dark';
  onReceived?: (adData: any) => void;
  onFailed?: () => void;
  onClicked?: () => void;
}

function BannerAd({
  unitId,
  contextId,
  theme = 'light',
  onReceived,
  onFailed,
  onClicked
}: BannerAdProps) {
  const containerRef = useRef<HTMLDivElement>(null);

  useEffect(() => {
    const adrop = Adrop.instance();
    const filter = { unit: unitId };

    const handleReceived = (_: string, adData: any) => onReceived?.(adData);
    const handleFailed = () => onFailed?.();
    const handleClicked = () => onClicked?.();

    adrop.on(Adrop.Events.AD_RECEIVED, handleReceived, filter);
    adrop.on(Adrop.Events.AD_FAILED, handleFailed, filter);
    adrop.on(Adrop.Events.AD_CLICKED, handleClicked, filter);

    if (containerRef.current) {
      adrop.renderAd(containerRef.current, {
        unit: unitId,
        contextId,
        theme
      });
    }

    return () => {
      adrop.off(Adrop.Events.AD_RECEIVED, handleReceived);
      adrop.off(Adrop.Events.AD_FAILED, handleFailed);
      adrop.off(Adrop.Events.AD_CLICKED, handleClicked);
    };
  }, [unitId, contextId, theme]);

  return <div ref={containerRef} className="banner-ad-container" />;
}

export default BannerAd;

Usage Example

import BannerAd from './components/BannerAd';

function App() {
  return (
    <div>
      <header>
        <BannerAd
          unitId="HEADER_BANNER_UNIT_ID"
          onClicked={() => console.log('Header banner clicked')}
        />
      </header>

      <main>
        <h1>Content</h1>
      </main>

      <footer>
        <BannerAd
          unitId="FOOTER_BANNER_UNIT_ID"
          theme="dark"
        />
      </footer>
    </div>
  );
}

Backfill Ads

When backfill ads are enabled, they are automatically requested when no direct ads are available. You can distinguish ad types using adData.format.

import { useEffect, useRef } from 'react';
import { Adrop } from '@adrop/ads-web-sdk';

function BannerAd({ unitId }: { unitId: string }) {
  const containerRef = useRef<HTMLDivElement>(null);

  useEffect(() => {
    const adrop = Adrop.instance();
    const filter = { unit: unitId };

    // Ad received (direct or backfill)
    const handleReceived = (unit: string, adData: any) => {
      if (adData.format === 'backfill') {
        console.log('Backfill ad loaded');
      } else {
        console.log('Direct ad loaded');
      }
    };

    // No direct ad (backfill request starts)
    const handleNoFill = (unit: string) => {
      console.log('No direct ad available, requesting backfill...');
    };

    // No backfill ad either
    const handleBackfillNoFill = (unit: string) => {
      console.warn('No backfill ad available either');
      // Hide ad area, etc.
    };

    adrop.on(Adrop.Events.AD_RECEIVED, handleReceived, filter);
    adrop.on(Adrop.Events.AD_NO_FILL, handleNoFill, filter);
    adrop.on(Adrop.Events.AD_BACKFILL_NO_FILL, handleBackfillNoFill, filter);

    if (containerRef.current) {
      adrop.renderAd(containerRef.current, { unit: unitId });
    }

    return () => {
      adrop.off(Adrop.Events.AD_RECEIVED, handleReceived);
      adrop.off(Adrop.Events.AD_NO_FILL, handleNoFill);
      adrop.off(Adrop.Events.AD_BACKFILL_NO_FILL, handleBackfillNoFill);
    };
  }, [unitId]);

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

Development Environment Testing: If at least one ad unit connected to the app is Monetizing, backfill ad requests can be made from localhost. On unapproved domains, an AD_BACKFILL_NO_FILL event will be triggered.

SDK Guide

AI

Android

iOS

React Native

Flutter

Web

REST API

Implementation Methods

1. Data Attributes Method

Data Attributes

Refreshing Ads

2. renderAd Method

renderAd Options

Refreshing Ads

Removing Ads

Ad Size

Event Handling

Supported Events

AdData

Custom Click Handling

Complete Example

BannerAd.tsx

Usage Example

Backfill Ads

​Implementation Methods

​1. Data Attributes Method

​Data Attributes

​Refreshing Ads

​2. renderAd Method

​renderAd Options

​Refreshing Ads

​Removing Ads

​Ad Size

​Event Handling

​Supported Events

​AdData

​Custom Click Handling

​Complete Example

​BannerAd.tsx

​Usage Example

​Backfill Ads

Implementation Methods

1. Data Attributes Method

Data Attributes

Refreshing Ads

2. renderAd Method

renderAd Options

Refreshing Ads

Removing Ads

Ad Size

Event Handling

Supported Events

AdData

Custom Click Handling

Complete Example

BannerAd.tsx

Usage Example

Backfill Ads