BETA - Get Started with Vungle - iOS SDK v6.4.1

Please direct integration issues or Beta related bugs to early.adoption@vungle.com. Beta SDKs will not be supported upon beta testing completion. We recommend you update to the latest SDK version, once Beta testing is completed.

Table of Contents

Before You Get Started

  • Vungle iOS SDK v. 6.4.1 supports iOS 9+. The SDK can be integrated into applications that ship with a deployment target of iOS 8 and higher. We do not recommend integrating the SDK in iOS versions lower than 8.0.
  • The Vungle iOS SDK v. 6.4.1 has been tested with the latest iOS version 12.3.
  • The Vungle iOS SDK v. 6.4.1 supports both 32-bit and 64-bit apps.
  • Integration requires you to have a Vungle account. If you don't yet have an account, create one before proceeding.

The Vungle iOS SDK v.6.4.1 supports Xcode 9.0 or higher. For the best experience, we recommend that you use the most recent version of Xcode (10.2.1 as of release date). 

Sample App

https://github.com/Vungle/iOS-SDK/tree/BETA-6.4.1

Download the SDK

https://drive.google.com/open?id=1oDYs51mSDqWrOiMG5KvCYAilxNvrVz6G

Step 1. Add the Vungle Framework to your Xcode Project

Add the VungleSDK.framework to your Project

There are two ways to add Vungle to your Xcode project: using Cocoapods or manual integration.

Cocoapods

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

source 'https://github.com/Vungle/ios-sdk-beta.git'
pod "VungleSDK-iOS", "6.4.1"

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.4.1 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 now ships with the build setting Link Frameworks Automatically set to YES, meaning you should no longer be required to link all the previously required frameworks and libraries (see below). With this update, you should only need to optionally link the following frameworks: included:

  • CoreFoundation.framework
  • Foundation.framework
  • StoreKit.framework

These previously required frameworks and libraries are included here so you can remove them if your project doesn’t reference any of them:

  • Support.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.4.1 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

Click on your project in Project Navigator and go to Build Settings → Linking → Other Linker Flags. Add -ObjC to Other Linker Flags.

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 a cache-optimized placement, doing this gives the SDK enough time to cache an ad for that placement. You will need the App ID to initialize the SDK. You can find the App ID in the Vungle Dashboard.

- (BOOL)startWithAppId:(nonnull NSString *)appID error:(NSError **)error;

Sample code:

#import <VungleSDK/VungleSDK.h>
...
NSError* error;
NSString* appID = @"Your_AppID_Here";
VungleSDK* sdk = [VungleSDK sharedSDK];
If (![sdk startWithAppId:appID error:&error]) {
if (error) {
NSLog(@"Error encountered starting the VungleSDK: %@", error);
}
}

Once the SDK is initialized successfully, the following callback method is called:

- (void)vungleSDKDidInitialize;

Refer to the “Delegate Callbacks” section of this article.

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

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

  • With the latest SDK v6.4.1, after initialization we will automatically optimize the caching behaviors to maximize your monetization performance.
  • Once initialization is successful, watch for the vungleAdPlayabilityUpdate callback method to be called with the placement reference IDs matching your cache-optimized placement. (Refer to the “Check Ad Availability for a Placement”)

Load an Ad for a Placement

To load an ad, you will need to call loadPlacementWithID method:

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

Sample code: 

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

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 {
    if([placementID isEqualToString:@"Your_placement_ID_Here"]) {
        self.playButtonPlacement1.enabled = isAdPlayable;
    }
}

⚠️Note: For the cache-optimized placements, only when an ad becomes available is this callback method called. 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);
}
}

In-Feed Ads

Since Vungle SDK v.5.3, we support In-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 an In-Feed Ad

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

Displaying an In-Feed Ad

Displaying In-Feed ads differs from displaying fullscreen ads. With In-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 In-Feed ad.

⚠️Note: If the UIView created for the In-Feed ad is created in Interface Builder, you should create a local UIView instance (of the same width and height as the IB view) and add that as a subview to the Interface Builder view. This will allow you to add and remove the In-Feed view and reuse the In-Feed UIView container as needed.

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;

Sample code:

NSError *error;
NSDictionary *options = @{};
VungleSDK* sdk = [VungleSDK sharedSDK];
@property (strong, nonatomic) UIView *tempIn-FeedFeedView;
// Play a Vungle ad (with default options)
if (!self.tempIn-FeedFeedView) {
// This view has the same size as the corresponding view created in interface builder
self.tempIn-FeedFeedView = [[UIView alloc] initWithFrame:self.In-FeedFeedView.bounds];
}
// add temp view as subview to view created in Interface Builder
[self.In-FeedFeedView addSubview:self.tempIn-FeedFeedView];
NSError *error;
[self.sdk addAdViewToView:self.tempIn-FeedFeedView withOptions:nil placementID:placementID error:&error];
if (![sdk addAdViewToView:_In-FeedFeedViewArea withOptions:options placementID:@"Your_placement_ID_Here" error:&error]) {
if (error)
{
NSLog(@"Error encountered while playing an ad: %@", error);
}
}

Closing an In-Feed Ad

Due to the nature of In-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 MREC and In-Feed ads. Note that this function does not take in a placement; it will simply close any native ad currently playing. Depending on the implementation, you may need to include some cleanup (removing the In-Feed container UIView from its parent view, etc.).

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;

Sample code:

//Ad is no longer on screen
VungleSDK* sdk = [VungleSDK sharedSDK];
[sdk finishedDisplayingAd];
[self.tempIn-FeedFeedView removeFromSuperview];
self.tempIn-FeedFeedView = nil;

⚠️Note: Only one In-Feed Ad should be playing at a time. Hence you should make sure you dismiss any In-Feed Ad before attempting to play another ad.

MREC Ads

Since Vungle SDK v.6.4.1, we support MREC ads. Similarly to In-Feed 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 MREC container has to be 300 × 250, which is the industry standard.

Loading an MREC Ad

Similarly to In-Feed, the placement type for MREC has to have the type MREC in Vungle dashboard.

Displaying an MREC Ad

Similarly to In-Feed ads, you must first create a container for the MREC ads. This container is a UIView having the size of 300 × 250. You can place said UIView anywhere on the screen.
You must then call the addAdViewToView function to associate the container with the MREC 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;

Sample code:

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

Closing an MREC Ad

Similarly to In-Feed ads, to close an MREC ad, call the finishedDisplayingAd function. This function only works with MREC and In-Feed ads. Note that this function does not take in a placement; it will simply close any native ad currently playing. Depending on the implementation, you may need to include some cleanup (removing the In-Feed container UIView from its parent view, etc).

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;

Sample code:

//Ad is no longer on screen
VungleSDK* sdk = [VungleSDK sharedSDK];
[sdk finishedDisplayingAd];

Delegate Callbacks

You can receive callbacks from the SDK with VungleSDKDelegate. There are four callback methods in the delegate in which you are notified of the SDK events.

You can attach and detach your delegate with:

// Attach
[[VungleSDK sharedSDK] setDelegate:yourDelegateInstance];
// Detach
[[VungleSDK sharedSDK] setDelegate:nil];

⚠️Note: Remember to clear the registered delegate when it's no longer needed to avoid memory leaks.

The following method is called when the SDK is about to play a video ad. This is a great place to pause gameplay, sound effects, animations, etc.

- (void)vungleWillShowAdForPlacementID:(nullable NSString *)placementID;

The following method is called when the SDK is about to close an ad. This is a great place to reward your user and resume gameplay, sound effects, animations, etc.

- (void)vungleWillCloseAdWithViewInfo:(VungleViewInfo *)info placementID:(NSString *)placementID;

The following method is called when the SDK has closed an ad:

- (void)vungleDidCloseAdWithViewInfo:(VungleViewInfo *)info placementID:(NSString *)placementID;

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.

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

(Please refer to “Check Ad Availability for a Placement” .)

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

- (void)vungleSDKDidInitialize;

The following method is called when the SDK fails to initialize. If this happens, you’ll need to restart the Vungle SDK.

- (void)vungleSDKFailedToInitializeWithError:(NSError *)error;

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.

 

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;
[self.sdk playAd:self options:options placementID: error:&error];

if (error) {
    NSLog(@"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];
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.

Memory Settings

Starting from v6.4.1, you can prevent the SDK from downloading, requesting ads or even initializing if the storage of your iPhone falls below a predefined threshold. If this happens, you will get an error similar to the following:

Error while starting VungleSDK There is not enough file system size on a device to initialize VungleSDK.

These are the option keys available:

Option Keys

Default Value / Type

Description

vungleMinimumFileSystemSizeForInit

Integer, value in MB, default value is 50

Sets the required minimum available free storage space to be able to initialize the SDK

vungleMinimumFileSystemSizeForAdRequest

Integer, value in MB, default value is 50

Sets the required minimum available free storage space to be able to request an ad

 

Sample code:

 

[[NSUserDefaults standardUserDefaults] setInteger:200 forKey:@"vungleMinimumFileSystemSizeForInit"];
[[NSUserDefaults standardUserDefaults] setInteger:200 forKey:@"vungleMinimumFileSystemSizeForAdRequest"];
//After setting the desired values above, synchronize
[[NSUserDefaults standardUserDefaults] synchronize];

 

GDPR Recommended Implementation Instructions

As of May 25th 2018, 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.

To use Vungle APIs to update or query the user’s consent status (as recommended in Option 1), 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

@protocol VungleSDKLogger 
- (void)vungleSDKLog:(NSString*)message;
@end

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:

[[VungleSDK sharedSDK] 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:

[[VungleSDK sharedSDK] detachLogger:yourLoggerInstance];

Check Initialization State

Some of the resources allocated to Vungle SDK can be terminated by OS if system resources are running low or many context switching take place. We recommend checking SDK initialization state before invoking SDK API to ensure smooth operation of SDK. Invoke isInitialized before calling any SDK API and re-initialize SDK if it returns NO.

if ([self.sdk isInitialized] == NO) {
   [self initVungleSDK];
}
Was this article helpful?
0 out of 0 found this helpful