Documentation

LevelPlay SDK - React Native

Unity SDK

Android SDK

iOS SDK

Adobe AIR SDK

Flutter SDK

React Native SDK

LevelPlay SDK - React Native

Native ads integration for React Native

Integrate native ads into your React Native application, offering customizable ad experiences with predefined or custom templates.
Read time 8 minutesLast updated 12 days ago
Native ads are a form of advertising that you can customize to blend in with the other content in your app. This makes ads appear more organic, which leads to a better user experience and higher retention.

Prerequisites

Ensure that you have correctly integrated the LevelPlay React Native plug-in 9.0.0+ into your application. The integration is outlined here.

Integrate LevelPlay native ads

There are two ways to integrate LevelPlay native ads using the React Native plug-in:
  • Native Templates: Predefined templates(XML and XIB files) provided by plug-in.
  • Custom Templates: Custom templates styled and designed by developers.

Native Templates

Native templates are predefined views that implement the native ad logic. This setup handles the population of views after the ad has loaded and clears them after the ad is destroyed.
There are two template options:
  • Small: Templates that do not include the media view.
  • Medium: Templates that feature the media view.
While the styling is generally similar, you can also customize it according to your preference.
To integrate native templates, follow the steps below:

Step 1. Create LevelPlayNativeAd Object

Create a LevelPlayNativeAd object responsible for loading the ad into the LevelPlayNativeAdView container. This object will handle the ad methods such as load, destroy and will define the ad placement and listener for event callbacks.
import {  LevelPlayNativeAd,  LevelPlayNativeAdView,  LevelPlayTemplateType,  type LevelPlayNativeAdListener,  type AdInfo,  type IronSourceError,} from 'unity-levelplay-mediation'const [nativeAd, setNativeAd] = useState<LevelPlayNativeAd | null>(null)useEffect(() => {  const levelPlayNativeAd = LevelPlayNativeAd.builder()    .withPlacement('YOUR_PLACEMENT')    .withListener(listener)    .build();  setNativeAd(levelPlayNativeAd);}, []);

Step 2. Implement the Listener

Implement the LevelPlayNativeAdListener in your code. The LevelPlay SDK fires several callbacks to inform you of native ad activity. The SDK will notify your Listener of all the events listed below:
Native ad callbacks report the legacy 
AdInfo
and 
IronSourceError
types (not 
LevelPlayAdInfo
and 
LevelPlayAdError
).
const listener: LevelPlayNativeAdListener = {  /** Called after a native ad has been clicked. */  onAdClicked: (nativeAd: LevelPlayNativeAd, adInfo: AdInfo) => {},  /** Called after a native ad impression has been recorded. */  onAdImpression: (nativeAd: LevelPlayNativeAd, adInfo: AdInfo) => {},  /** Called after a native ad has attempted to load but failed. */  onAdLoadFailed: (nativeAd: LevelPlayNativeAd, error: IronSourceError) => {},  /** Called after a native ad has been successfully loaded. */  onAdLoaded: (nativeAd: LevelPlayNativeAd, adInfo: AdInfo) => {},};

Step 3. Create LevelPlayNativeAdView

Create a LevelPlayNativeAdView component to define the container that will host the loaded native ad. This object will define the native ad boundaries by determining width and height or setting box constraints for the container. It can also handle the native ad elements styling, such as: title, body, advertiser and call to action button.
Note
For native templates, 
templateType
is required: set it to 
LevelPlayTemplateType.Small
or 
LevelPlayTemplateType.Medium
. If you omit it, the template view can't be created.
<LevelPlayNativeAdView    style={{       width: 300,// Recommended width for Medium Type       height: 350 // Recommended height for Medium Type    }}    nativeAd={nativeAd}     templateType={LevelPlayTemplateType.Medium}    templateStyle={templateStyle} // optional: LevelPlayNativeAdTemplateStyle  /><LevelPlayNativeAdView    style={{       width: 300,// Recommended width for Small Type       height: 175 // Recommended height for Small Type    }}    nativeAd={nativeAd}     templateType={LevelPlayTemplateType.Small}    templateStyle={templateStyle} // optional: LevelPlayNativeAdTemplateStyle  />
The optional 
templateStyle
prop customizes the template elements. For example:
import {  LevelPlayNativeTemplateFontStyle,  type LevelPlayNativeAdTemplateStyle,} from 'unity-levelplay-mediation'const templateStyle: LevelPlayNativeAdTemplateStyle = {  mainBackgroundColor: '#FFFFFF',  titleStyle: {    textSize: 18,    textColor: '#000000',    fontStyle: LevelPlayNativeTemplateFontStyle.Bold,  },  bodyStyle: {    textSize: 14,    textColor: '#555555',  },  callToActionStyle: {    backgroundColor: '#1E88E5',    textColor: '#FFFFFF',    cornerRadius: 8,  },}
Each element style (
titleStyle
, 
bodyStyle
, 
advertiserStyle
, 
callToActionStyle
) supports 
backgroundColor
, 
textSize
, 
textColor
, 
fontStyle
and 
cornerRadius
.

Step 4. Load the ad

Call loadAd method to load a native ad. It can be called on useEffect hook or in another timing decided by the developer.
nativeAd?.loadAd();

Step 5. Destroy the Native Ad

To destroy a native ad, call the following method:
nativeAd?.destroyAd();
After you destroy a native ad, you can call 
loadAd()
again to load a new native ad into the same container.

Custom Templates Setup

Custom templates allow you to design your own styles and features to fit your specific needs. They provide the flexibility to personalize layouts and functionalities, ensuring a unique user experience. 
These templates are mainly used when a higher level of control over the ad design is necessary. It can be implemented for both Android and iOS platforms and require additional code implementation.
To create custom templates, you'll need to write native code and develop your own custom layouts. Follow the steps below for integration:

Step 1. Create NativeAdViewManager

The Android or iOS implementation of the class that will extend LevelPlayNativeAdViewManager and display the loaded ad with your customized layout.
Android
// Android Implementationimport android.widget.Buttonimport android.widget.ImageViewimport android.widget.TextViewimport com.facebook.react.bridge.ReactApplicationContextimport com.ironsource.mediationsdk.ads.nativead.LevelPlayMediaViewimport com.ironsource.mediationsdk.ads.nativead.LevelPlayNativeAdimport com.ironsource.mediationsdk.ads.nativead.NativeAdLayoutimport com.unity3d.reactnative.Rimport com.unity3d.reactnative.LevelPlayNativeAdViewManagerclass NativeAdViewManagerExample(  reactApplicationContext: ReactApplicationContext,  layoutId: Int): LevelPlayNativeAdViewManager(reactApplicationContext, layoutId) {  override fun bindNativeAdToView(nativeAd: LevelPlayNativeAd?, nativeAdLayout: NativeAdLayout) {    // Extract views    val titleView = nativeAdLayout.findViewById<TextView>(R.id.adTitle)    val bodyView = nativeAdLayout.findViewById<TextView>(R.id.adBody)    val advertiserView = nativeAdLayout.findViewById<TextView>(R.id.adAdvertiser)    val callToActionView = nativeAdLayout.findViewById<Button>(R.id.adCallToAction)    val iconView = nativeAdLayout.findViewById<ImageView>(R.id.adAppIcon)    val mediaView: LevelPlayMediaView? = nativeAdLayout.findViewById(R.id.adMedia)    // Bind native ad to view    if (nativeAd != null) {      if (nativeAd.title != null) {        titleView.text = nativeAd.title        nativeAdLayout.setTitleView(titleView)      }      if (nativeAd.body != null) {        bodyView.text = nativeAd.body        nativeAdLayout.setBodyView(bodyView)      }      if (nativeAd.advertiser != null) {        advertiserView.text = nativeAd.advertiser        nativeAdLayout.setAdvertiserView(advertiserView)      }      if (nativeAd.callToAction != null) {        callToActionView.text = nativeAd.callToAction        nativeAdLayout.setCallToActionView(callToActionView)      }      if (nativeAd.icon != null) {        iconView!!.setImageDrawable(nativeAd.icon!!.drawable)        nativeAdLayout.setIconView(iconView)      }      if (mediaView != null) {        nativeAdLayout.setMediaView(mediaView)      }      nativeAdLayout.registerNativeAdViews(nativeAd)    }  }  override fun getName(): String {    return "ExampleViewType"  }}
iOS
// iOS Implementation /// h file#import <Foundation/Foundation.h>#import <IronSource/IronSource.h>#import "LevelPlayNativeAdViewManager.h"@interface NativeAdViewManagerExample : LevelPlayNativeAdViewManager <LevelPlayNativeAdViewManagerDelegate>@end/// m file#import "NativeAdViewManagerExample.h"@implementation NativeAdViewManagerExampleRCT_EXPORT_MODULE(ExampleViewType) // View type definition- (instancetype)init{  self = [super initWithDelegate:self layoutName:@"MyCustomNativeAdViewTemplate"];  return self;}- (void)bindNativeAdToView:(LevelPlayNativeAd *)nativeAd isNativeAdView:(ISNativeAdView *)isNativeAdView {    // Extract views    UILabel *titleView = isNativeAdView.adTitleView;    UILabel *bodyView = isNativeAdView.adBodyView;    UILabel *advertiserView = isNativeAdView.adAdvertiserView;    UIButton *callToActionView = isNativeAdView.adCallToActionView;    UIImageView *iconView = isNativeAdView.adAppIcon;    LevelPlayMediaView *mediaView = isNativeAdView.adMediaView;    // Bind native ad to view    if (nativeAd != nil) {        if (nativeAd.title != nil) {            titleView.text = nativeAd.title;            [isNativeAdView setAdTitleView:titleView];        }        if (nativeAd.body != nil) {            bodyView.text = nativeAd.body;            [isNativeAdView setAdBodyView:bodyView];        }        if (nativeAd.advertiser != nil) {            advertiserView.text = nativeAd.advertiser;            [isNativeAdView setAdAdvertiserView:advertiserView];        }        if (nativeAd.callToAction != nil) {            [callToActionView setTitle:nativeAd.callToAction forState:UIControlStateNormal];            [isNativeAdView setAdCallToActionView:callToActionView];        }        if (nativeAd.icon != nil) {            iconView.image = nativeAd.icon.image;            [isNativeAdView setAdAppIcon:iconView];        }        if (mediaView != nil) {            [isNativeAdView setAdMediaView:mediaView];        }        // Register native ad views with the provided native ad        [isNativeAdView registerNativeAdViews:nativeAd];    }}@end
Your custom view type string should match the viewType specified in the LevelPlayNativeAdView component on the React Native side.
  • For Android, return the view type string in the overridden getName method.
  • For iOS, specify the view type string in RCT_EXPORT_MODULE.

Step 2. Register your NativeAdViewManager for Android

After you've created a custom native ad class that extends the LevelPlayNativeAdViewManager class, register your Android class in the MainApplication.
Note
Your custom view type string must match the viewType set in the LevelPlayNativeAdView component on the React Native side. For iOS, no additional setup is needed since the module export serves as registration.
// Android Implementationpackage com.yourappimport android.app.Applicationimport com.facebook.react.PackageListimport com.facebook.react.ReactApplicationimport com.facebook.react.ReactHostimport com.facebook.react.ReactNativeApplicationEntryPoint.loadReactNativeimport com.facebook.react.ReactNativeHostimport com.facebook.react.ReactPackageimport com.facebook.react.defaults.DefaultReactHost.getDefaultReactHostimport com.facebook.react.defaults.DefaultReactNativeHostimport com.unity3d.reactnative.LevelPlayMediationPackageclass MainApplication : Application(), ReactApplication {  override val reactNativeHost: ReactNativeHost =      object : DefaultReactNativeHost(this) {        override fun getPackages(): List<ReactPackage> =            PackageList(this).packages.apply {              // Packages that cannot be autolinked yet can be added manually here, for example:              // add(MyReactNativePackage())            }        override fun getJSMainModuleName(): String = "index"        override fun getUseDeveloperSupport(): Boolean = BuildConfig.DEBUG        override val isNewArchEnabled: Boolean = BuildConfig.IS_NEW_ARCHITECTURE_ENABLED        override val isHermesEnabled: Boolean = BuildConfig.IS_HERMES_ENABLED      }  override val reactHost: ReactHost    get() = getDefaultReactHost(applicationContext, reactNativeHost)  override fun onCreate() {    super.onCreate()    loadReactNative(this)    // Register custom view managers    LevelPlayMediationPackage.registerViewManager("ExampleViewType") { reactContext ->      NativeAdViewManagerExample(reactContext, R.layout.my_custom_native_ad_view)    }  }}

Step 3. Create LevelPlayNativeAdView

Create a LevelPlayNativeAdView component to define the container that will host the loaded native ad. This object will define the native ad boundaries by determining width and height or setting box constraints for the container. It can also handle the native ad elements styling, such as: title, body, advertiser and call to action button.
Note
When creating custom templates, ensure the viewType aligns with the unique view type specified in the native Android or iOS sections.
<LevelPlayNativeAdView    style={{      width: 300,  // recommended width for native ad container      height: 350, // recommended height (for example: medium-style layout)    }}    nativeAd={nativeAd}    viewType="ExampleViewType"    templateStyle={templateStyle} // optional: LevelPlayNativeAdTemplateStyle  />

Step 4. Load the ad

Call loadAd method to load a native ad. It can be called on useEffect or in another timing decided by the developer.
nativeAd?.loadAd();

Step 5. Destroy the Native Ad

To destroy a native ad, invoke the destroyAd method of the native ad object.
nativeAd?.destroyAd();
After you destroy a native ad, you can call 
loadAd()
again to load a new native ad into the same container.