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

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 iOS 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. Receive Delegate Callbacks

This is a very important step for every format. Follow the instructions in the Receive Delegate Callbacks section of the Advanced Settings article.

Step 3. Load and Play an Ad

Load an Ad for a Placement

To load an ad, call the loadPlacementWithID method:

- (BOOL)loadPlacementWithID:(NSString *)placementID error:(NSError **)error;

Sample code:

NSError* error;
VungleSDK* sdk = [VungleSDK sharedSDK];
NSString* placementID = @"Your_Placement_ID_Here";
if (![sdk loadPlacementWithID:placementID error:&error]) {
    if (error) {
        NSLog(@"Error occurred when loading placement: %@", error);
    }
}

var sdk:VungleSDK = VungleSDK.shared()
do {
    try sdk?.loadPlacement(withID: <Your_PlacementID>)
} catch let error as NSError {
    print("Unable to load placement with reference ID :\(<Your_PlacementID>), Error: \(error)")
    return
}

Check Ad Availability for a Placement

Once the SDK finishes caching an ad for a placement, the following callback method is called:

- (void)vungleAdPlayabilityUpdate:(BOOL)isAdPlayable placementID:(nullable NSString *)placementID error:(nullable NSError *)error;

Sample code:

- (void)vungleAdPlayabilityUpdate:(BOOL)isAdPlayable placementID:(NSString *)placementID error:(nullable NSError *)error {
    NSLog(@"vungleAdPlayabilityUpdate called");
}

func vungleAdPlayabilityUpdate(_ isAdPlayable: Bool, placementID: String?) {
    print("vungleAdPlayabilityUpdate called")
}

Note: For the cache-optimized placements, this callback method is called only when an ad becomes available. The SDK will keep requesting an ad for these placements. For all other placements, this callback method is called in case of “Load Failed” (isAdPlayable returns ‘NO’ in this case).

You can also check the ad availability for a placement with the following property:

- (BOOL)isAdCachedForPlacementID:(nonnull NSString *)placementID;

Play an Ad

After you make sure that an ad is ready for a placement, you can play the ad with the following method:

- (BOOL)playAd:(UIViewController *)controller options:(nullable NSDictionary *)options placementID:(nullable NSString *)placementID error:( NSError *__autoreleasing _Nullable *_Nullable)error;

Sample code:

VungleSDK* sdk = [VungleSDK sharedSDK];
NSError *error;
if (![sdk playAd:self options:nil placementID:@"Your_placement_ID_Here" error:&error]) {
    if (error) {
        NSLog(@"Error encountered playing ad: %@", error);
    }
}

var sdk:VungleSDK = VungleSDK.shared()
do {
    try sdk.playAd(self, options: nil, placementID: kVungleTestPlacementID01)
} catch let error as NSError {
    print("Error encountered playing ad: + \(error)");
}

Step 4. Configure All Fullscreen Ads (Optional)

Use these options to customize the ad experience for playback.

Note: Rewarded ads are in some cases referred to as incentivized ads; both terms always refer to the same kind of ad. In the SDK code and in our Reporting API, we use the term 'incentivized'.

Sample code:

NSDictionary *options = @{VunglePlayAdOptionKeyOrientations: @(UIInterfaceOrientationMaskLandscape),
                          VunglePlayAdOptionKeyUser: @"userGameID",
                          VunglePlayAdOptionKeyIncentivizedAlertBodyText : @"If the video isn't completed you won't get your reward! Are you sure you want to close early?",
                          VunglePlayAdOptionKeyIncentivizedAlertCloseButtonText : @"Close",
                          VunglePlayAdOptionKeyIncentivizedAlertContinueButtonText : @"Keep Watching",
                          VunglePlayAdOptionKeyIncentivizedAlertTitleText : @"Careful!"};

// Pass in dict of options, play ad
NSError *error;
if (![self.sdk playAd:self options:options placementID:@<Placement_ID_Here> error: &error] {
    if (error) { 
        NSLog(@"Error encountered playing ad: %@", error); 
    }
}

let options: NSDictionary = NSDictionary(dictionary: [VunglePlayAdOptionKeyUser: "test_user_id",
                            VunglePlayAdOptionKeyIncentivizedAlertBodyText: "If the video isn't completed you won't get your reward! Are you sure you want to close early?",
                            VunglePlayAdOptionKeyIncentivizedAlertCloseButtonText: "Close",
                            VunglePlayAdOptionKeyIncentivizedAlertContinueButtonText: "Keep Watching",
                            VunglePlayAdOptionKeyIncentivizedAlertTitleText: "Careful!"])
do {
    try self.sdk.playAd(self, options: (options as! [AnyHashable : Any]), placementID: PlacementID)
} catch let error as NSError {
    print("Error encountered playing ad: + \(error)");
}

Mute Option

The Vungle SDK instance offers the option to play ads with the sound disabled. You can set the muted property to 'true' before issuing a playAd().

Sample code:

VungleSDK* sdk = [VungleSDK sharedSDK];
sdk.muted = YES;

var sdk:VungleSDK = VungleSDK.shared()
sdk.muted = true

Note: This option only applies to the standard ad type for Vungle SDK version 6.3.1 and lower. The muted option for Dynamic Template ads is available to configure on the dashboard. Starting with Vungle SDK v6.3.2, Vungle will respect the SDK-side mute setting for all ads.

Step 5. Customize Rewarded Ads (Optional)

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.