Advanced Settings - Vungle iOS SDK v.1.0 - v.4.1

Table of Contents

  1. The Vungle SDK Instance
  2. Customized Ad Experiences
  3. Additional VungleSDK Protocols

Before we get started...

This article covers the advanced settings of the Vungle iOS SDK. If you're not familiar with our iOS SDK, you'll want to check out our getting started guide for iOS.

The VungleSDK Instance

Instance Properties

The VungleSDK singleton instance has a few properties available for customizing your end user's ad experience or for receiving important event data.  They're listed below:

muted (BOOL): Controls whether presented ads will start in a muted state or not
delegate (id<VungleSDKDelegate>): Assignable property following the VungleSDKDelegate protocol which allows apps to receive asynchronous callbacks for certain SDK events
assetLoader (id<VungleAssetLoader>):  Assignable property following the VungleAssetLoader protocol allowing apps to override the required assets used in the main VungleSDK playAd ViewController

 

Instance Methods & Helper Constants

(BOOL)isAdPlayable; Returns YES if there's a cached ad ready to be displayed and the current user isn't limited by daily views or rates. This doesn't check whether there might be a streaming ad available, even if the publisher is opted in for streaming.
(NSDictionary*)debugInfo; Returns an NSDictionary with various debug information about the VungleSDK singleton
(void)setLoggingEnabled:(BOOL)enable;  Enables or disables default logging functionality from the VungleSDK singleton.  Logged events and information will be printed to console.  To handle individual logging events, see the attachLoggermethod below.
(void)log:(NSString*)message, ... NS_FORMAT_FUNCTION(1,2);  Logs the specified message to console and all attached VungleSDKLogger instances.
(void)attachLogger:(id<VungleSDKLogger>)logger Allows the app to attach a class following the VungleSDKLogger protocol to the VungleSDKsingleton instance. The attached logger will receive every log event handled by the SDK.  To avoid memory leaks, it's important to properly detach the logger once it is no longer needed.  TheVungleSDK singleton instance will retain the attached logger until it has been properly removed.
(void)detachLogger:(id<VungleSDKLogger>)logger; Detaches a logger object.
NSString* VungleSDKVersion  A string constant noting the current version of the Vungle iOS SDK.  Includes major and minor versions. 

Customized Ad Experience

The playAd method on the VungleSDK singleton can accept an NSDictionary parameter allowing an app to customize an individual ad experience.  Any valid key/value pairs included in the NSDictionary parameter will override the default value for the noted setting. All keys are optional to add to the dictionary. The settings included in the NSDictionary parameter will only affect a single playAd call. You can find an example of an options dictionary on line 111 or 131 of the sample app.

Key Default Value / Type Description
VunglePlayAdOptionKeyIncentivized NO
NSNumber representing a bool value.
Marking an ad play as incentivized will cause slightly different behavior than a default playAd call, both from the local SDK and from the Vungle ad servers. This feature can be used to help separate behavior and functionality between rewarded placement ads and normally occurring ads.  For a detailed walkthrough on the differences between incentivized and non-incentivized ads, check out our documentation here.
VunglePlayAdOptionKeyOrientations UIInterfaceOrientationMaskAll
An NSNumber representing a bitmask with orientations (defaults to autorotate).
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 acheive this by setting the orientation on a view controller level (rather than a project level).
VunglePlayAdOptionKeyUser nil
NSString with user identifier that will be passed if the ad is incentivized.
The value passed as 'user' in the an incentivized server-to-server call.
VunglePlayAdOptionKeyIncentivizedAlertTitleText nil
NSString
String that is used as the title of the alert dialog presented when a user closes an incentivized 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 an incentivized ad experience prematurely.
VunglePlayAdOptionKeyIncentivizedAlertCloseButtonText Close
NSString
String title for the close button text of the alert dialog presented when a user closes an incentivized ad experience prematurely.
VunglePlayAdOptionKeyIncentivizedAlertContinueButtonText Continue
NSString
String title for the close button text of the alert dialog presented when a user closes an incentivized ad experience prematurely.
VunglePlayAdOptionKeyExtraInfoDictionary nil
NSDictionary containing the extra keys (defined below).
Basic metadata dictionary that can be used to keep track of metrics such as age group, gender, etc.
VunglePlayAdOptionKeyExtra1..8 nil
NSString representing each user metric you are tracking.
COMING SOON - This feature hasn't been completed yet, but once it is you'll be able to use the 8 keys here to track and report on additional information about ad placements, user data, etc.

Protocols

VungleSDKDelegate Protocol


@protocol VungleSDKDelegate 
- (void)vungleSDKAdPlayableChanged:(BOOL)isAdPlayable;
- (void)vungleSDKwillShowAd;
- (void)vungleSDKwillCloseAdWithViewInfo:(NSDictionary*)viewInfo willPresentProductSheet:(BOOL)willPresentProductSheet;
- (void)vungleSDKwillCloseProductSheet:(id)productSheet;
@end    

VungleSDKDelegate Methods

You can implement the VungleSDK Delegate which can alert you to some useful events with regards to the ad experience.

Method Description
(void)vungleSDKAdPlayableChanged:(BOOL)isAdPlayable Called when the VungleSDK has changed ad availability status.  isAdPlayable boolean denotes the new playability of the Vungle SDK
(void)vungleSDKwillShowAd Called when the VungleSDK is about to play a video ad.  The override of this method is a great place to pause gameplay, sound effects, animations, etc.
(void)vungleSDKwillCloseAdWithViewInfo:
(NSDictionary *)viewInfo  willPresentProductSheet:(BOOL)willPresentProductSheet

There are three ways a user might leave an ad experience:

  • by completing the video ad (where the presented ad closes automatically
  • by pressing the close button on an in-progress or completed ad
  • by clicking the download button, in which case we open the in-app app store that iOS provides (using the StoreKit framework)

In all of these cases, this callback is fired, as the main Vungle ViewController is dismissed. The viewInfo NSDictionary contains the following information:

  • completedView: NSNumber as BOOL, YES if at least 80% of the video was watched
  • playTime: NSNumber of duration a video watched
  • didDownload: NSNumber as BOOL, YES if user tapped Download button
  • videoLength: (deprecated in Vungle iOS SDK 4.0.9)

This event can be used to resume animations, sound effects, etc., when returning to the app.

Note that the willPresentProductSheet parameter is always NO. Do not rely on this parameter to determine if the user tapped the download button.

(void)vungleSDKwillCloseProductSheet:(id)productSheet (deprecated) (Deprecated in Vungle iOS SDK 4.0.9.) This callback will NOT be called because the latest Vungle SDK no longer uses Product Sheet. Instead, use the (void)vungleSDKwillCloseAdWithViewInfo: callback to resume your application. 


Registering The VungleSDKDelegate

In order to receive events from the VungleSDK singleton, classes following the VungleSDKDelegate protocol must be registered in the following way:

[[VungleSDK sharedSDK] setDelegate:yourDelegateInstance];

To avoid memory leaks, remember to clear the registered delegate when it's no longer needed. The VungleSDK singleton will retain the registered delegate until it has been explicitly removed.

To clear a delegate, use the following:

[[VungleSDK sharedSDK] setDelegate:nil];

 

VungleSDKLogger Protocol


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

The VungleSDK singleton will send logging events to any attached class following the VungleSDKLogger protocol.  The log event will contain the NSString value that will also be 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 VungleSDK. 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
Have more questions? Submit a request

Comments