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

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()
}

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.

Required 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)
}

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, 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)
    },
  }), [])

  // 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.

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
`ERROR_CODE_NETWORK`	Network error	Check network connection and retry
`ERROR_CODE_INTERNAL`	Internal error	Retry or contact support
`ERROR_CODE_INITIALIZE`	SDK initialization failed	Check SDK initialization code
`ERROR_CODE_INVALID_UNIT`	Invalid unit ID	Check unit ID
`ERROR_CODE_AD_NO_FILL`	Ad inventory shortage	Normal, retry later
`ERROR_CODE_AD_LOADING`	Already loading	Retry after loading completes
`ERROR_CODE_AD_EMPTY`	No loaded ad	Show after loading ad
`ERROR_CODE_AD_SHOWN`	Already shown ad	Need to load new ad

Error Handling Example

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

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

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

      case 'ERROR_CODE_INVALID_UNIT':
        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

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

SDK Guide

AI

Android

iOS

React Native

Flutter

Web

REST API

​Overview

​Features

​Implementation Methods

​AdropInterstitialAd Class

​Constructor

​Properties

​Methods

​AdropListener Interface

​Required 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

​Next Steps

Rewarded Ads

Banner Ads

Native Ads

Popup Ads

Overview

Features

Implementation Methods

AdropInterstitialAd Class

Constructor

Properties

Methods

AdropListener Interface

Required 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

Next Steps