Contents

GDPR: Recommended Implementation

As of May 25th, the General Data Protection Regulation (GDPR) will be enforced in the European Union. To comply with GDPR, developers have two options.

Option 1 (recommended): Publisher controls the GDPR consent process at the user level, then communicates the user’s choice to Vungle. To do this, developers can collect the user’s consent using their own mechanism, and then use Vungle APIs to update or query the user’s consent status. Refer to the GDPR Recommended Implementation Instructions section for details.

Option 2: Allow Vungle to handle the requirements. Vungle will display a consent dialog before playing an ad for a European user, and will remember the user’s consent or rejection for subsequent ads.

Before You Get Started

The Vungle iOS SDK v. 6 supports iOS 8+.

The Vungle iOS SDK v. 6 has been tested with the latest iOS 12 beta available on release date.

The Vungle iOS SDK v. 6 supports both 32bit and 64bit apps.

Integration requires you to have a Vungle account. If you don't yet have an account, create one before proceeding.

Step 1. Add the Vungle Framework to your Xcode Project

Add the VungleSDK.framework to your Project

Cocoapods

The Vungle SDK is available through Cocoapods. Add Vungle to your project by adding the following line into your project’s podfile.

pod "VungleSDK-iOS", "6.3.2"

After that, a quick pod install run will update your project with the latest version of our iOS SDK. At this point you can skip down to “Step 2. Remove the iOS Status Bar”.

Manual Integration

Download Vungle SDK v6. If you are updating from a previous version of the Vungle SDK, first remove the VungleSDK.framework directory completely before adding the new SDK.

Find the extracted files and drag the VungleSDK.framework directory into Xcode under Frameworks. Be sure to add the VungleSDK.framework folder as a group (yellow folder) and not as a reference (blue folder).

Add Other Required Frameworks

The Vungle SDK requires that you link a few other native frameworks to your project, so click on your project in Project Navigator and go to General → Linked Frameworks and Libraries.

Many of these frameworks are already included as a default for most Xcode projects, but be sure to add any of the following that are not already included:

AdSupport.framework

AudioToolbox.framework

AVFoundation.framework

CFNetwork.framework

CoreGraphics.framework

CoreMedia.framework

libz.dylib or libz.tbd

MediaPlayer.framework

QuartzCore.framework

StoreKit.framework

SystemConfiguration.framework

Note: Vungle SDK V.6 does not support iOS 7. If you have iOS 7 as a deployment target, use Vungle iOS SDK v.4.1 or lower, and include these frameworks:

UIKit.framework

WebKit.framework

Foundation.framework

Make sure that the VungleSDK framework appears under Linked Frameworks and Libraries.

Add the “-ObjC” Linker Flag

Step 2. Remove the iOS Status Bar

Although this step is not required, we recommend that you remove the iOS status bar to ensure that Vungle's ad interaction and presentation perform smoothly. To remove the status bar, open your Info.plist, add the key View controller-based status bar appearance, and set it to No.

Step 3. Add Code

Initialize the SDK

Initialize the SDK as soon as your app starts; if you are using an auto-cached placement, doing this gives the SDK enough time to cache an ad for that auto-cached placement. You will need the App ID to initialize the SDK. You can find the App ID in the Vungle Dashboard.

You can also check the status of the SDK initialization with the following property:

@property (atomic, readonly, getter=isInitialized) BOOL initialized;

After the SDK is initialized, if you selected a placement as Auto Cached in the Vungle Dashboard, the SDK automatically caches an ad for that placement. If you use this feature, we recommend selecting the most viewed placement for auto-caching.

Once an ad is cached successfully, the vungleAdPlayabilityUpdate callback method is called with the placement reference ID matching your Auto Cached placement. (Refer to the “Check Ad Availability for a Placement” section of this article.)

Load an Ad for a Placement

For placements other than the auto-cached placement, call loadPlacementWithID method to load an ad.

Note: For the auto-cached placement, only when an ad becomes available is this callback method called. The SDK will keep requesting an ad for the auto-cached placement. 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:

Flex Feed Ads

Since Vungle SDK v.5.3, we support Flex Feed ads. This is the first ad format that does not require a full screen; instead, the publisher determines the exact dimensions and location of the ad container within their app. These ad containers can be in collection views or table views.

Loading a Flex Feed Ad

Loading a Flex Feed ad is the same as loading a fullscreen ad; however, the placement must be configured to support Flex Feed. Contact your Vungle account manager to enable Flex Feed for a placement.

Displaying a Flex Feed Ad

Displaying Flex Feed ads differs from displaying fullscreen ads. With Flex Feed ads, you must first create a container for the ad. This container is a UIView. You can place said UIView anywhere on the screen. The ad will scale to any size of container, but keep in mind that very low resolution will make ads less visible. You must then call the addAdViewToView function to associate the container with the Flex Feed 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.
* @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 Vungle 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;

Closing a Flex Feed Ad

Due to the nature of Flex Feed ads, a user can stop viewing the video without closing the ad. You must therefore tell the SDK to dismiss the ad when it is no longer on screen. To do this, call the finishedDisplayingAd function. This function only works with Flex Feed and Flex View ads. Note that this function does not take in a placement; it will simply close any native ad currently playing.

Function overview:

/**
* This method must be called when the publisher is confident that they are finished displaying the ad unit.
* This signals to the SDK that a new ad may be fetched or a different ad may be displayed. This will
* be called in conjunction with `addViewToView:containedInViewController:withOptions:placementID:error:`
*/
- (void)finishedDisplayingAd;

VungleViewInfo includes the following properties for you to check a result of ad play:

@interface VungleViewInfo : NSObject
//Represents a BOOL whether or not the video can be considered a completed view.
@property (nonatomic, readonly) NSNumber *completedView;
//The time in seconds that the user watched the video.
@property (nonatomic, readonly) NSNumber *playTime;
//Represents a BOOL whether or not the user clicked the download button.
@property (nonatomic, readonly) NSNumber *didDownload;
@end

The following method is called when the SDK has changed ad availability status. The isAdPlayable boolean denotes the new playability of a specific placementID.

The following method is called when the SDK is initialized successfully:

- (void)vungleSDKDidInitialize;

Customization Options

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

Option Keys

Default Value / Type

Description

VunglePlayAdOptionKeyOrientations

autorotate

UIInterfaceOrientationMaskAll

An NSNumber representing a bitmask with orientations

Sets the orientation of the ad. We recommend allowing ads to autorotate, even if your app is in portrait. This way, the user has the option to watch full-size videos, resulting in a better user experience. You can achieve this by setting the orientation on a view controller level (rather than a project level).

VunglePlayAdOptionKeyUser

nil

NSString

Sets your user ID. The value is passed to Vungle server, and then sent to your server through server-to-server callback system if an placement is set to “Rewarded”.

VunglePlayAdOptionKeyIncentivizedAlertTitleText

nil

NSString

String that is used as the title of the alert dialog presented when a user closes a rewarded ad experience prematurely.

VunglePlayAdOptionKeyIncentivizedAlertBodyText

“Are you sure you want to skip this ad? If you do, you might not get your reward”

NSString

String that is used as the body text of the alert dialog presented when a user closes a rewarded ad experience prematurely.

VunglePlayAdOptionKeyIncentivizedAlertCloseButtonText

“Close”

NSString

String title for the close button text of the alert dialog presented when a user closes a rewarded ad experience prematurely.

VunglePlayAdOptionKeyIncentivizedAlertContinueButtonText

“Continue”

NSString

String title for the close button text of the alert dialog presented when a user closes a rewarded ad experience prematurely.

VunglePlayAdOptionKeyFlexViewAutoDismissSeconds

Int

Use this option to make Flex View ads dismiss automatically after the specified number of seconds. This function only works with Flex View ads.

VunglePlayAdOptionKeyOrdinal

Int

If you receive ordinal data reports from Vungle, use this 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.

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];
self.sdk.muted = true;

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

GDPR Recommended Implementation Instructions

To use Vungle APIs to update or query the user’s consent status (as recommended in Option 1 of Vungle's GDPR: Recommended Implementation), use these functions for v6.3.2 and above:

// This function sets the consent status that will be recorded in Vungle SDK. Accepted values: 'VungleConsentAccepted' or 'VungleConsentDenied'. It also sets the consent message version. This value is an arbitrary string, and can be used to identify the version of the consent message presented to the user.
// To set the user's consent status to opted in:
[[VungleSDK sharedSDK] updateConsentStatus:VungleConsentAccepted consentMessageVersion:@"Some Consent Message Version"];
// To set the user's consent status to opted out:
[[VungleSDK sharedSDK] updateConsentStatus:VungleConsentDenied consentMessageVersion:@"Some Consent Message Version"];
// To find out what the user's current consent status is:
// (Check against enum values: 'VungleConsentAccepted' or 'VungleConsentDenied'.)
[[VungleSDK sharedSDK] getCurrentConsentStatus];
// To find out which version of the consent message was shown to the user:
// This method returns an NSString value.
[[VungleSDK sharedSDK] getConsentMessageVersion];

VungleConsentStatus is an enum containing two states:

VungleConsentAccepted

VungleConsentDenied

The SDK also has an initial state of 'unknown', which prompts the user to opt in or opt out of user data collection. Note that this prompt only occurs on IP addresses originating from Europe.

v6.2.0 does not have ability to pass consent message version, so please use following APIs.

// This function sets the consent status that will be recorded in Vungle SDK. Accepted values: 'VungleConsentAccepted' or 'VungleConsentDenied'.
// To set the user's consent status to opted in:
[[VungleSDK sharedSDK] updateConsentStatus:VungleConsentAccepted]
// To set the user's consent status to opted out:
[[VungleSDK sharedSDK] updateConsentStatus:VungleConsentDenied];
// To find out what the user's current consent status is:
// (Check against enum values: 'VungleConsentAccepted' or 'VungleConsentDenied'.)
[[VungleSDK sharedSDK] getCurrentConsentStatus];

Debug

If you need SDK information, you can get it by using this property:

- (NSDictionary *)debugInfo;

If you want the SDK to output logs, use the following method:

- (void)setLoggingEnabled:(BOOL)enable;

VungleSDKLogger Protocol

The VungleSDK singleton sends logging events to any attached class following the VungleSDKLogger protocol. The log event contains the NSString value that is also printed to console (if logging has been enabled). To attach your logger, use the following:

[sdk attachLogger:yourLoggerInstance];

As mentioned above, it's important to clear out attached loggers from the Vungle SDK. Loggers can be detached using the following approach:

[sdk detachLogger:yourLoggerInstance];

assetLoader Protocol

@protocol VungleAssetLoader
/**
* should return a valid NSData containing the (raw) data of an image for the specified path or nil. */
- (NSData*)vungleLoadAsset:(NSString*)path;
/**
* should return a valid UIImage for the specified path, or nil.
*/
- (UIImage*)vungleLoadImage:(NSString*)path;
@end