// // MPInterstitialAdController.h // // Copyright 2018 Twitter, Inc. // Licensed under the MoPub SDK License Agreement // http://www.mopub.com/legal/sdk-license-agreement/ // #import #import @protocol MPInterstitialAdControllerDelegate; /** * The `MPInterstitialAdController` class provides a full-screen advertisement that can be * displayed during natural transition points in your application. */ @interface MPInterstitialAdController : NSObject /** @name Obtaining an Interstitial Ad */ /** * Returns an interstitial ad object matching the given ad unit ID. * * The first time this method is called for a given ad unit ID, a new interstitial ad object is * created, stored in a shared pool, and returned. Subsequent calls for the same ad unit ID will * return that object, unless you have disposed of the object using * `removeSharedInterstitialAdController:`. * * There can only be one interstitial object for an ad unit ID at a given time. * * @param adUnitId A string representing a MoPub ad unit ID. */ + (MPInterstitialAdController *)interstitialAdControllerForAdUnitId:(NSString *)adUnitId; /** @name Setting and Getting the Delegate */ /** * The delegate (`MPInterstitialAdControllerDelegate`) of the interstitial ad object. */ @property (nonatomic, weak) id delegate; /** @name Setting Request Parameters */ /** * The MoPub ad unit ID for this interstitial ad. * * Ad unit IDs are created on the MoPub website. An ad unit is a defined placement in your * application set aside for advertising. If no ad unit ID is set, the ad object will use a default * ID that only receives test ads. */ @property (nonatomic, copy) NSString *adUnitId; /** * A string representing a set of non-personally identifiable keywords that should be passed to the MoPub ad server to receive * more relevant advertising. * Note: If a user is in General Data Protection Regulation (GDPR) region and MoPub doesn't obtain consent from the user, "keywords" will still be sent to the server. * */ @property (nonatomic, copy) NSString *keywords; /** * A string representing a set of personally identifiable keywords that should be passed to the MoPub ad server to receive * more relevant advertising. * * Keywords are typically used to target ad campaigns at specific user segments. They should be * formatted as comma-separated key-value pairs (e.g. "marital:single,age:24"). * * On the MoPub website, keyword targeting options can be found under the "Advanced Targeting" * section when managing campaigns. * * Note: If a user is in General Data Protection Regulation (GDPR) region and MoPub doesn't obtain consent from the user, personally identifiable keywords will not be sent to the server. */ @property (nonatomic, copy) NSString *userDataKeywords; /** * A `CLLocation` object representing a user's location that should be passed to the MoPub ad server * to receive more relevant advertising. */ @property (nonatomic, copy) CLLocation *location; /** * An optional dictionary containing extra local data. */ @property (nonatomic, copy) NSDictionary *localExtras; /** @name Loading an Interstitial Ad */ /** * Begins loading ad content for the interstitial. * * You can implement the `interstitialDidLoadAd:` and `interstitialDidFailToLoadAd:` methods of * `MPInterstitialAdControllerDelegate` if you would like to be notified as loading succeeds or * fails. */ - (void)loadAd; /** @name Detecting Whether the Interstitial Ad Has Loaded */ /** * A Boolean value that represents whether the interstitial ad has loaded an advertisement and is * ready to be presented. * * After obtaining an interstitial ad object, you can use `loadAd` to tell the object to begin * loading ad content. Once the content has been loaded, the value of this property will be YES. * * The value of this property can be NO if the ad content has not finished loading, has already * been presented, or has expired. The expiration condition only applies for ads from certain * third-party ad networks. See `MPInterstitialAdControllerDelegate` for more details. */ @property (nonatomic, assign, readonly) BOOL ready; /** @name Presenting an Interstitial Ad */ /** * Presents the interstitial ad modally from the specified view controller. * * This method will do nothing if the interstitial ad has not been loaded (i.e. the value of its * `ready` property is NO). * * `MPInterstitialAdControllerDelegate` provides optional methods that you may implement to stay * informed about when an interstitial takes over or relinquishes the screen. * * @param controller The view controller that should be used to present the interstitial ad. */ - (void)showFromViewController:(UIViewController *)controller; /** @name Disposing of an Interstitial Ad */ /** * Removes the given interstitial object from the shared pool of interstitials available to your * application. * * This method removes the mapping from the interstitial's ad unit ID to the interstitial ad * object. In other words, you will receive a different ad object if you subsequently call * `interstitialAdControllerForAdUnitId:` for the same ad unit ID. * * @warning **Important**: This method is intended to be used for deallocating the interstitial * ad object when it is no longer needed. You should `nil` out any references you have to the * object after calling this method. * * @param controller The interstitial ad object that should be disposed. */ + (void)removeSharedInterstitialAdController:(MPInterstitialAdController *)controller; /* * Returns the shared pool of interstitial objects for your application. */ + (NSMutableArray *)sharedInterstitialAdControllers DEPRECATED_MSG_ATTRIBUTE("This functionality will be removed in a future SDK release."); @end #pragma mark - /** * The delegate of an `MPInterstitialAdController` object must adopt the * `MPInterstitialAdControllerDelegate` protocol. * * The optional methods of this protocol allow the delegate to be notified of interstitial state * changes, such as when an ad has loaded, when an ad has been presented or dismissed from the * screen, and when an ad has expired. */ @protocol MPInterstitialAdControllerDelegate @optional /** @name Detecting When an Interstitial Ad is Loaded */ /** * Sent when an interstitial ad object successfully loads an ad. * * @param interstitial The interstitial ad object sending the message. */ - (void)interstitialDidLoadAd:(MPInterstitialAdController *)interstitial; /** * Sent when an interstitial ad object fails to load an ad. * * @param interstitial The interstitial ad object sending the message. */ - (void)interstitialDidFailToLoadAd:(MPInterstitialAdController *)interstitial; /** * Sent when an interstitial ad object fails to load an ad. * * @param interstitial The interstitial ad object sending the message. * @param error The error that occurred during the load. */ - (void)interstitialDidFailToLoadAd:(MPInterstitialAdController *)interstitial withError:(NSError *)error; /** @name Detecting When an Interstitial Ad is Presented */ /** * Sent immediately before an interstitial ad object is presented on the screen. * * Your implementation of this method should pause any application activity that requires user * interaction. * * @param interstitial The interstitial ad object sending the message. */ - (void)interstitialWillAppear:(MPInterstitialAdController *)interstitial; /** * Sent after an interstitial ad object has been presented on the screen. * * @param interstitial The interstitial ad object sending the message. */ - (void)interstitialDidAppear:(MPInterstitialAdController *)interstitial; /** @name Detecting When an Interstitial Ad is Dismissed */ /** * Sent immediately before an interstitial ad object will be dismissed from the screen. * * @param interstitial The interstitial ad object sending the message. */ - (void)interstitialWillDisappear:(MPInterstitialAdController *)interstitial; /** * Sent after an interstitial ad object has been dismissed from the screen, returning control * to your application. * * Your implementation of this method should resume any application activity that was paused * prior to the interstitial being presented on-screen. * * @param interstitial The interstitial ad object sending the message. */ - (void)interstitialDidDisappear:(MPInterstitialAdController *)interstitial; /** @name Detecting When an Interstitial Ad Expires */ /** * Sent when a loaded interstitial ad is no longer eligible to be displayed. * * Interstitial ads from certain networks may expire their content at any time, * even if the content is currently on-screen. This method notifies you when the currently- * loaded interstitial has expired and is no longer eligible for display. * * If the ad was on-screen when it expired, you can expect that the ad will already have been * dismissed by the time this message is sent. * * Your implementation may include a call to `loadAd` to fetch a new ad, if desired. * * @param interstitial The interstitial ad object sending the message. */ - (void)interstitialDidExpire:(MPInterstitialAdController *)interstitial; /** * Sent when the user taps the interstitial ad and the ad is about to perform its target action. * * This action may include displaying a modal or leaving your application. Certain ad networks * may not expose a "tapped" callback so you should not rely on this callback to perform * critical tasks. * * @param interstitial The interstitial ad object sending the message. */ - (void)interstitialDidReceiveTapEvent:(MPInterstitialAdController *)interstitial; @end