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

Understand Interstitial Ads

Interstitial ads are full-screen ads that cover the interface of your app. They're typically displayed at natural transition points in the flow of your app, such as between activities or during the pause between levels in a game. Some interstitial ads are rewarded ads.

Understand Rewarded Ads

Rewarded ads deliver a great user experience by offering users something of value in exchange for watching or engaging with an ad. This exchange is typically a reward within your app, such as extra lives in a game, virtual currency, or a hint in a puzzle (you determine the nature and amount of the reward). Shown at natural breaks in the app, rewarded video ads deliver high revenue, especially if you follow our recommendation to make them non-skippable.  

Note that rewarded ads are in some cases referred to as incentivized ads; both terms always refer to the same kind of ad. Although "rewarded" is our preferred term, in the SDK code and in our Reporting API, we use the term 'incentivized'.

There are two ways to integrate rewarded ads: in-app rewards (recommended, and described below), or server-to-server callbacks (refer to our FAQ article on this topic). With in-app rewards, when a user successfully completes an ad view or clicks the download button, you can reward them directly in your app. The main benefit of this approach is that it's simple to implement. If you're looking for something quick, and you're not concerned with replay attacks, this should do it.

Vungle now offers a variety of ad formats with Dynamic Template ads. Unlike the traditional ad format, in which an ad play consists of a video play followed by an end card, we offer templates where the call-to-action (CTA) button is available during the video play. The users who complete the video ad, as well as those who click the button, should be rewarded.

Step 1. Complete Basic Integration

To integrate interstitial ads in your Android or Amazon app, begin by following the instructions in the basic integration article. This Interstitial/Rewarded 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 onAdRewarded(String id) {
    // User earned reward for watching an rewarded 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 onAdRewarded(String id) {
    // User earned reward for watching an rewarded 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 onAdRewarded(String id) {
    // User earned reward for watching an rewarded 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 and Play an Ad

Load an Ad for a Placement

The LoadAdCallback will be notified about the load state for the call to which it was assigned. The SDK only references this callback and does not store it anywhere; it is the responsibility of the caller to ensure that the callback is managed properly.

public static void loadAd(@NonNull final String id, @Nullable LoadAdCallback callback)

// Load Ad Implementation
if (Vungle.isInitialized()) {
  Vungle.loadAd("PLACEMENT_ID", new LoadAdCallback() {
    @Override
    public void onAdLoad(String placementReferenceId) { }

    @Override
    public void onError(String placementReferenceId, VungleException exception) { }
  });
}

Check Ad Availability for a Placement

Use the static method canPlayAdmethod to check if there is an ad available to play for the placement before invoking the playAd method.

public static boolean canPlayAd(@NonNull String id)

Play an Ad

To play an ad, invoke the playAd method with the placement reference ID, optional AdConfig (null if not being used), and a PlayAdCallback event listener, which will be notified of success or errors during ad playback.

public static void playAd(@NonNull final String id, final AdConfig settings, @Nullable final PlayAdCallback listener)

Always check ad availability by calling the canPlayAd method before invoking the playAd method. Because an ad will not render properly if playAd is repeatedly called in quick succession, you must also make sure that you receive either an onAdEnd or an onError callback from the initial playAd call before issuing an additional playAd.

if (Vungle.canPlayAd("PLACEMENT_ID")) { 
  Vungle.playAd("PLACEMENT_ID", null, new PlayAdCallback() { 
    @Override public void onAdStart(String placementReferenceId) { } 
    @Override public void onAdEnd(String placementReferenceId, boolean completed, boolean isCTAClicked) { } 
    @Override public void onError(String placementReferenceId, VungleException exception) { } 
  });
}

Step 4. Configure All Fullscreen Ads (Optional)

You have the option to customize individual ads you play by providing a new adConfig object to playAd. When the AdConfig object is null, the ad plays with the default configuration settings; when it is non-null, its settings override those in the AdConfig setter. The following is an example of how to use AdConfig:

Vungle.playAd(placementReferenceID, adConfig, vunglePlayAdCallback);

The above example uses the adConfig object, which contains customized configuration options. Set the AdConfig object as shown:

AdConfig adConfig = new AdConfig();
adConfig.setAdOrientation(AdConfig.AUTO_ROTATE);
adConfig.setMuted(true);
Vungle.playAd(placementReferenceID, adConfig, vunglePlayAdCallback);

The following table lists all the available AdConfig options:

Note: You may use the same AdConfig object for multiple ads.

Step 5. Customize Rewarded Ads (Optional)

Pop-Up Message Dialog

The pop-up message dialog for rewarded ads is configurable with the setIncentivizedFields method.

public static void setIncentivizedFields(@Nullable String userID, @Nullable String title, @Nullable String body, @Nullable String keepWatching, @Nullable String close)

Reward Considerations

There is no standard for rewarding users. Your decision depends on how your game economy works. A developer should reward the user just enough to make the video option attractive, but not so much that the reward replaces an IAP purchase. Placing a Daily View Cap on rewarded videos is also important; it limits the number of rewards per user.

Here are a few questions you should ask when deciding the right amount to reward:

1. What is more valuable to the user: soft or hard currency?
   Soft currency is cheaper to give away, but users may be more apt to watch a video for an item they can use right away. You can also use the rewarded video as a way to introduce new items to the user, incentivizing them to purchase the IAP later on.
2. How enticing is the reward to the user?
   You want to make sure the reward is something that the user actually needs or wants and is not easy to come by.
3. How does the reward compare to the most common IAP?
   You will want the reward to be the stepping stone to get that IAP, or something that the user may want, but never buys.
4. How does the reward compare to what the user will earn on average by playing the game?
   If the user earns the same reward amount by just playing a single level, the user may not perceive that the reward is worth 15 seconds of his/her time.
5. Should I cap the number of rewards per user per day?
   Yes. Setting a Daily View Limit can help you control how many free items/coins the user can earn.

Our Account Management team is also there to help. Email us at monetize@vungle.com.

Step 6. Test an Interstitial or Rewarded Ad

You can test an Interstitial or Rewarded 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.