Popup Ads - Ad Control Help Center

Overview

Popup ads are an ad format that appears on screen at specific moments. They can be displayed at app launch, content load completion, specific events, etc. Users can dismiss by tapping the close button or selecting “Don’t show today”.

Features

Popup format displayed at center or bottom of screen
Image and video ad support
Close, dim (background) click, and “Don’t show today” options
Customizable background color, text color, etc.
Non-intrusive yet effective ad experience

Use test unit IDs in development. See the Test Unit IDs section.

Implementation Steps

Popup ads are implemented in 4 steps:

Initialize - Create AdropPopupAd instance
Set Listener - Set listener for receiving ad events
Load Ad - Request and receive ad
Show Ad - Display ad on screen

Basic Implementation

AdropPopupAd Class

AdropPopupAd is the main class for managing popup ads.

import { AdropPopupAd, type AdropPopupAdColors } from 'adrop-ads-react-native';

const popupAd = new AdropPopupAd(
  unitId: string,
  colors?: AdropPopupAdColors,
  useCustomClick?: boolean
);

Constructor Parameters

unitId

string

required

Popup ad unit ID. Use the unit ID created in the Ad Control console.

colors

AdropPopupAdColors

Options for customizing popup ad colors.

closeTextColor: Close button text color
hideForTodayTextColor: “Don’t show today” text color
backgroundColor: Popup background (dim) color

useCustomClick

boolean

default:"false"

Whether to use custom click handling. When set to true, only the onAdClicked callback is called instead of opening the default browser on ad click.

Basic Usage

import React, { useEffect, useState, useMemo } from 'react';
import { Button, View } from 'react-native';
import { AdropPopupAd, type AdropListener } from 'adrop-ads-react-native';

const App: React.FC = () => {
  const [popupAd, setPopupAd] = useState<AdropPopupAd>();
  const [isLoaded, setIsLoaded] = useState(false);

  const listener: AdropListener = useMemo(() => ({
    onAdReceived: (ad: AdropPopupAd) => {
      console.log('Popup ad received');
      setIsLoaded(true);
    },
    onAdFailedToReceive: (_: AdropPopupAd, errorCode: any) => {
      console.log('Popup ad failed to receive:', errorCode);
    },
    onAdClicked: (ad: AdropPopupAd) => {
      console.log('Popup ad clicked');
      // Close popup on click
      ad.close();
    },
  }), []);

  useEffect(() => {
    // 1. Create popup ad
    const ad = new AdropPopupAd('YOUR_POPUP_UNIT_ID');
    ad.listener = listener;
    setPopupAd(ad);

    // 2. Load ad
    ad.load();

    // Cleanup on unmount
    return () => {
      ad.destroy();
    };
  }, [listener]);

  // 3. Show ad
  const showAd = () => {
    if (popupAd && isLoaded) {
      popupAd.show();
    }
  };

  return (
    <View>
      <Button
        title="Show Popup Ad"
        onPress={showAd}
        disabled={!isLoaded}
      />
    </View>
  );
};

export default App;

AdropListener Interface

Listener interface for receiving popup ad events.

Recommended Callbacks

onAdReceived

(ad: AdropPopupAd) => void

Called on successful ad reception. You can call show() at this point.

onAdFailedToReceive

(ad: AdropPopupAd, errorCode?: any) => void

Called on ad reception failure. Check error code for failure reason.

Optional Callbacks

onAdImpression

(ad: AdropPopupAd) => void

Called when ad impression is recorded.

onAdClicked

(ad: AdropPopupAd) => void

Called when user clicks the ad. You can call ad.close() in this callback to dismiss the popup.

onAdWillPresentFullScreen

(ad: AdropPopupAd) => void

Called just before popup ad is displayed.

onAdDidPresentFullScreen

(ad: AdropPopupAd) => void

Called immediately after popup ad is displayed.

onAdWillDismissFullScreen

(ad: AdropPopupAd) => void

Called just before popup ad is dismissed.

onAdDidDismissFullScreen

(ad: AdropPopupAd) => void

Called immediately after popup ad is dismissed. Good time to preload next ad.

onAdFailedToShowFullScreen

(ad: AdropPopupAd, errorCode?: any) => void

Called on ad display failure. Check error code for failure reason.

onAdBackButtonPressed

(ad: AdropPopupAd) => void

Called when the user presses the back button while the ad is displayed. Android only.

onAdVideoStart

(ad: AdropPopupAd) => void

Called when a video ad starts playing.

onAdVideoEnd

(ad: AdropPopupAd) => void

Called when a video ad finishes playing.

Listener Implementation Example

const listener: AdropListener = useMemo(() => ({
  // Ad received successfully
  onAdReceived: (ad: AdropPopupAd) => {
    console.log('Popup ad received');
    console.log('Creative ID:', ad.creativeId);
    console.log('Campaign ID:', ad.campaignId);
    // Auto-show when ad is ready
    ad.show();
  },

  // Ad reception failed
  onAdFailedToReceive: (ad: AdropPopupAd, errorCode?: any) => {
    console.log('Popup ad failed to receive:', errorCode);
  },

  // Ad impression
  onAdImpression: (ad: AdropPopupAd) => {
    console.log('Popup ad impression');
    console.log('TX ID:', ad.txId);
    console.log('Destination URL:', ad.destinationURL);
  },

  // Ad clicked
  onAdClicked: (ad: AdropPopupAd) => {
    console.log('Popup ad clicked:', ad.destinationURL);
    // Close popup on click
    ad.close();
  },

  // Just before popup is displayed
  onAdWillPresentFullScreen: (ad: AdropPopupAd) => {
    console.log('Popup ad about to display');
  },

  // Popup displayed
  onAdDidPresentFullScreen: (ad: AdropPopupAd) => {
    console.log('Popup ad displayed');
  },

  // Just before popup is dismissed
  onAdWillDismissFullScreen: (ad: AdropPopupAd) => {
    console.log('Popup ad about to dismiss');
  },

  // Popup dismissed
  onAdDidDismissFullScreen: (ad: AdropPopupAd) => {
    console.log('Popup ad dismissed');
    // Preload next ad
    loadNextAd();
  },

  // Popup display failed
  onAdFailedToShowFullScreen: (ad: AdropPopupAd, errorCode?: any) => {
    console.log('Popup ad failed to show:', errorCode);
  },

  // Video ad started
  onAdVideoStart: (ad: AdropPopupAd) => {
    console.log('Video ad started playing:', ad.creativeId);
  },

  // Video ad ended
  onAdVideoEnd: (ad: AdropPopupAd) => {
    console.log('Video ad finished playing:', ad.creativeId);
  },
}), []);

Methods

load()

Requests and loads an ad.

popupAd.load();

show()

Displays the loaded ad. Can only be called after onAdReceived callback is fired.

popupAd.show();

Only call show() when the ad is loaded (isLoaded === true).

close()

Closes the currently displayed popup ad. Primarily used in the onAdClicked callback.

popupAd.close();

destroy()

Cleans up the ad instance and releases resources. Must be called on component unmount.

useEffect(() => {
  const ad = new AdropPopupAd('YOUR_UNIT_ID');
  setPopupAd(ad);

  return () => {
    ad.destroy();
  };
}, []);

Ad Properties

The following properties are available on the popup ad object:

unitId

string

Ad unit ID

isLoaded

boolean

Whether the ad is loaded

creativeId

string

Creative ID of the currently displayed ad

destinationURL

string

URL to navigate to on ad click

txId

string

Transaction ID (for ad impression tracking)

campaignId

string

Campaign ID

browserTarget

BrowserTarget

Browser target for ad click. BrowserTarget.EXTERNAL (0) opens the system browser, BrowserTarget.INTERNAL (1) opens an in-app browser.

Customization

Color Settings

Use AdropPopupAdColors type to customize popup ad colors.

import { AdropPopupAd, type AdropPopupAdColors } from 'adrop-ads-react-native';

// Define color options
const customColors: AdropPopupAdColors = {
  closeTextColor: '#FFFFFF',                    // Close button color
  hideForTodayTextColor: '#456789',             // "Don't show today" color
  backgroundColor: 'rgba(53, 255, 63, 0.3)',    // Background (dim) color
};

// Apply colors when creating popup ad
const popupAd = new AdropPopupAd(
  'YOUR_POPUP_UNIT_ID',
  customColors
);

AdropPopupAdColors Type

closeTextColor

string

Close button text color. Supports HEX color codes or RGBA format.

hideForTodayTextColor

string

“Don’t show today” text color. Supports HEX color codes or RGBA format.

backgroundColor

string

Popup background (dim) color. Supports HEX color codes or RGBA format. Transparency can be adjusted.

Custom Click Handling

To use custom handling instead of opening the default browser on ad click, use the useCustomClick parameter.

const listener: AdropListener = useMemo(() => ({
  onAdReceived: (ad: AdropPopupAd) => {
    ad.show();
  },
  onAdFailedToReceive: (_: AdropPopupAd, errorCode: any) => {
    console.log('Ad failed to receive:', errorCode);
  },
  onAdClicked: (ad: AdropPopupAd) => {
    // Custom click handling
    console.log('Ad clicked:', ad.destinationURL);

    // Handle URL as desired
    // e.g., Open in in-app browser
    openInAppBrowser(ad.destinationURL);

    // Close popup
    ad.close();
  },
}), []);

// Set useCustomClick to true
const popupAd = new AdropPopupAd(
  'YOUR_POPUP_UNIT_ID',
  undefined,  // colors
  true        // useCustomClick
);
popupAd.listener = listener;

Test Unit IDs

Use the following test unit IDs during development and testing.

Ad Type	Test Unit ID
Popup (Bottom Image)	`PUBLIC_TEST_UNIT_ID_POPUP_BOTTOM`
Popup (Center Image)	`PUBLIC_TEST_UNIT_ID_POPUP_CENTER`
Popup Video (Bottom 16:9)	`PUBLIC_TEST_UNIT_ID_POPUP_BOTTOM_VIDEO_16_9`
Popup Video (Bottom 9:16)	`PUBLIC_TEST_UNIT_ID_POPUP_BOTTOM_VIDEO_9_16`
Popup Video (Center 16:9)	`PUBLIC_TEST_UNIT_ID_POPUP_CENTER_VIDEO_16_9`
Popup Video (Center 9:16)	`PUBLIC_TEST_UNIT_ID_POPUP_CENTER_VIDEO_9_16`

Test Ad Usage Example

// Separate development/production environments
const POPUP_UNIT_ID = __DEV__
  ? 'PUBLIC_TEST_UNIT_ID_POPUP_BOTTOM'  // Test unit ID
  : 'YOUR_PRODUCTION_UNIT_ID';           // Production unit ID

const popupAd = new AdropPopupAd(POPUP_UNIT_ID);

Make sure to use the actual unit ID created in the Ad Control console for production releases.

Error Handling

Handle errors appropriately by checking error codes on ad load or display failure.

const listener: AdropListener = {
  onAdFailedToReceive: (ad: AdropPopupAd, errorCode?: any) => {
    console.error('Ad reception failed:', errorCode);

    switch (errorCode) {
      case AdropErrorCode.network:
        // Handle network error
        console.log('Please check your network connection');
        break;
      case AdropErrorCode.adNoFill:
        // Insufficient ad inventory
        console.log('No ads available to display');
        break;
      case AdropErrorCode.invalidUnit:
        // Invalid unit ID
        console.log('Please check your ad unit ID');
        break;
      default:
        console.log('Unable to load ad');
    }
  },

  onAdFailedToShowFullScreen: (ad: AdropPopupAd, errorCode?: any) => {
    console.error('Ad display failed:', errorCode);

    // Retry later
    setTimeout(() => {
      ad.load();
    }, 30000); // Retry after 30 seconds
  },
};

Best Practices

1. Appropriate Display Timing

Popup ads are most effective at these times:

// Good: App launch
useEffect(() => {
  const ad = new AdropPopupAd('YOUR_UNIT_ID');
  ad.listener = {
    onAdReceived: (ad) => ad.show(),
    onAdFailedToReceive: (_, error) => console.log(error),
  };
  ad.load();

  return () => ad.destroy();
}, []);

// Good: Content load completion
const onContentLoaded = () => {
  if (shouldShowPopupAd()) {
    popupAd?.show();
  }
};

// Good: Specific event completion
const onAchievementUnlocked = () => {
  popupAd?.show();
};

// Bad: While user is working
const onUserTyping = () => {
  popupAd?.show(); // Harms user experience
};

2. Frequency Limiting

Don’t show popup ads too frequently.

import AsyncStorage from '@react-native-async-storage/async-storage';

const LAST_SHOWN_KEY = 'popup_ad_last_shown';
const MINIMUM_INTERVAL = 3600000; // 1 hour (milliseconds)

// Check if ad can be shown
const canShowAd = async (): Promise<boolean> => {
  try {
    const lastShown = await AsyncStorage.getItem(LAST_SHOWN_KEY);
    if (!lastShown) return true;

    const currentTime = Date.now();
    const lastShownTime = parseInt(lastShown, 10);

    return currentTime - lastShownTime >= MINIMUM_INTERVAL;
  } catch (error) {
    return true;
  }
};

// Record ad shown
const recordAdShown = async () => {
  try {
    await AsyncStorage.setItem(LAST_SHOWN_KEY, Date.now().toString());
  } catch (error) {
    console.error('Error recording ad shown:', error);
  }
};

// Usage
const showAdIfAllowed = async () => {
  if (await canShowAd()) {
    popupAd?.show();
    await recordAdShown();
  }
};

3. Preload Ads

Preload ads for better user experience.

const [isAdReady, setIsAdReady] = useState(false);

useEffect(() => {
  // Preload at app launch
  const ad = new AdropPopupAd('YOUR_UNIT_ID');
  ad.listener = {
    onAdReceived: () => setIsAdReady(true),
    onAdFailedToReceive: (_, error) => console.log(error),
  };
  ad.load();

  setPopupAd(ad);
  return () => ad.destroy();
}, []);

// Show immediately at desired time
const showPopupNow = () => {
  if (isAdReady) {
    popupAd?.show();
  }
};

4. Memory Management

Always clean up ads on component unmount.

useEffect(() => {
  const ad = new AdropPopupAd('YOUR_UNIT_ID');
  setPopupAd(ad);

  // Cleanup function
  return () => {
    ad.destroy();
  };
}, []);

Close popup on ad click for better user experience.

const listener: AdropListener = {
  onAdClicked: (ad: AdropPopupAd) => {
    console.log('Ad clicked:', ad.destinationURL);
    // Auto-close popup on click
    ad.close();
  },
};

Troubleshooting

Ad Not Displaying

onAdReceived not called

Verify SDK is initialized
Check if unit ID is correct
Check network connection
Use test unit ID in test environment

onAdFailedToReceive is called

Check error code to identify cause
Retry later if ad inventory is insufficient
Verify native SDK is properly integrated

Nothing happens after show() is called

Verify show() is called after onAdReceived callback
Check isLoaded property to confirm ad is loaded
Verify native module is properly connected

Memory Leak

// Good: Using cleanup function
useEffect(() => {
  const ad = new AdropPopupAd('YOUR_UNIT_ID');
  setPopupAd(ad);

  return () => {
    ad.destroy();  // Must call
  };
}, []);

// Bad: Not cleaning up
useEffect(() => {
  const ad = new AdropPopupAd('YOUR_UNIT_ID');
  setPopupAd(ad);
  // No destroy() call - memory leak!
}, []);

Getting Started

SDK installation and initialization

Interstitial Ads

Implementing interstitial ads

Rewarded Ads

Implementing rewarded ads

Banner Ads

Implementing banner ads

​Overview

​Features

​Implementation Steps

​Basic Implementation

​AdropPopupAd Class

​Constructor Parameters

​Basic Usage

​AdropListener Interface

​Recommended Callbacks

​Optional Callbacks

​Listener Implementation Example

​Methods

​load()

​show()

​close()

​destroy()

​Ad Properties

​Customization

​Color Settings

​AdropPopupAdColors Type

​Custom Click Handling

​Test Unit IDs

​Test Ad Usage Example

​Error Handling

​Best Practices

​1. Appropriate Display Timing

​2. Frequency Limiting

​3. Preload Ads

​4. Memory Management

​5. Close Popup on Click

​Troubleshooting

​Ad Not Displaying

​Memory Leak

​Related Documentation

Getting Started

Interstitial Ads

Rewarded Ads

Banner Ads

Overview

Features

Implementation Steps

Basic Implementation

AdropPopupAd Class

Constructor Parameters

Basic Usage

AdropListener Interface

Recommended Callbacks

Optional Callbacks

Listener Implementation Example

Methods

load()

show()

close()

destroy()

Ad Properties

Customization

Color Settings

AdropPopupAdColors Type

Custom Click Handling

Test Unit IDs

Test Ad Usage Example

Error Handling

Best Practices

1. Appropriate Display Timing

2. Frequency Limiting

3. Preload Ads

4. Memory Management

5. Close Popup on Click

Troubleshooting

Ad Not Displaying

Memory Leak

Related Documentation