Skip to main content

​
Overview

Backfill ads automatically show alternative ads when direct ads are unavailable, maximizing ad revenue.

​
Configuration

​
1. Enable in Console

Enable backfill ads for your desired ad unit in Ad Control Console.

Backfill Ad Settings

Check how to enable backfill ads in the console

​
2. Verify Ads

After Adrop team approval, when the ad unit becomes Monetizing status, backfill ads will be automatically displayed.
On registered app domains, backfill ads will automatically display on configured ad placements without additional work.

​
How It Works

  1. SDK requests direct ads.
  2. If no direct ads are available (AD_NO_FILL), it automatically requests backfill ads.
  3. If no backfill ads are available, the AD_BACKFILL_NO_FILL event is fired.

​
Supported Formats

Currently, backfill ads only support banner format.
Ad Unit FormatBackfill Ad Format
BannerBanner
NativeBanner
Even in native units, backfill ads are displayed as banners.

​
Ad Size

Backfill ads automatically request creatives matching the container size.
  • Width: Initial matching
  • Height: Required (specify appropriate height)
  • Alignment: Horizontal center alignment supported

​
Development Environment Testing

​
localhost Testing

  • On localhost, you can make backfill ad requests if any ad unit connected to the app is Monetizing.
  • However, actual ads will not be delivered on localhost, and the AD_BACKFILL_NO_FILL event will be fired.
  • To receive actual backfill ads, you must test on an app-registered domain (not localhost).

​
Event Handling

You can handle backfill ad-related events. 
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) => {
      console.log('Ad received:', adData.format);  // 'banner', 'nativeAd', 'backfill'
    };

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

    // No backfill ad available
    const handleBackfillNoFill = (unit: string) => {
      console.warn('No backfill ad:', unit);
      // Handle UI, such as hiding ad area
    };

    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} />;
}

​
Key Events

EventConstantDescription
Ad ReceivedAD_RECEIVEDDirect or backfill ad received
No Direct AdAD_NO_FILLNo direct ads (backfill request started)
No BackfillAD_BACKFILL_NO_FILLNo backfill ad available

​
Distinguishing Ad Types

You can distinguish ad types using adData.format in the AD_RECEIVED event. 
adrop.on(Adrop.Events.AD_RECEIVED, (unit, adData) => {
  switch (adData.format) {
    case 'banner':
      console.log('Direct ad (banner)');
      break;
    case 'nativeAd':
      console.log('Direct ad (native)');
      break;
    case 'backfill':
      console.log('Backfill ad');
      break;
  }
});

​
Handling No Ads

Example of hiding the ad area when both direct and backfill ads are unavailable. 
import { useState, useEffect, useRef } from 'react';
import Adrop from '@adrop/ads-web-sdk';

function BannerAd({ unitId }: { unitId: string }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const [hasAd, setHasAd] = useState(true);

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

    const handleReceived = () => {
      setHasAd(true);
    };

    const handleBackfillNoFill = () => {
      setHasAd(false);  // Hide ad area
    };

    adrop.on(Adrop.Events.AD_RECEIVED, handleReceived, 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_BACKFILL_NO_FILL, handleBackfillNoFill);

    };
  }, [unitId]);

  if (!hasAd) return null;

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

Reference > Events

Event constant definitions

Reference > ErrorCode

Error code definitions