Advanced Settings for Vungle SDK v.6 on iOS

Apple has published details on their privacy requirements for the App Store. According to Apple’s announcement, app developers must define which data are collected by their apps and any SDKs they have integrated.

To help you answer this questionnaire with respect to your integration of the Vungle SDK, refer to the following table, which maps Vungle's data collection and use to the data types that Apple asks about in its questionnaire.

A couple of disclaimers:

• This list is only applicable to Apple privacy questionnaire, and it does not address data or privacy questions that may be raised by other parties. Please always refer to our Privacy Policy for more detailed information.
• This list only describes Vungle's SDK and data collection. This list does not describe a developer’s overall app data collection and use, or that of any other SDK.

As of May 25, 2019, 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 sample code below 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 Vungle SDK v6.3.2 and higher:

// 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];

//This function returns the current consent status recorded in SDK. If status is not known return 0.

sdk = VungleSDK.shared()
sdk?.getCurrentConsentStatus()

//This function sets the current consent status recorded in the SDK
sdk = VungleSDK.shared()
sdk?.update(status: VungleConsentStatus)

VungleConsentStatus is an enum with 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. getConsentStatus may return null until updateConsentStatus has been called or users make their consent using Vungle consent dialog. Note that this prompt only occurs on IP addresses originating from Europe.

Because Vungle SDK v6.2.0 cannot pass the consent message version, use the following APIs:

// This function sets the consent status that will be recorded in the 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];

As of July 1, 2020, California Consumer Privacy Act (CCPA) will be enforced and publishers must updated to iOS SDK 6.7.0 to comply with CCPA. In accordance with CCPA, the consent status is opted in by default unless updateCCPAStatus has been explicitly called to set it as opted out. getCCPAStatus may return null if CCPA is not set, but will be treated as opted-in. 

Generally speaking, the Children’s Online Privacy Protection Act (COPPA) regulates the collection, use, and disclosure of personal information for children under the age of 13 by certain websites and online services (including mobile apps). Compliance with COPPA is a legal issue and we suggest you seek the advice of an attorney in determining compliance. Additionally, for more information on COPPA, please refer to the Federal Trade Commission's COPPA FAQ.

Vungle has tools to assist publishers with COPPA compliance. In addition to use of settings on the Monetize Dashboard, Vungle offers features within the Vungle SDK using the COPPA API. This is available for early access with iOS SDK v.6.11.0.

COPPA Compliance at the App Level

Vungle provides tooling in the Monetize Dashboard to indicate COPPA compliance for each app. When defining your app in the Monetize Dashboard, you must indicate to Vungle whether your app is directed toward children under age 13. Depending on your setting, Vungle will globally treat all traffic for the app as subject to COPPA or not. If you indicate that your app is not directed toward children under 13, COPPA settings will not apply at the app level, and can then be indicated at a more granular level (see COPPA Compliance at the Device Level).

COPPA Compliance at the Device Level

Starting with SDK v.6.11 early access, Vungle provides an optional method for you to indicate at the device level whether the user within the given mobile app is under or over the age of 13 by using the SDK COPPA API. The SDK COPPA API is most appropriate in cases of apps that legally can implement an age screen or age gate in accordance with COPPA, rather than treating all users as under 13. If you believe your app as a whole is primarily directed to children under the age of 13 as set forth in COPPA and related guidance, the COPPA Dashboard settings are more appropriate for you.

Recommendations for Using Vungle's COPPA Compliance Tools

Pursuant to the Vungle SDK License and Publisher Terms, it is the publisher’s responsibility to ensure compliance with applicable laws, including COPPA. Vungle is not liable for COPPA violations resulting from incorrect settings communicated via the SDK COPPA API. Consider the following recommendations to help you ensure COPPA compliance.

• Use the SDK COPPA API for mixed-audience apps. Use the SDK COPPA API if:
  • You have confirmed you are a “mixed-audience app” under COPPA
  • You have implemented an age gate or age screen
  • You have stated that for your app “COPPA settings will NOT apply” in the Publisher Dashboard (otherwise, a COPPA-compliant setting in your Dashboard will override any API settings to the contrary)
• Use the Dashboard for apps directed towards children under 13: In cases where it is clear that your app is primarily directed to children under the age of 13, use the COPPA settings section in the Publisher Dashboard instead of the SDK COPPA API.
• Conflicting settings between API and Dashboard: As noted above, you can establish COPPA settings at the app level (but not at the user level) on the Publisher Dashboard, and at the device/user level by using the SDK COPPA API. Under the current release of SDK COPPA API functionality, in the event of a conflict between the settings in Publisher Dashboard and those passed via the SDK COPPA API, the COPPA-compliant setting takes precedence.
  
  For example, if your app setting on the Publisher Dashboard is COPPA-compliant, and that same app also enables use of the SDK COPPA API and identifies a given user as over 13, Vungle will defer to the Dashboard setting, which states that all the users in this app are protected by COPPA regulations. If, on the other hand, your app setting on the Publisher Dashboard states that your app is not directed toward users under the age of 13, but a call to the SDK COPPA API identifies a given user as under age 13, Vungle will override the dashboard setting and treat that user as being protected by COPPA regulations.

COPPA API

The SDK COPPA API must be called before calling the init method. To update Vungle about a user’s COPPA status:

/**
* This method can be used to provide a user's COPPA status to the Vungle SDK.
* This method should be called before initialization.
* @param status the bool flag to be set for the user's COPPA status.
* status: YES if the user should be treated as 'under 13' and under COPPA regulations.
* status: NO if the user is known to be over the age of 13 and does NOT fall under COPPA regulations.
*/
- (void)updateCOPPAStatus:(BOOL)status;

1. Use [[VungleSDK sharedSDK] updateCOPPAStatus:BOOL] where BOOL is set to `YES` for a user who is under the age of 13 and falls under COPPA regulations; `NO` for a user known to be over the age of 13.
2. Then call [[VungleSDK sharedSDK] startWithAppID: options: error:], as shown.

Usage example:

// To treat the user as under age 13
// and under COPPA regulations:
[[VungleSDK sharedSDK] updateCOPPAStatus:YES];

//OR

// If user is known to be over age 13 and 
// does NOT fall under COPPA regulations:
[[VungleSDK sharedSDK] updateCOPPAStatus:NO];


// Initialize SDK after setting COPPA Status
NSError *error = nil; // pass into init to receive error message if one is triggered
[[VungleSDK sharedSDK] startWithAppID:@”Some App ID” options:[NSDictionary of SDK options] error:&error];

Starting with Vungle SDK v6.4.3, you can prevent passing the IDFV from the device to the SDK.

Sample code:

[VungleSDK setPublishIDFV:NO];
if (![sdk startWithAppId:appID error:&error]) {
    if (error) {
        NSLog(@"Error encountered starting the VungleSDK: %@", error);
    }
}

You can receive callbacks from the SDK with VungleSDKDelegate. The callback methods in the delegate notify the app about SDK events.

You can attach and detach your delegate with the following:

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

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

var sdk:VungleSDK = VungleSDK.shared()
// Attach
sdk.delegate = <yourDelegateInstance> as VungleSDKDelegate

// Detach
sdk.delegate = nil

Note: To avoid memory leaks, remember to clear the registered delegate when it's no longer needed.

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

- (void)vungleSDKDidInitialize;

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 has just begun to play a video ad:

- (void)vungleDidShowAdForPlacementID:(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)vungleWillCloseAdForPlacementID:(nonnull NSString *)placementID;

//Deprecated as of v6.7.0
- (void)vungleWillCloseAdWithViewInfo:(VungleViewInfo *)info placementID:(NSString *)placementID;

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

- (void)vungleDidCloseAdForPlacementID:(nonnull NSString *)placementID;

//Deprecated as of v6.7.0
- (void)vungleDidCloseAdWithViewInfo:(nonnull VungleViewInfo *)info placementID:(nonnull NSString *)placementID

The following method is called when the SDK has changed ad availability status. The isAdPlayable Boolean denotes the new playability of a specific placementID. (Refer to the Check Ad Availability for a Placement section.)

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

The following method is called when the user clicks the Vungle ad. At this point, it is recommended to track click event.

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

The following method is called when the user taps the Vungle ad which will cause them to leave the current application (e.g the ad action opens the iTunes store, Mobile Safari, etc).

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

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

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

- (void)vungleAdViewedForPlacement:(NSString *)placementID;

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

/**
Deprecated as of 6.7.0
**/
@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

Starting with Vungle SDK v6.4.3, 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:

Sample code:

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

Use this property to get SDK information:

- (NSDictionary *)debugInfo;

Use the following method for the SDK to output logs:

- (void)setLoggingEnabled:(BOOL)enable;

@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];

VungleSDK.shared().attach(logger: yourLoggerInstance);

As we stated above, it's important to clear out attached loggers from the Vungle SDK. To detach your logger, use the following:

[[VungleSDK sharedSDK] detachLogger:yourLoggerInstance];

VungleSDK.shared().detach(logger: yourLoggerInstance);

Some of the resources allocated to the Vungle SDK can be terminated by the OS if system resources are running low or if too much context switching is occurring. To ensure smooth operation of SDK, we recommend checking the SDK initialization state before invoking the SDK API. Invoke isInitialized before calling any SDK API and reinitialize the SDK if isInitialized returns NO.

if (![[VungleSDK sharedSDK] isInitialized]) {
    if (![VungleSDK startWithAppID:appID options:options error:&error]) {
        return;
    }
}

Starting with Vungle SDK v6.9.1, any current downloads and download operations can be done when the app is in the background. When the app returns to the foreground, the ad assets should be downloaded. 

Starting with Vungle SDK 6.9.2, to disable background downloading please add the following line of code before initializing the SDK. Set the value to NO for enableBackgroundDownload: otherwise it will be enabled by default. We recommend leaving it enabled by default. Please note: only for 6.9.1, the default value for background downloading will disabled by default.

Sample code:

[VungleSDK enableBackgroundDownload:NO];

To check the value of enableBackgroundDownload after initialization, use backgroundDownloadEnabled(). Returns YES is background downloading is enabled, otherwise NO.

[VungleSDK backgroundDownloadEnabled];

Optional: If ads need to be downloaded in the background when the application is in the suspended application lifecycle state, implement the following delegate method  application:handleEventsForBackgroundURLSession:completeHandler:. 

Sample code:

In AppDelegate.m, add the following method with this implementation.

- (void)application:(UIApplication *)application handleEventsForBackgroundURLSession:(NSString *)identifier completionHandler:(void (^)(void))completionHandler { 
    [VungleSDK sharedSDK].backgroundURLSessionCompletionHandler = completionHandler;
}

If implemented, this will get called when the SDK has an ad ready to be displayed. The parameters will indicate that an ad associated with the included creative ID is ready to play for the specified placement reference ID. Both parameters should return a value if an ad is ready to be played.

Sample code:

In the class header file, be sure to import the VungleSDKCreativeTracking.h file in the class header file.

#import <VungleSDK/VungleSDKCreativeTracking.h>

Implement creativeTrackingDelegate by calling the method setCreativeTrackingDelegate before initializing the Vungle SDK.

[[VungleSDK sharedSDK] setCreativeTrackingDelegate:self];

Implement the following delegate method inside the class. 

-(void)vungleCreative:(NSString *)creativeID readyForPlacement:(NSString *)placementID;