Integrate Banner Ads on Vungle SDK v.6 for iOS

Starting with Vungle SDK v.6.5.1, we support banner ads. This ad format does not require a full screen; instead, the publisher determines the location of the ad container within their app. However, the size of the banner container must be either 320x50, 300x50, or 728x90 (for tablets). You can set banner ads anywhere on the screen, and the user can continue using the app while the ad is being played. The Enum listing the different banner sizes can be found in the VungleSDK.h file (also described in the table below).

The placement type for banner ads must have the type "Banner" in the Liftoff Monetize dashboard. Feel free to contact your account manager to enable banner placement on the dashboard.

Step 1. Complete Basic Integration

To integrate banner ads in your iOS app, begin by following the instructions in the basic integration article. This Banner 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, Display, and Close a Banner Ad

Load a Banner Ad

Loading a banner ad works differently from other ad formats. Use the following API to load the banner ad. You must specify size of the banner that you want to load and the SDK automatically refreshes the banner following the time interval that you configured on the dashboard. Refer the above table for enum values that required by the load call.

Function overview:

/**
 * (Overloaded method)
 * Prepares a placement when you know that you will want
 * to show an ad experience tied to a specific placementID.
 * @param placementID the specific ID of the placement you would like to present at some point soon
 * @param size the VungleAdSize (enum) you would like to request (only for banner ad type at the moment)
 * @return NO if something goes immediately wrong with loading, YES otherwise
 */
- (BOOL)loadPlacementWithID:(NSString *)placementID withSize:(VungleAdSize)size error:(NSError **)error;

Sample code:

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

You can also check for the banner ad availability by calling the following API:

Function overview:

/**
* (Overloaded method)
 * Returns `YES` when there is certainty that an ad will be able to play for a given placementID.
 * Returning `NO`.
 * @param size the VungleAdSize (enum) you would like to request (only for banner ad type at the moment)
 * @param placementID the specific ID of the placement you are trying to present
 */
- (BOOL)isAdCachedForPlacementID:(nonnull NSString *)placementID withSize:(VungleAdSize)size;

Sample code:

if([sdk isAdCachedForPlacementID:@"Your_placement_ID_Here" withSize:BANNER_ENUM]){
     //Ad is cached successfully
}

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;

Display a Banner Ad

You must first create a container for the banner ads. This container is a UIView with the size of either 300×250 , 320x50, or 728x90 (for iPads only). You can place this UIView anywhere on the screen.
You must then call the addAdViewToView function to associate the container with the banner ad.

Function overview:

/**
 * Pass in an UIView which acts as a container for the ad experience. This view container may be placed in random positions.
 * @note This method should only be called using placements that have the `mrec` template type. ALSO, for the
 *`mrec` template type, note that the UIView must have a width of 300 and a height of 250. If the view is provided without
 * these dimensions, an error message will be returned and the ad will not be shown.
 * @param publisherView container view in which an ad will be displayed
 * @param options A reference to an instance of NSDictionary with customized ad playback options
 * @param placementID The placement defined on the Liftoff Monetize dashboard
 * @param error An optional double reference to an NSError. In case this method returns `NO` it will be non-nil
 * @return YES/NO in case of success/error while presenting an AdUnit
 */
- (BOOL)addAdViewToView:(UIView *)publisherView withOptions:(nullable NSDictionary *)options placementID:(nullable NSString *)placementID error:(NSError *__autoreleasing _Nullable *_Nullable)error;

Sample code:

NSError *error;
VungleSDK* sdk = [VungleSDK sharedSDK];
if (![sdk addAdViewToView:<Banner_View_Area> withOptions:options placementID:@"Your_placement_ID_Here" error:&error]) {
    if (error) {
        NSLog(@"Error encountered while playing an ad: %@", error);
    }
}

Close a Banner Ad

Call the finishedDisplayingAd function to close the banner ad. Depending on your implementation, you may need to include some cleanup (such as removing the banner container UIView from its parent view, etc).

Function overview:

- (void)finishDisplayingAd:(NSString*)placementId;

//Deprecated as of 6.7.0
- (void)finishedDisplayingAd;

Sample code:

VungleSDK* sdk = [VungleSDK sharedSDK];
[sdk finishedDisplayingAd:@"BANNER_PLACEMENTID_HERE"];

Step 4. Customize Banner Ads (Optional)

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.

Pass the Mediation Ordinal

If you receive ordinal data reports from Vungle, use the VunglePlayAdOptionKeyOrdinal field to pass the mediation ordinal. This is an integer indicating the order in which this ad was shown in the game session (for example, if two ads were already shown in this session, and this ad from Vungle was then shown third, pass in '3'). Read more about ordinal data here.

Step 5. Test a Banner Ad

You can test a Banner 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.