Interstitial Ads - Ad Control Help Center

Overview

Interstitial ads are ads that cover the entire app screen. They are suitable for natural transition points in the app, such as level transitions in games or content page transitions.

Features

Immersive ads covering the full screen
Maintained until user explicitly closes
Support for image and video ads
High visual attention

Use test unit ID in development: PUBLIC_TEST_UNIT_ID_INTERSTITIAL

Implementation Methods

Adrop React Native SDK provides two ways to implement interstitial ads:

Class Method - Direct use of AdropInterstitialAd class
Hook Method - Using useAdropInterstitialAd Hook (Recommended)

AdropInterstitialAd Class

Constructor

Create an AdropInterstitialAd instance.

import { AdropInterstitialAd } from 'adrop-ads-react-native'

const interstitialAd = new AdropInterstitialAd(unitId)

unitId

string

required

Ad unit ID (issued from console)

Properties

isLoaded

boolean

Returns whether the ad is loaded.

if (interstitialAd.isLoaded) {
  // Ad can be shown
}

unitId

string

Returns the ad unit ID.

const unitId = interstitialAd.unitId

creativeId

string

Returns the creative ID of the currently loaded ad.

const creativeId = interstitialAd.creativeId

txId

string

Returns the transaction ID of the currently loaded ad.

const txId = interstitialAd.txId

campaignId

string

Returns the campaign ID of the currently loaded ad.

const campaignId = interstitialAd.campaignId

destinationURL

string

Returns the destination URL of the currently loaded ad.

const destinationURL = interstitialAd.destinationURL

browserTarget

BrowserTarget

Returns the browser target setting of the currently loaded ad (BrowserTarget.EXTERNAL or BrowserTarget.INTERNAL).

const browserTarget = interstitialAd.browserTarget

listener

AdropListener

Sets the listener to receive ad events.

interstitialAd.listener = {
  onAdReceived: (ad) => console.log('Ad received'),
  onAdFailedToReceive: (ad, errorCode) => console.log('Reception failed', errorCode),
  // ... other callbacks
}

Methods

load()

() => void

Requests and loads the ad.

interstitialAd.load()

show()

() => void

Shows the loaded ad. Should be called when isLoaded is true.

if (interstitialAd.isLoaded) {
  interstitialAd.show()
}

close()

() => void

Closes the currently displayed ad. Useful for handling back button press on Android.

interstitialAd.close()

destroy()

() => void

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

useEffect(() => {
  return () => {
    interstitialAd?.destroy()
  }
}, [interstitialAd])

AdropListener Interface

Callback interface for receiving ad events.

Recommended Callbacks

onAdReceived

(ad: AdropAd) => void

Called when ad reception is successful. At this point, you can call show() to display the ad.

onAdReceived: (ad) => {
  console.log('Ad received:', ad.unitId)
  // Ad ready to show
}

onAdFailedToReceive

(ad: AdropAd, errorCode?: string) => void

Called when ad reception fails. You can check the failure reason through the error code.

onAdFailedToReceive: (ad, errorCode) => {
  console.log('Ad reception failed:', errorCode)
}

Optional Callbacks

onAdImpression

(ad: AdropAd) => void

Called when ad impression is recorded.

onAdImpression: (ad) => {
  console.log('Ad impression recorded')
}

onAdClicked

(ad: AdropAd) => void

Called when user clicks the ad.

onAdClicked: (ad) => {
  console.log('Ad clicked')
}

onAdWillPresentFullScreen

(ad: AdropAd) => void

Called just before the full-screen ad is displayed. You can perform actions such as pausing the game.

onAdWillPresentFullScreen: (ad) => {
  console.log('About to show ad')
  // Pause game, stop music, etc.
}

onAdDidPresentFullScreen

(ad: AdropAd) => void

Called immediately after the full-screen ad is displayed.

onAdDidPresentFullScreen: (ad) => {
  console.log('Ad displayed')
}

onAdWillDismissFullScreen

(ad: AdropAd) => void

Called just before the full-screen ad is closed.

onAdWillDismissFullScreen: (ad) => {
  console.log('About to close ad')
}

onAdDidDismissFullScreen

(ad: AdropAd) => void

Called immediately after the full-screen ad is closed. Good time to preload the next ad.

onAdDidDismissFullScreen: (ad) => {
  console.log('Ad closed')
  // Resume game, load next ad, etc.
}

onAdFailedToShowFullScreen

(ad: AdropAd, errorCode?: string) => void

Called when ad display fails. You can check the failure reason through the error code.

onAdFailedToShowFullScreen: (ad, errorCode) => {
  console.log('Ad display failed:', errorCode)
}

onAdBackButtonPressed

(ad: AdropAd) => void

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

onAdBackButtonPressed: (ad) => {
  console.log('Back button pressed')
}

Class Method Implementation Example

Method using AdropInterstitialAd class directly.

import React, { useCallback, useEffect, useMemo, useState } from 'react'
import { Button, StyleSheet, Text, View } from 'react-native'
import { AdropInterstitialAd, type AdropListener } from 'adrop-ads-react-native'

const InterstitialAdScreen: React.FC = () => {
  const [interstitialAd, setInterstitialAd] = useState<AdropInterstitialAd>()
  const [isLoaded, setIsLoaded] = useState(false)
  const [errorCode, setErrorCode] = useState('')

  // Set up ad event listener
  const listener: AdropListener = useMemo(() => ({
    onAdReceived: (ad) => {
      console.log('Interstitial ad received:', ad.unitId)
      setIsLoaded(true)
      setErrorCode('')
    },
    onAdFailedToReceive: (ad, error) => {
      console.log('Interstitial ad reception failed:', error)
      setErrorCode(error || 'Unknown error')
      setIsLoaded(false)
    },
    onAdClicked: (ad) => {
      console.log('Interstitial ad clicked')
    },
    onAdImpression: (ad) => {
      console.log('Interstitial ad impression')
    },
    onAdWillPresentFullScreen: (ad) => {
      console.log('About to show interstitial ad')
      // Pause game, stop music, etc.
    },
    onAdDidPresentFullScreen: (ad) => {
      console.log('Interstitial ad displayed')
    },
    onAdWillDismissFullScreen: (ad) => {
      console.log('About to close interstitial ad')
    },
    onAdDidDismissFullScreen: (ad) => {
      console.log('Interstitial ad closed')
      setIsLoaded(false)
      // Resume game, preload next ad, etc.
    },
    onAdFailedToShowFullScreen: (ad, error) => {
      console.log('Interstitial ad display failed:', error)
      setErrorCode(error || 'Unknown error')
      setIsLoaded(false)
    },
    onAdBackButtonPressed: (ad) => {
      console.log('Back button pressed')
      ad.close() // Close ad on back button press (Android only)
    },
  }), [])

  // Initialize ad instance
  useEffect(() => {
    const ad = new AdropInterstitialAd('YOUR_UNIT_ID')
    ad.listener = listener
    setInterstitialAd(ad)

    // Clean up on component unmount
    return () => {
      ad.destroy()
    }
  }, [listener])

  // Load ad
  const loadAd = useCallback(() => {
    interstitialAd?.load()
  }, [interstitialAd])

  // Show ad
  const showAd = useCallback(() => {
    if (interstitialAd?.isLoaded) {
      interstitialAd.show()
    } else {
      console.log('Ad not loaded yet')
    }
  }, [interstitialAd])

  return (
    <View style={styles.container}>
      <Button
        title="Load Ad"
        onPress={loadAd}
      />
      <Button
        title="Show Ad"
        onPress={showAd}
        disabled={!isLoaded}
      />
      {errorCode && (
        <Text style={styles.error}>Error: {errorCode}</Text>
      )}
    </View>
  )
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: 'center',
    alignItems: 'center',
    gap: 16,
  },
  error: {
    color: 'red',
    marginTop: 16,
  },
})

export default InterstitialAdScreen

useAdropInterstitialAd Hook

You can implement interstitial ads more easily using React Hook.

Hook Usage

import { useAdropInterstitialAd } from 'adrop-ads-react-native'

const { load, show, reset, isLoaded, isOpened, isClosed, isClicked, errorCode, isReady } = useAdropInterstitialAd(unitId)

unitId

string | null

required

Ad unit ID. Passing null will release the ad.

Return Values

load

() => void

Loads the ad. Only works when isReady is true.

const handleLoad = () => {
  if (isReady) {
    load()
  }
}

show

() => void

Shows the loaded ad.

const handleShow = () => {
  if (isLoaded) {
    show()
  }
}

reset

() => void

Resets ad state and creates a new instance.

const handleReset = () => {
  reset()
}

isReady

boolean

Whether the ad instance is ready.

isLoaded

boolean

Whether the ad is successfully loaded.

isOpened

boolean

Whether the ad is displayed on screen.

isClosed

boolean

Whether the ad is closed.

isClicked

boolean

Whether the ad is clicked.

errorCode

string | undefined

Error code occurred during ad loading or display.

isBackPressed

boolean

Whether the back button was pressed while the ad is displayed. Android only.

browserTarget

BrowserTarget | undefined

Browser target setting of the loaded ad (BrowserTarget.EXTERNAL or BrowserTarget.INTERNAL).

Hook Method Implementation Example

Method using useAdropInterstitialAd Hook (recommended).

import React, { useCallback, useMemo } from 'react'
import { Button, StyleSheet, Text, View } from 'react-native'
import { useAdropInterstitialAd } from 'adrop-ads-react-native'

const InterstitialAdScreen: React.FC = () => {
  const unitId = 'YOUR_UNIT_ID'

  const {
    load,
    show,
    reset,
    isLoaded,
    isOpened,
    isClosed,
    isClicked,
    errorCode,
    isReady
  } = useAdropInterstitialAd(unitId)

  // Load ad
  const handleLoad = useCallback(() => {
    if (isReady) {
      load()
    }
  }, [isReady, load])

  // Show ad
  const handleShow = useCallback(() => {
    if (isLoaded) {
      show()
    }
  }, [isLoaded, show])

  // Reset ad
  const handleReset = useCallback(() => {
    reset()
  }, [reset])

  return (
    <View style={styles.container}>
      <Button
        title="Load Ad"
        onPress={handleLoad}
        disabled={!isReady}
      />

      <Button
        title="Show Ad"
        onPress={handleShow}
        disabled={!isLoaded}
      />

      <Button
        title="Reset Ad"
        onPress={handleReset}
        disabled={!(isOpened || errorCode)}
      />

      {/* Status display */}
      <View style={styles.statusContainer}>
        <Text>Ready: {isReady ? 'Yes' : 'No'}</Text>
        <Text>Loaded: {isLoaded ? 'Yes' : 'No'}</Text>
        <Text>Opened: {isOpened ? 'Yes' : 'No'}</Text>
        <Text>Closed: {isClosed ? 'Yes' : 'No'}</Text>
        <Text>Clicked: {isClicked ? 'Yes' : 'No'}</Text>
      </View>

      {errorCode && (
        <Text style={styles.error}>Error: {errorCode}</Text>
      )}
    </View>
  )
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: 'center',
    alignItems: 'center',
    gap: 16,
  },
  statusContainer: {
    marginTop: 24,
    padding: 16,
    backgroundColor: '#f0f0f0',
    borderRadius: 8,
  },
  error: {
    color: 'red',
    marginTop: 16,
  },
})

export default InterstitialAdScreen

Test Unit ID

Be sure to use test unit IDs in development and test environments.

// For testing
const TEST_UNIT_ID = 'PUBLIC_TEST_UNIT_ID_INTERSTITIAL'

// Separate dev/production environments
const unitId = __DEV__
  ? 'PUBLIC_TEST_UNIT_ID_INTERSTITIAL'
  : 'YOUR_PRODUCTION_UNIT_ID'

You must use actual unit IDs in production builds. Revenue from test unit IDs will not be settled.

Error Handling

Errors that may occur during ad loading and display should be handled appropriately.

Error Codes

Error Code	Description	Response
`AdropErrorCode.network`	Network error	Check network connection and retry
`AdropErrorCode.internal`	Internal error	Retry or contact support
`AdropErrorCode.initialize`	SDK initialization failed	Check SDK initialization code
`AdropErrorCode.invalidUnit`	Invalid unit ID	Check unit ID
`AdropErrorCode.adNoFill`	Ad inventory shortage	Normal, retry later
`AdropErrorCode.adLoading`	Already loading	Retry after loading completes
`AdropErrorCode.adEmpty`	No loaded ad	Show after loading ad
`AdropErrorCode.adShown`	Already shown ad	Need to load new ad

Error Handling Example

const { load, show, errorCode, isLoaded } = useAdropInterstitialAd(unitId)

useEffect(() => {
  if (errorCode) {
    switch (errorCode) {
      case AdropErrorCode.network:
        console.log('Network error: Check connection')
        // Retry after 30 seconds
        setTimeout(() => load(), 30000)
        break

      case AdropErrorCode.adNoFill:
        console.log('No ads available')
        // Continue without ad
        break

      case AdropErrorCode.invalidUnit:
        console.error('Invalid unit ID')
        break

      default:
        console.log('Ad error:', errorCode)
        break
    }
  }
}, [errorCode, load])

Best Practices

1. Appropriate Display Timing

Show ads at natural transition points in your app.

// ✅ Good: Game level transition
const handleLevelComplete = () => {
  saveProgress()
  if (isLoaded) {
    show() // Natural transition point
  }
  navigateToNextLevel()
}

// ✅ Good: After reading content
const handleArticleFinished = () => {
  if (isLoaded) {
    show()
  }
}

// ❌ Bad: During user action
const handleButtonClick = () => {
  show() // Disrupts user experience
  performAction()
}

2. Preloading

Preload ads to minimize user wait time.

const InterstitialAdScreen: React.FC = () => {
  const { load, show, isLoaded, isClosed } = useAdropInterstitialAd(unitId)

  // Preload ad on component mount
  useEffect(() => {
    load()
  }, [load])

  // Preload next ad after closing
  useEffect(() => {
    if (isClosed) {
      load()
    }
  }, [isClosed, load])

  return (
    // ...
  )
}

3. Frequency Limiting

Limit how often ads are shown.

const InterstitialAdScreen: React.FC = () => {
  const { show, isLoaded } = useAdropInterstitialAd(unitId)
  const [lastShownTime, setLastShownTime] = useState(0)
  const MIN_INTERVAL = 3 * 60 * 1000 // 3 minutes

  const showAdWithFrequencyLimit = useCallback(() => {
    const now = Date.now()
    if (now - lastShownTime < MIN_INTERVAL) {
      console.log('Ad display interval too short')
      return
    }

    if (isLoaded) {
      show()
      setLastShownTime(now)
    }
  }, [isLoaded, show, lastShownTime])

  return (
    // ...
  )
}

4. Game Pause Handling

Use listeners to manage game state in class method.

const listener: AdropListener = useMemo(() => ({
  onAdWillPresentFullScreen: (ad) => {
    // Pause game
    pauseGame()
    pauseBackgroundMusic()
  },
  onAdDidDismissFullScreen: (ad) => {
    // Resume game
    resumeGame()
    resumeBackgroundMusic()
  },
}), [])

5. Memory Management

Always release resources on component unmount.

// Hook method - automatic management
const { load, show } = useAdropInterstitialAd(unitId)

// Class method - manual cleanup required
useEffect(() => {
  const ad = new AdropInterstitialAd(unitId)
  setInterstitialAd(ad)

  return () => {
    ad.destroy() // Required!
  }
}, [unitId])

Platform Considerations

iOS

On iOS, ads automatically close when the app goes to background
onAdDidDismissFullScreen callback is called

Android

Ads can be closed with the back button on Android
Hardware acceleration may be required

Backfill Ads

To use backfill ads, you must have the backfill dependency added to your native platforms (Android/iOS).

When backfill ads are enabled, the SDK automatically falls back to backfill ads when no direct ad is available. You can handle backfill-specific error codes in the listener.

interstitialAd.listener = {
  onAdReceived: (ad) => {
    console.log('Ad loaded:', ad.creativeId)
  },
  onAdFailedToReceive: (ad, errorCode) => {
    switch (errorCode) {
      case AdropErrorCode.adNoFill:
        console.log('No direct ad available, requesting backfill...')
        break
      case AdropErrorCode.backfillNoFill:
        console.log('No backfill ad available either')
        break
      default:
        console.log('Ad load failed:', errorCode)
    }
  },
}

Next Steps

Rewarded Ads

Improve user engagement with rewarded ads

Banner Ads

Implement banner ads

Native Ads

Provide natural ad experience with native ads

Popup Ads

Implement popup ads

​Overview

​Features

​Implementation Methods

​AdropInterstitialAd Class

​Constructor

​Properties

​Methods

​AdropListener Interface

​Recommended Callbacks

​Optional Callbacks

​Class Method Implementation Example

​useAdropInterstitialAd Hook

​Hook Usage

​Return Values

​Hook Method Implementation Example

​Test Unit ID

​Error Handling

​Error Codes

​Error Handling Example

​Best Practices

​1. Appropriate Display Timing

​2. Preloading

​3. Frequency Limiting

​4. Game Pause Handling

​5. Memory Management

​Platform Considerations

​iOS

​Android

​Backfill Ads

​Next Steps

Rewarded Ads

Banner Ads

Native Ads

Popup Ads

Overview

Features

Implementation Methods

AdropInterstitialAd Class

Constructor

Properties

Methods

AdropListener Interface

Recommended Callbacks

Optional Callbacks

Class Method Implementation Example

useAdropInterstitialAd Hook

Hook Usage

Return Values

Hook Method Implementation Example

Test Unit ID

Error Handling

Error Codes

Error Handling Example

Best Practices

1. Appropriate Display Timing

2. Preloading

3. Frequency Limiting

4. Game Pause Handling

5. Memory Management

Platform Considerations

iOS

Android

Backfill Ads

Next Steps