Integrate MREC Ads on Vungle SDK v.6 for Android and Amazon

Starting with Vungle SDK v6.4.11, Vungle supports MREC video ads.

Understand MREC Ads

MREC is an abbreviation for "medium rectangle" ads. Unlike interstitial ads, MREC ads do not require a fullscreen view. Similar to banner ads, MREC video ads are rectangular ads occupying a location anywhere within the app's layout, typically displayed on the top or bottom of the screen, so that the user can continue to interact with the app while the ad is playing. The container size to render an MREC ad is the industry standard: 300x250.

Step 1. Complete Basic Integration

To integrate MREC ads in your Android or Amazon app, begin by following the instructions in the basic integration article. This MREC Ads article contains supplementary information and assumes you have completed basic integration.

Step 2. Implement Event Listeners

You can use generic callbacks, by implementing LoadAdCallback for ad load events and PlayAdCallback for ad play events, or use inline callbacks when you invoke loadAd and playAd.

LoadAdCallback

private final LoadAdCallback vungleLoadAdCallback = new LoadAdCallback() { 
  @Override
  public void onAdLoad(String id) { 
    // Ad has been successfully loaded for the placement
  } 

  @Override 
  public void onError(String id, VungleException exception) { 
    // Ad has failed to load for the placement
  }
};

// 6.4.x & below
private final LoadAdCallback vungleLoadAdCallback = new LoadAdCallback() { 
  @Override
  public void onAdLoad(String id) { 
    // Ad has been successfully loaded for the placement
  } 

  @Override 
  public void onError(String id, Throwable throwable) { 
    // Ad has failed to load for the placement
  }
};

PlayAdCallback

private final PlayAdCallback vunglePlayAdCallback = new PlayAdCallback() {
  @Override
  public void onAdStart(String id) { 
    // Ad experience started
  }
  
  @Override
  public void onAdViewed(String id) { 
    // Ad has rendered
  }

  @Override
  public void onAdEnd(String id) {
    // Ad experience ended
  }

  @Override
  public void onAdClick(String id) {
    // User clicked on ad
  }

  @Override
  public void onAdLeftApplication(String id) {
    // User has left app during an ad experience
  }
  
  @Override
  public void creativeId(String creativeId) {
   // Vungle creative ID to be displayed
  }

  @Override
  public void onError(String id, VungleException exception) { 
    // Ad failed to play
  }
};

// 6.8.x & 6.9.x
private final PlayAdCallback vunglePlayAdCallback = new PlayAdCallback() {
  @Override
  public void onAdStart(String id) { 
    // Ad experience started
  }
  
  @Override
  public void onAdViewed(String id) { 
    // Ad has rendered
  }

  @Override
  public void onAdEnd(String id) {
    // Ad experience ended
  }

  @Override
  public void onAdClick(String id) {
    // User clicked on ad
  }

  @Override
  public void onAdLeftApplication(String id) {
    // User has left app during an ad experience
  }

  @Override
  public void onError(String id, VungleException exception) { 
    // Ad failed to play
  }
};

// 6.6.x & 6.7.x
private final PlayAdCallback vunglePlayAdCallback = new PlayAdCallback() {
  @Override
  public void onAdStart(String id) { 
    // Ad experience started
  }

  @Override
  public void onAdEnd(String id) {
    // Ad experience ended
  }

  @Override
  public void onAdClick(String id) {
    // User clicked on ad
  }

  @Override
  public void onAdLeftApplication(String id) {
    // User has left app during an ad experience
  }

  @Override
  public void onError(String id, VungleException exception) { 
    // Ad failed to play
  }
};

// 6.5.x & below
private final PlayAdCallback vunglePlayAdCallback = new PlayAdCallback() { 
  @Override 
  public void onAdStart(String placementReferenceId) {
    // Ad experience started
  } 

  // Deprecated
  @Override
  public void onAdEnd(String placementReferenceId, boolean completed, boolean isCTAClicked) {
    // Invoked when the ad experience is completed
    // isCTAClicked flag indicates whether CTA download button has been triggered
		// completed flag indicates at least 80% of video was watched for rewarded placement
  }

  @Override 
  public void onError(String placementReferenceId, VungleException exception) {
    // Ad failed to play
  }
};

Step 3. Load, Display, and Close an MREC Ad

Note on v6.10.x API Change: Starting with v6.10.1, we are incorporating MREC ads into VungleBanner, by using MREC as an ad size, for simpler integration. Integration steps will be identical to integration banner ads and same API will be used with AdConfig.AdSize.VUNGLE_MREC as ad size of BannerAdConfig. VungleNativeAd API remains fuctional to this version but we plan to deprecate it in future so we highly recommend publisher to migrate to VungleBanner when updating Vungle Android SDK to v6.10.x.

Please note that the placement ID that you use for MREC must be configured as a MREC placement from the Liftoff Monetize dashboard and attempting to load with a banner placement ID will result in no fill.

Load an MREC Ad

Loading an MREC ad uses the banner API with MREC as an ad size. Banners.loadBanner will be called with a BannerAdConfig object that has been configured with AdConfig.AdSize.VUNGLE_MREC with setAdSize. Similarly, you will use Banners.canPlayAd to check ad availability for the MREC placement.

1. Load an MREC ad by calling the loadBanner method:
   6.10.x & above 6.9.1 and lower

   final BannerAdConfig bannerAdConfig = new BannerAdConfig();
   bannerAdConfig.setAdSize(AdConfig.AdSize.VUNGLE_MREC);
   Banners.loadBanner("MREC_ID", bannerAdConfig, vungleLoadAdCallback);

   // Deprecated - 6.9.1 & below
   Vungle.loadAd("MREC_ID", vungleLoadAdCallback);

2. Check for banner ad availability by calling the canPlayAd method:
   6.10.x & above 6.9.1 and lower

   final BannerAdConfig bannerAdConfig = new BannerAdConfig();
   bannerAdConfig.setAdSize(AdConfig.AdSize.VUNGLE_MREC);
   Banners.canPlayAd("MREC_ID", bannerAdConfig.getAdSize());

   // 6.9.1 & below
   Vungle.canPlayAd("MREC_ID");

// Deprecated - 6.9.1 & below
Vungle.loadAd("MREC_ID", vungleLoadAdCallback);

Display an MREC Ad

The view size is fixed and the container which is used to display the MREC ad must be specified to be 300dp x 250dp which can be placed anywhere on the screen.

Similarly to loading an MREC, you must pass a BannerAdConfig with the ad size configured to 'MREC' by calling setAdSize(AdConfig.AdSize.VUNGLE_MREC) and passing this object when calling Banners.getBanner to obtain the MREC ad object to be displayed.

Finally, call the addView to associate an ad container with the MREC ad. Vungle MREC plays with sound enabled as a default, but you can call setMuted with true to start the video muted.

private FrameLayout mrecContainer = findViewById(...);

BannerAdConfig bannerAdConfig = new BannerAdConfig();
bannerAdConfig.setAdSize(AdConfig.AdSize.VUNGLE_MREC);
bannerAdConfig.setMuted(true);

VungleBanner vungleBanner = Banners.getBanner("MREC_ID", bannerAdConfig, vunglePlayAdCallback);
mrecContainer.addView(vungleBanner);
mrecContainer.setVisibility(View.VISIBLE)

// Deprecated - 6.9.1 & below
private RelativeLayout mrecContainer = findViewById(...);

AdConfig adConfig = new AdConfig();
adConfig.setAdSize(AdConfig.AdSize.VUNGLE_MREC);
adConfig.setMuted(true);

VungleNativeAd vungleNativeAd = Vungle.getNativeAd("MREC_ID", adConfig, vunglePlayAdCallback);
View nativeAdView = vungleNativeAd.renderNativeView();
mrecContainer.addView(nativeAdView);

Close a Banner Ad

Because the banner ad view has been added to your container view, it must also be removed, in case the ad view disappears from the screen, the activity or fragment is destroyed, or the parent view container is recycled or destroyed.

vungleBanner.destroyAd();

Attach and Detach the State of an MREC Ad

If the user scrolls to a point where the video ad is no longer visible on the screen, you must pause the video, and resume it when it is again visible. To control the pause and resume states, call setAdVisibility from the VungleNativeAd instance, and set it to true when the video is visible and to false when the video goes off screen. The setAdVisibility is not to be confused with View visibility: this setter informs Vungle SDK whether the MREC ad view is visible or not, and depending on it, the SDK pauses or resumes video playback.

• Pause an MREC ad:
  vungleBanner.setAdVisibility(false);

• Resume an MREC ad:
  vungleBanner.setAdVisibility(true);

Step 4. Test an MREC Ad

You can test an MREC 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.