Integrate Interstitial and Rewarded Ads

Overview

About 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.

About 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 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

6.5.0 & above Legacy
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
  }
};
Overridable Methods Description
onAdLoad(String id) Invoked when the ad has been successfully loaded and be played for the placement
onError(String id) Invoked when an error occurs while attempting to play an ad. You will be able to check error message from getLocalizedMessage of VungleException and use getExceptionCode for debugging.

PlayAdCallback

6.6.0 & above Legacy
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 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 } };
Overridable Methods Description
onAdStart(String id) Invoked when the ad is successfully launched and displayed on the device.
onAdEnd(String id) Invoked when the entire ad experience has been completed, just before the control has been returned back to the hosting app.
onAdClick(String id) Invoked when the user has clicked on a video ad or download button.
onAdRewarded(String id) Invoked when the user has completed 80% of the rewarded video and should be rewarded. Rewarding the user should take place here and it will only get triggered for rewarded placements.
onAdLeftApplication(String id) Invoked when the user leaves the app before ad experience is completed, such as opening the Store page for the ad.
onAdError(String id, VungleException exception) Invoked when an error occurs while attempting to play an ad. You will be able to check error message from getLocalizedMessage of VungleException and use getExceptionCode for debugging.

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:

Option

Description

setBackButtonImmediatelyEnabled

'true' if the back button should be enabled before the close ad button appears; 'false' otherwise

setAdOrientation

AdConfig.AUTO_ROTATE if the video ad should auto-rotate; otherwise AdConfig.LANDSCAPE or AdConfig.PORTRAIT to follow video ad orientation

setMuted

'false' if the video should start with its audio settings matching those of your enclosing application; 'true' if it should start muted regardless

setOrdinal

takes an Integer value of ordinal count to track the number of ads that have been played in same session

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.

Powered by Creativity Driven by Performance Sign Up Here

Questions?

Need further assistance, feel free to reach out to us, we’re here to help!

Was this article helpful?