Picture-in-picture (PiP) ads display in a floating window that stays on top of content on the screen, such as articles, feeds, or gameplay. This format lets users interact with your app while the ad remains visible. To display ads that don't take over the entire screen, choose this format. This guide covers requesting and displaying picture-in-picture ads in your app using Google Mobile Ads SDK. ## Before you begin Before you continue, do the following: - [Set up Google Mobile Ads SDK](https://developers.google.com/ad-manager/mobile-ads-sdk/ios/quick-start.md.txt). - Install Google Mobile Ads SDK version `13.10.0` or later. - [Enable test ads](https://developers.google.com/ad-manager/mobile-ads-sdk/ios/test-ads.md.txt) and use the following test ad unit ID: /21775744923/example/picture-in-picture ## Load an ad To load a [`GADPictureInPictureAd`](https://developers.google.com/ad-manager/mobile-ads-sdk/ios/api/beta/reference/Classes/GADPictureInPictureAd.md.txt) object, create an ad request and call the `load` method: ### Swift ```swift private func loadAdManagerPictureInPictureAd() async { do { // Capture the PictureInPictureAd reference for later use. pipAd = try await PictureInPictureAd.load( with: adUnitID, request: AdManagerRequest()) // Set the delegate to be notified of ad events. pipAd?.delegate = self } catch { print( "Picture-in-Picture ad failed to load: \(error.localizedDescription)") } } ``` Replace adUnitID with your ad unit ID. ### Objective-C ```objective-c - (void)loadAdManagerPictureInPictureAd { GAMRequest *request = [GAMRequest request]; [GADPictureInPictureAd loadWithAdUnitID:kAdUnitID request:request completionHandler:^(GADPictureInPictureAd *_Nullable ad, NSError *_Nullable error) { if (error) { NSLog(@"Picture-in-Picture ad failed to load: %@", error); return; } // Capture the PictureInPictureAd reference for later use. self.pipAd = ad; // Set the delegate to be notified of ad events. self.pipAd.delegate = self; }]; } ``` Replace kAdUnitID with your ad unit ID.
## Show the ad To display the picture-in-picture ad on screen, call the `show` method. The following example displays the ad in the default position and sets the presentation scope to the screen: ### Swift ```swift private func showPictureInPictureAd() { // Use the loaded PictureInPictureAd instance. guard let pipAd else { print("No ad to show.") return } let options = PictureInPictureAdOptions() // Uses the Google Mobile Ads SDK's default screen position. options.position = .default // Binds the ad lifecycle to the host screen. options.presentationScope = .screen pipAd.show(with: options) } ``` ### Objective-C ```objective-c - (void)showPictureInPictureAd { // Use the loaded PictureInPictureAd instance. if (!self.pipAd) { NSLog(@"No ad to show."); return; } GADPictureInPictureAdOptions *options = [[GADPictureInPictureAdOptions alloc] init]; // Uses the Google Mobile Ads SDK's default screen position. options.position = GADPictureInPictureAdPositionDefault; // Binds the ad lifecycle to the host screen. options.presentationScope = GADPictureInPictureAdPresentationScopeScreen; [self.pipAd showWithOptions:options]; } ```
### Set the position By default, Google Mobile Ads SDK displays a picture-in-picture ad in the bottom-right corner of the screen when first shown, or at the last known position if previously shown. To customize where the ad appears, specify a position when showing the ad. The following example sets the position on top of content in the top-left corner of the screen: ### Swift ```swift private func createTopLeftPositionOptions() -> PictureInPictureAdOptions { let options = PictureInPictureAdOptions() // Sets the ad position to the top-left corner of the screen. options.position = .topLeft return options } ``` ### Objective-C ```objective-c - (GADPictureInPictureAdOptions *)createTopLeftPositionOptions { GADPictureInPictureAdOptions *options = [[GADPictureInPictureAdOptions alloc] init]; // Sets the ad position to the top-left corner of the screen. options.position = GADPictureInPictureAdPositionTopLeft; return options; } ```
For all available positions, see [`GADPictureInPictureAdPosition`](https://developers.google.com/ad-manager/mobile-ads-sdk/ios/api/beta/reference/Enums/GADPictureInPictureAdPosition.md.txt). ### Set the presentation scope By default, Google Mobile Ads SDK binds a picture-in-picture ad to the current host screen. Google Mobile Ads SDK dismisses the ad when the host screen's view hierarchy is no longer in memory. To keep the ad visible after the host screen is removed from memory, set the presentation scope to the application: ### Swift ```swift private func createApplicationScopedOptions() -> PictureInPictureAdOptions { let options = PictureInPictureAdOptions() // Keeps the ad visible beyond the host screen's lifecycle. options.presentationScope = .application return options } ``` ### Objective-C ```objective-c - (GADPictureInPictureAdOptions *)createApplicationScopedOptions { GADPictureInPictureAdOptions *options = [[GADPictureInPictureAdOptions alloc] init]; // Keeps the ad visible beyond the host screen's lifecycle. options.presentationScope = GADPictureInPictureAdPresentationScopeApplication; return options; } ```
For more information, see [Keep the ad visible across screens](https://developers.google.com/ad-manager/mobile-ads-sdk/ios/picture-in-picture#keep_visible_across_screens). ## Listen to ad events To handle picture-in-picture ad lifecycle events, register for ad events before displaying your ad. These events report ad interactions, such as clicks and impressions. These events also report picture-in-picture-specific events, such as when the ad shows or hides: ### Swift ```swift func pictureInPictureAdDidShow(_ pictureInPictureAd: PictureInPictureAd) { print("Picture-in-Picture ad shown.") } func pictureInPictureAdDidHide(_ pictureInPictureAd: PictureInPictureAd) { print("Picture-in-Picture ad hidden.") } func pictureInPictureAdDidFailToShow( _ pictureInPictureAd: PictureInPictureAd, error: Error ) { print("Picture-in-Picture ad failed to show: \(error.localizedDescription)") } func pictureInPictureAdDidRecordImpression( _ pictureInPictureAd: PictureInPictureAd ) { print("Picture-in-Picture ad recorded an impression.") } func pictureInPictureAdDidRecordClick( _ pictureInPictureAd: PictureInPictureAd ) { print("Picture-in-Picture ad recorded a click.") } func pictureInPictureAdWillPresentScreen( _ pictureInPictureAd: PictureInPictureAd ) { print("Picture-in-Picture ad will present screen.") } func pictureInPictureAdWillDismissScreen( _ pictureInPictureAd: PictureInPictureAd ) { print("Picture-in-Picture ad will dismiss screen.") } func pictureInPictureAdDidDismissScreen( _ pictureInPictureAd: PictureInPictureAd ) { print("Picture-in-Picture ad dismissed screen.") } ``` ### Objective-C ```objective-c - (void)pictureInPictureAdDidShow:(GADPictureInPictureAd *)pictureInPictureAd { NSLog(@"Picture-in-Picture ad shown."); } - (void)pictureInPictureAdDidHide:(GADPictureInPictureAd *)pictureInPictureAd { NSLog(@"Picture-in-Picture ad hidden."); } - (void)pictureInPictureAdDidFailToShow:(GADPictureInPictureAd *)pictureInPictureAd withError:(NSError *)error { NSLog(@"Picture-in-Picture ad failed to show: %@", error); } - (void)pictureInPictureAdDidRecordImpression:(GADPictureInPictureAd *)pictureInPictureAd { NSLog(@"Picture-in-Picture ad recorded an impression."); } - (void)pictureInPictureAdDidRecordClick:(GADPictureInPictureAd *)pictureInPictureAd { NSLog(@"Picture-in-Picture ad recorded a click."); } - (void)pictureInPictureAdWillPresentScreen:(GADPictureInPictureAd *)pictureInPictureAd { NSLog(@"Picture-in-Picture ad will present screen."); } - (void)pictureInPictureAdWillDismissScreen:(GADPictureInPictureAd *)pictureInPictureAd { NSLog(@"Picture-in-Picture ad will dismiss screen."); } - (void)pictureInPictureAdDidDismissScreen:(GADPictureInPictureAd *)pictureInPictureAd { NSLog(@"Picture-in-Picture ad dismissed screen."); } ```
## Hide the ad To remove the floating ad from the screen, call the `hide` method. This method invokes the ad hidden event: ### Swift ```swift private func hidePictureInPictureAd() { // Use the loaded PictureInPictureAd instance. guard let pipAd else { print("No ad to hide.") return } pipAd.hide() } ``` ### Objective-C ```objective-c - (void)hidePictureInPictureAd { // Use the loaded PictureInPictureAd instance. if (!self.pipAd) { NSLog(@"No ad to hide."); return; } [self.pipAd hide]; } ```
## Clean up ad resources To avoid memory leaks, drop your reference to the ad object when your app finishes using the ad. For example, when your app no longer displays or interacts with the ad again. For screen-scoped ads, drop the reference when your app removes the host screen from memory. For app-scoped ads, retain the ad reference while the user navigates across screens, and drop the reference when the user dismisses the ad: ### Swift ```swift private func cleanUpPictureInPictureAd() { pipAd?.hide() pipAd = nil } ``` ### Objective-C ```objective-c - (void)cleanUpPictureInPictureAd { [self.pipAd hide]; self.pipAd = nil; } ```
## Keep the ad visible across screens When you set the presentation scope to the application, the picture-in-picture ad remains visible even when your app removes the hosting screen from memory. To interact with or dismiss the ad when the user navigates away from the host screen, your app must retain access to the picture-in-picture ad. We recommend holding the ad in an app-level singleton or shared state manager rather than in a single screen's instance variable. For examples on how to keep an ad visible across screens, see the following sample apps: - [Swift](https://github.com/googleads/googleads-mobile-ios-examples/tree/main/Swift/advanced/APIDemo/APIDemo/PictureInPicture/PictureInPictureAdManager.swift) - [Objective-C](https://github.com/googleads/googleads-mobile-ios-examples/tree/main/Objective-C/advanced/APIDemo/APIDemo/PictureInPicture/PictureInPictureAdManager.m)