Integrate Native Ads

To integrate any ad format, you must first have completed the instructions in the basic integration article.

Native ads are composed of assets that are presented to users via UI components native to the platform. They’re displayed using the same classes you already use in your storyboards, and can be formatted to match your app's visual design. When a native ad loads, your app receives an ad object containing its assets, and your app (rather than the SDK) is then responsible for displaying them. This differs from other ad formats, which don't allow you to customize the appearance of the ad.

Broadly speaking, there are two parts to successfully implementing native ads: loading an ad via the SDK and displaying the ad content in your app.

Create and Load a Native Ad

1. To integrate native ads in your app, add a ViewGroup to your Activity/Fragment, and name it nativeAdContainer.
2. Design a layout file for native ad.

3. In your Activity/Fragment file, import NativeAd and add an instance variable for NativeAd.

   KotlinJava

   nativeAd = NativeAd(requireActivity(), placementId).apply {
      adListener = this@NativeAdFragment
      load()
   }
   

   nativeAd = new NativeAd(requireActivity(), placementId);
   nativeAd.setAdListener(this);
   nativeAd.load();

Display a Native Ad

1. To display a native ad in your application, fill all the elements in the layout file; these usually include button text, icon, main image, etc. Refer to Native Ad UI Elements below.
2. Remove nativeAdContainer child views, and then add native ad layout to nativeAdContainer.
3. Register all the clickable views.
4. Call registerViewForInteraction and pass the root view, MediaView, iconView, and clickableViews. Root view and MediaView are required. If there are no clickableViews, MediaView will handle click events.

nativeAd?.let { nativeAd ->
           val layout = LayoutNativeAdBinding.inflate(LayoutInflater.from(requireContext()))
           with(layout) {
               binding.adContainer.removeAllViews()
               val clickableViews = mutableListOf(imgAdIcon, pnlVideoAd, btnAdCta)
               lbAdTitle.text = nativeAd.getAdTitle()
               lbAdBody.text = nativeAd.getAdBodyText()
               lbAdRating.text = String.format("Rating: %s", nativeAd.getAdStarRating())
               lbAdSponsor.text = nativeAd.getAdSponsoredText()
               btnAdCta.text = nativeAd.getAdCallToActionText()
               btnAdCta.isVisible = nativeAd.hasCallToAction()
    nativeAd.registerViewForInteraction(
                   root, pnlVideoAd, imgAdIcon, clickableViews
               )	
               binding.apply {
                   nativeAdContainer.show()
               }


               nativeAdContainer.addView(root)
           }
       }

List<View> clickableViews = new ArrayList<>();
clickableViews.add(layout.imgAdIcon);
clickableViews.add(layout.pnlVideoAd);
clickableViews.add(layout.btnAdCta);
nativeAd.registerViewForInteraction(layout.getRoot(), layout.pnlVideoAd, layout.imgAdIcon, clickableViews);
layout.lbAdTitle.setText(nativeAd.getAdTitle());
layout.lbAdBody.setText(nativeAd.getAdBodyText());
layout.lbAdRating.setText(String.format("Rating: %s", nativeAd.getAdStarRating()));
layout.lbAdSponsor.setText(nativeAd.getAdSponsoredText());
layout.btnAdCta.setText(nativeAd.getAdCallToActionText());
layout.btnAdCta.setVisibility(nativeAd.hasCallToAction() ? View.VISIBLE : View.GONE);
nativeAdContainer.addView(layout.getRoot());
nativeAdContainer.setVisibility(View.VISIBLE);

Native Ad UI Elements

These are the UI elements illustrated in the layout above:

1. NativeAdLayout: Required. A main view that contains all other native ad components.
2. ImageView: Optional. A view to display an icon image.
3. MediaView: Required. A view to display a main image.
4. TextView: Optional. A label to display the ad title.
5. TextView: Optional. A label to display app rating.
6. TextView: Optional. A label to display "Sponsored By" text.
7. NativeAdOptionsView: Optional. An option view to display privacy icon. Because this is a private class, use the setAdOptionsPosition API as instructed in the third step of the Create and Load a Native Ad section.
8. TextView: Optional. A label to display ad body text.
9. Button: Optional. A button to display Call to Action (CTA) text.

You can place the view anywhere on the screen. This container is a Layout. You can place this Layout anywhere on the screen.

Destroy a Native Ad

In cases where you reuse the view to show different ads over time, make sure to call unregisterView() before registering the same view with a different instance of NativeAd.

nativeAd.unregisterView()

nativeAd.unregisterView();

Register for Callbacks

To receive notifications for ad events, declare conformance to NativeAdListener protocol and implement callback methods.

override fun onAdLoaded(baseAd: BaseAd) {
Log.d(TAG, "Creative id:" + baseAd.creativeId)
}
override fun onAdStart(baseAd: BaseAd) {
}
override fun onAdImpression(baseAd: BaseAd) {
}
override fun onAdEnd(baseAd: BaseAd) {
}
override fun onAdClicked(baseAd: BaseAd) {
}
override fun onAdLeftApplication(baseAd: BaseAd) {
}
override fun onAdFailedToLoad(baseAd: BaseAd, adError: VungleError) {
}
override fun onAdFailedToPlay(baseAd: BaseAd, adError: VungleError) {
}

@Override
public void onAdClicked(@NonNull BaseAd baseAd) {
}
@Override
public void onAdEnd(@NonNull BaseAd baseAd) {
}
@Override
public void onAdFailedToLoad(@NonNull BaseAd baseAd, @NonNull VungleError vungleError) {
}
@Override
public void onAdFailedToPlay(@NonNull BaseAd baseAd, @NonNull VungleError vungleError) {
}
@Override
public void onAdImpression(@NonNull BaseAd baseAd) {
}
@Override
public void onAdLeftApplication(@NonNull BaseAd baseAd) {
}
@Override
public void onAdLoaded(@NonNull BaseAd baseAd) {
Log.d(TAG, "Creative id:" + baseAd.getCreativeId());
}
@Override
public void onAdStart(@NonNull BaseAd baseAd) {
}
;

Video Events

Native ad provides access to MediaView class that is used to get information about media content which could be video or image. 

Check if the native ad has video content.

// If the content is video the value will return true.
// If the content is image the value will return false.
nativeAd.hasVideoContent()

// If the content is video the value will return true.
// If the content is image the value will return false.
nativeAd.hasVideoContent();

Retrieve video duration of the ad

// If the content is image the value will return 0. 
mediaView.getDuration() // Units are in seconds

// If the content is image the value will return 0. 
mediaView.getDuration(); // Units are in seconds

Retrieve current playback time of the video

// If the content is image the value will return 0. 
mediaView.getCurrentTime() // Units are in seconds

// If the content is image the value will return 0. 
mediaView.getCurrentTime(); // Units are in seconds

To receive notifications for ad events, declare conformance to NativeVideoListener protocol and implement callback methods.
Set the delegate to receive  NativeVideoListener events

mediaView.setNativeVideoListener()

mediaView.setNativeVideoListener();

override fun onVideoPlay() { }
override fun onVideoPause() { }
override fun onVideoEnd() { }
override fun onVideoMute() { }
override fun onVideoUnmute() { }

@Override
public void onVideoPlay() { }
@Override
public void onVideoPause() { }
@Override
public void onVideoEnd() { }
@Override
public void onVideoMute() { }
@Override
public void onVideoUnmute() { }
;

Test a Native Ad

You can test a native ad in one of two ways: by setting your app status to Test Mode so that Vungle can deliver test ads to your app, or by adding a test device to your app so that Vungle can deliver test ads specifically to the test device. Follow the instructions in Test Your Integration: Test Mode and Test Devices.