Banner integration for React Native
Implement banner ads in your React Native app using the LevelPlay SDK, including setup, initialization, and listener configuration.
Read time 4 minutesLast updated 7 months ago
Banners are rectangular, system-initiated ads that can be either static or animated, and are served in a designated area around your live app content.
Note
This documentation is relevant for SDK 8.4.0+.
Prerequisites
- Ensure that you have correctly integrated the LevelPlay React Native SDK into your app. Integration is outlined here.
- Ensure that you initialize the SDK using LevelPlay Initialization API.
- Find the AdUnitID in LevelPlay dashboard.
Create Banner Ad Object and Set Size
The creation of the banner ad object should be done after receiving onInitSuccess callback.
import { LevelPlayBannerAdView, LevelPlayAdSize, type LevelPlayBannerAdViewMethods, type LevelPlayBannerAdViewListener,} from 'unity-levelplay-mediation'const bannerAdViewRef = useRef<LevelPlayBannerAdViewMethods>(null);const adSize = LevelPlayAdSize.BANNER; // or await LevelPlayAdSize.createAdaptiveAdSize() for adaptiveconst listener = { /* LevelPlayBannerAdViewListener */ };const loadAd = useCallback(() => { bannerAdViewRef.current?.loadAd();}, []);return ( <LevelPlayBannerAdView ref={bannerAdViewRef} adUnitId="YOUR_AD_UNIT_ID" adSize={adSize} placementName="YOUR_PLACEMENT" listener={listener} style={{ width: adSize.width, height: adSize.height }} />);
Banner Sizes
LevelPlayAdSize | Description | Dimensions in dp (Width X Height) |
|---|---|---|
| BANNER | Standard banner | 320 x 50 |
| LARGE | Large banner | 320 x 90 |
| MEDIUM_RECTANGLE | Medium Rectangular (MREC) | 300 x 250 |
| Adaptive | Automatically renders ads to adjust size and orientation for mobile & tablets | Device width X recommended height |
To create the ad size follow one of these options:
Adaptive ad size that adjusts to the screen width (recommended): This option replaces the “SMART” integration, as it will return BANNER or LEADERBOARD according to the device type. Networks that support adaptive features (Google, Yandex) will return a height based on their optimization logic.
let adSize = await LevelPlayAdSize.createAdaptiveAdSize();
Adaptive ad size using fixed width ad size: This option allows you to set a specific width. Networks that support adaptive- banner feature (Google, Yandex) will return a height based on their optimization logic based on the provided width. All other networks will return the fallback size (either BANNER or LEADERBOARD) according to the width provided.
let adSize = await LevelPlayAdSize.createAdaptiveAdSize(400);
Specific banner size: This option allows you to set specifically a banner size: banner, large, medium.
let adSize = LevelPlayAdSize.MEDIUM_RECTANGLE;
Placements
We support placements in banners for reporting only. Placements should be set before the loadAd, to affect all reloaded ads.
Set Banner Listener
Implement the LevelPlayBannerAdViewListener in your code to get informed of ad delivery.
- It is recommended to set the listener before loading the banner ad.
- Each banner ad should have its own listener implementation.
- Callbacks run on the main thread.
const listener: LevelPlayBannerAdViewListener = { onAdLoaded: (adInfo: LevelPlayAdInfo) => { // Invoked each time a banner was loaded. Either on refresh, or manual load. }, onAdLoadFailed: (error: LevelPlayAdError) => { // Invoked when the banner loading process has failed. // This callback will be sent both for manual load and refreshed banner failures. }, onAdDisplayed: (adInfo: LevelPlayAdInfo) => { // Notifies the screen is displayed. }, onAdDisplayFailed: (adInfo: LevelPlayAdInfo, error: LevelPlayAdError) => { // Notifies the screen failed to display. }, onAdClicked: (adInfo: LevelPlayAdInfo) => { // Invoked when end user clicks on the banner ad. }, onAdExpanded: (adInfo: LevelPlayAdInfo) => { // Ad is opened on full screen }, onAdCollapsed: (adInfo: LevelPlayAdInfo) => { // Ad is restored to its original size }, onAdLeftApplication: (adInfo: LevelPlayAdInfo) => { // Invoked when the user left the app. },};
Load Banner Ad
To load a banner ad use loadAd.
// Load the banner adbannerAdViewRef.current?.loadAd();
Pause and Resume Banner Refresh
You can pause banner refresh in your code if the refresh value was defined in the platform. Use the following methods to stop the automatic refresh of the banner ad, or re-enable it after pausing.
Note
When the banner is displayed again, it will complete the time until refresh from the time it was paused.
- pauseAutoRefresh – pauses auto-refresh of the banner ad.
- resumeAutoRefresh – resumes auto-refresh of the banner ad after it has been paused.
// Pause refresh bannerAdViewRef.current?.pauseAutoRefresh(); // Resume refreshbannerAdViewRef.current?.resumeAutoRefresh();
Destroy Banner Ad
To destroy a banner, call the destroy method.
A destroyed banner can no longer be shown again. To display more ads, create a new LevelPlayBannerAdView object.
bannerAdViewRef.current?.destroy();
Full Implementation Example of Banner Ads
Here is an example for creating and loading a banner ad using standard banner size.
import { LevelPlayBannerAdView, LevelPlayAdSize, type LevelPlayBannerAdViewMethods, type LevelPlayBannerAdViewListener, type LevelPlayAdInfo, type LevelPlayAdError,} from 'unity-levelplay-mediation'// Start of some component ...const bannerAdViewRef = useRef<LevelPlayBannerAdViewMethods>(null);const adSize = LevelPlayAdSize.BANNERconst listener: LevelPlayBannerAdViewListener = { onAdLoaded: (adInfo: LevelPlayAdInfo) => { // Implement your logic here }, onAdLoadFailed: (error: LevelPlayAdError) => { // Implement your logic here }, onAdDisplayed: (adInfo: LevelPlayAdInfo) => { // Implement your logic here }, onAdDisplayFailed: (adInfo: LevelPlayAdInfo, error: LevelPlayAdError) => { // Implement your logic here }, onAdClicked: (adInfo: LevelPlayAdInfo) => { // Implement your logic here }, onAdExpanded: (adInfo: LevelPlayAdInfo) => { // Implement your logic here }, onAdCollapsed: (adInfo: LevelPlayAdInfo) => { // Implement your logic here }, onAdLeftApplication: (adInfo: LevelPlayAdInfo) => { // Implement your logic here },};return ( <LevelPlayBannerAdView ref={bannerAdViewRef} adUnitId={'YOUR_AD_UNIT_ID'} adSize={adSize} placementName={'YOUR_PLACEMENT'} listener={listener} onLayout={(_) => bannerAdViewRef.current?.loadAd()} style={{width: adSize.width, height: adSize.height}} // Get actual banner layout size />); // End of component ...
LevelPlay Mediation Demo App
The Integration Demo application demonstrates how to integrate banner Ad Unit APIs in your app.
Verify your integration with our Integration Test Suite.
Next steps
Follow our integration guides to integrate additional mediation networks or configure additional ad formats: