Docs(prebid-mobile): clarify creative size resolution for iOS and Android

prebid-mobile/pbm-api/android/pbm-util-android.md

@@ -18,7 +18,7 @@ This page will store any utilities that can used in conjuntion with the Prebid S
 ## Find Prebid Creative Size
 Prebid SDK provides a function `findPrebidCreativeSize` to address a bug in the Google Ad Manager ad server (described in [this Google forum thread](https://groups.google.com/forum/?utm_medium=email&utm_source=footer#!category-topic/google-admob-ads-sdk/ios/648jzAP2EQY)) where under certain situations ads fail to render.
 
-It is recommended all Google Ad Manager integrations resize all ads served based on the winning Prebid creative size `findPrebidCreativeSize`. Functionally speaking the Prebid SDK resizes ad slots based on the [onAdLoaded](https://developers.google.com/android/reference/com/google/android/gms/ads/AdListener.html#onAdLoaded()) (when an ad is received) to determine the winning Prehbid ad size to determine how to resize the ad slot.
+For GAM banner integrations, call `findPrebidCreativeSize` from [`onAdLoaded`](https://developers.google.com/android/reference/com/google/android/gms/ads/AdListener.html#onAdLoaded()) after each successful banner load. The utility searches the creative’s HTML for Prebid size information. If found, use the success callback to resize the ad view accordingly. Size resolution may fail when GAM serves a non-Prebid creative or when the required size information cannot be extracted from a Prebid creative. The failure callback does not distinguish between these cases; leave the ad view’s current size unchanged.
 
 {% include alerts/alert_note.html content="`findPrebidCreativeSize` is supported on Android API versions 19+. Using on earlier versions is safe to use, however the resizing would not function." %}
 
@@ -29,15 +29,17 @@ adView.adListener = object : AdListener() {
     override fun onAdLoaded() {
         super.onAdLoaded()
 
-        // Determine the kind of winning line item
         AdViewUtils.findPrebidCreativeSize(adView, object : AdViewUtils.PbFindSizeListener {
             override fun success(width: Int, height: Int) {
 
-                // In the case of Prebid's line item - resize te ad view
+                // Resize the ad view using the resolved Prebid creative size.
                 adView.setAdSizes(AdSize(width, height))
             }
 
-            override fun failure(error: PbFindSizeError) {}
+            override fun failure(error: PbFindSizeError) {
+                // Size resolution may fail for a non-Prebid creative served by GAM,
+                // or when size information cannot be extracted from a Prebid creative.
+            }
         })
     }
 }

prebid-mobile/pbm-api/ios/pbm-util-ios.md

@@ -1,6 +1,6 @@
 ---
 layout: page_v2
-title: Prebid SDK Utilities - Android
+title: Prebid SDK Utilities - iOS
 description: Utilities used in conjuntion with the Prebid SDK
 top_nav_section: prebid-mobile
 nav_section: prebid-mobile
@@ -19,7 +19,7 @@ This page will store any utilities that can used in conjuntion with the Prebid S
 
 Prebid SDK provides a function `findPrebidCreativeSize` to address a bug in the Google Ad Manager ad server (described in [this Google forum thread](https://groups.google.com/forum/?utm_medium=email&utm_source=footer#!category-topic/google-admob-ads-sdk/ios/648jzAP2EQY)) where under certain situations ads fail to render.
 
-It is recommended all Google Ad Manager integrations resize all ads served based on the winning Prebid creative size `findPrebidCreativeSize`. Functionally speaking the Prebid SDK resizes ad slots based on the [adViewDidReceiveAd event](https://developers.google.com/admob/ios/banner) (when an ad is received) to determine the winning Prehbid ad size to determine how to resize the ad slot.
+For GAM banner integrations, call `findPrebidCreativeSize` from [`bannerViewDidReceiveAd`](https://developers.google.com/ad-manager/mobile-ads-sdk/ios/banner) after each successful banner load. The utility searches the creative’s HTML for Prebid size information. If found, use the success callback to resize the ad view accordingly. Size resolution may fail when GAM serves a non-Prebid creative or when the required size information cannot be extracted from a Prebid creative. The failure callback does not distinguish between these cases; leave the ad view’s current size unchanged.
 
 Usage example:
 
@@ -28,23 +28,24 @@ func bannerViewDidReceiveAd(_ bannerView: GoogleMobileAds.BannerView) {
     AdViewUtils.findPrebidCreativeSize(bannerView, success: { size in
         guard let bannerView = bannerView as? AdManagerBannerView else { return }
 
-        // In the case of Prebid's line item - resize te ad view
+        // Resize the ad view using the resolved Prebid creative size.
         bannerView.resize(adSizeFor(cgSize: size))
-    }, failure: { (error) in
-        PrebidDemoLogger.shared.error("Error occurring during searching for Prebid creative size: \(error)")
+    }, failure: { error in
+        // Size resolution may fail for a non-Prebid creative served by GAM,
+        // or when size information cannot be extracted from a Prebid creative.
     })
 }
 {% endcapture %}
 {% capture gma11 %}func bannerViewDidReceiveAd(_ bannerView: GADBannerView) {
 
-    // Determine the kind of winning line item
     AdViewUtils.findPrebidCreativeSize(bannerView, success: { size in
         guard let bannerView = bannerView as? GAMBannerView else { return }
 
-        // In the case of Prebid's line item - resize te ad view
+        // Resize the ad view using the resolved Prebid creative size.
         bannerView.resize(GADAdSizeFromCGSize(size))
-    }, failure: { (error) in
-        PrebidDemoLogger.shared.error("Error occurring during searching for Prebid creative size: \(error)")
+    }, failure: { error in
+        // Size resolution may fail for a non-Prebid creative served by GAM,
+        // or when size information cannot be extracted from a Prebid creative.
     })
 }
 {% endcapture %}

prebid-mobile/recipes/subrecipes/android/gam-bidding-only-html-banner.md

@@ -69,10 +69,14 @@ private fun createGAMListener(adView: AdManagerAdView): AdListener {
             // 6. Resize ad view if needed
             AdViewUtils.findPrebidCreativeSize(adView, object : AdViewUtils.PbFindSizeListener {
                 override fun success(width: Int, height: Int) {
+                    // Resize the ad view using the resolved Prebid creative size.
                     adView.setAdSizes(AdSize(width, height))
                 }
 
-                override fun failure(error: PbFindSizeError) {}
+                override fun failure(error: PbFindSizeError) {
+                    // Size resolution may fail for a non-Prebid creative served by GAM,
+                    // or when size information cannot be extracted from a Prebid creative.
+                }
             })
         }
     }
@@ -82,7 +86,7 @@ private fun createGAMListener(adView: AdManagerAdView): AdListener {
 Notes:
 
 1. in case you use a single-size banner (as opposed to multi-size), i.e. 300x250 - you don’t need to make a call to the AdViewUtils.findPrebidCreativeSize routine - because you already know the size of the creative (it is 300x250), however you still need to make a call to bannerView.resize because the creative has the 1x1 size by default and without this call it will be rendered, but as a pixel.
-2. Make sure you properly process all possible cases in the  AdViewUtils.findPrebidCreativeSize callbacks (both success and failure).  Sometimes you might not get the size of the creative (or a failure callback) - it simply means that this is not a Prebid creative.  It means that you still need to render the creative, but you most likely don’t need to resize it - at least Prebid knows nothing about it.
+2. Size resolution may fail when GAM serves a non-Prebid creative or when the required size information cannot be extracted from a Prebid creative. The failure callback does not distinguish between these cases; leave the ad view’s current size unchanged.
 
 ## Step 1: Create a BannerAdUnit
 {:.no_toc}
@@ -118,12 +122,12 @@ Be sure that you make the ad request with the same `AdManagerAdRequest` object t
 ## Step 6: Adjust the ad view size
 {:.no_toc}
 
-Once an app receives a signal that an ad is loaded, you should use the method `AdViewUtils.findPrebidCreativeSize` to verify whether it's Prebid's ad and resize the ad slot respectively to the creative's properties.
+After the banner loads, use `AdViewUtils.findPrebidCreativeSize` to look for Prebid size information in the creative’s HTML. If a size is found, resize the ad view in the success callback.
 
 Notes:
 
 1. In case you use a single-size banner (as opposed to multi-size), f.e. 300x250 - you don’t need to make a call to the AdViewUtils.findPrebidCreativeSize routine - because you already know the size of the creative (it is 300x250), however you still need to make a call to bannerView.resize(<size>) because the creative has the 1x1 size by default and without this call it will be rendered, but as a pixel. 
-2. Make sure you properly process all possible cases in the  AdViewUtils.findPrebidCreativeSize callbacks (both success and failure).  Sometimes you might not get the size of the creative (or a failure callback) - it simply means that this is not a Prebid creative.  It means that you still need to render the creative, but you most likely don’t need to resize it - at least Prebid knows nothing about it.
+2. Size resolution may fail when GAM serves a non-Prebid creative or when the required size information cannot be extracted from a Prebid creative. The failure callback does not distinguish between these cases; leave the ad view’s current size unchanged.
 
 ## Further Reading
 

prebid-mobile/recipes/subrecipes/android/nextgen-bidding-only-html-banner.md

@@ -56,10 +56,14 @@ private fun createAdLoadCallback(adView: AdView): AdLoadCallback<BannerAd> {
             // 7. Resize ad view if needed
             AdViewUtils.findPrebidCreativeSize(adView, object : AdViewUtils.PbFindSizeListener {
                 override fun success(width: Int, height: Int) {
+                    // Resize the ad view using the resolved Prebid creative size.
                     adView.resize(AdSize(width, height))
                 }
 
-                override fun failure(error: PbFindSizeError) {}
+                override fun failure(error: PbFindSizeError) {
+                    // Size resolution may fail for a non-Prebid creative served by GAM,
+                    // or when size information cannot be extracted from a Prebid creative.
+                }
             })
 
             ad.adEventCallback = object : BannerAdEventCallback {
@@ -83,7 +87,7 @@ private fun createAdLoadCallback(adView: AdView): AdLoadCallback<BannerAd> {
 Notes:
 
 1. In case you use a single-size banner (as opposed to multi-size), i.e. 300x250 - you don't need to call `AdViewUtils.findPrebidCreativeSize` because you already know the size of the creative. However you still need to call `adView.resize()` because the creative has a 1x1 size by default and without this call it will be rendered as a pixel.
-2. Make sure you properly process all possible cases in the `AdViewUtils.findPrebidCreativeSize` callbacks (both success and failure). Sometimes you might not get the size of the creative (or a failure callback) - it simply means that this is not a Prebid creative. It means that you still need to render the creative, but you most likely don't need to resize it.
+2. Size resolution may fail when GAM serves a non-Prebid creative or when the required size information cannot be extracted from a Prebid creative. The failure callback does not distinguish between these cases; leave the ad view’s current size unchanged.
 
 ## Step 1: Create a BannerAdUnit
 {:.no_toc}
@@ -124,12 +128,12 @@ Be sure that you make the ad request with the same `BannerAdRequest.Builder` obj
 ## Step 7: Adjust the ad view size
 {:.no_toc}
 
-Once an app receives a signal that an ad is loaded, you should use the method `AdViewUtils.findPrebidCreativeSize` to verify whether it's Prebid's ad and resize the ad slot respectively to the creative's properties.
+After the banner loads, use `AdViewUtils.findPrebidCreativeSize` to look for Prebid size information in the creative’s HTML. If a size is found, resize the ad view in the success callback.
 
 Notes:
 
 1. In case you use a single-size banner (as opposed to multi-size), e.g. 300x250 - you don't need to call `AdViewUtils.findPrebidCreativeSize` because you already know the size of the creative. However you still need to call `adView.resize()` because the creative has a 1x1 size by default and without this call it will be rendered as a pixel.
-2. Make sure you properly process all possible cases in the `AdViewUtils.findPrebidCreativeSize` callbacks (both success and failure). Sometimes you might not get the size of the creative (or a failure callback) - it simply means that this is not a Prebid creative. It means that you still need to render the creative, but you most likely don't need to resize it.
+2. Size resolution may fail when GAM serves a non-Prebid creative or when the required size information cannot be extracted from a Prebid creative. The failure callback does not distinguish between these cases; leave the ad view’s current size unchanged.
 
 ## Further Reading
 

prebid-mobile/recipes/subrecipes/ios/gam-bidding-only-html-banner.md

@@ -83,27 +83,31 @@ In case you use a single-size banner (e.g., 300x250), you don't need to make a c
 {% capture gma12 %}func bannerViewDidReceiveAd(_ bannerView: GoogleMobileAds.BannerView) {
     AdViewUtils.findPrebidCreativeSize(bannerView, success: { size in
         guard let bannerView = bannerView as? AdManagerBannerView else { return }
+        // Resize the ad view using the resolved Prebid creative size.
         bannerView.resize(adSizeFor(cgSize: size))
-    }, failure: { (error) in
-        PrebidDemoLogger.shared.error("Error occurring during searching for Prebid creative size: \(error)")
+    }, failure: { error in
+        // Size resolution may fail for a non-Prebid creative served by GAM,
+        // or when size information cannot be extracted from a Prebid creative.
     })
 }
 {% endcapture %}
 {% capture gma11 %}func bannerViewDidReceiveAd(_ bannerView: GADBannerView) {
     // 6. Resize ad view if needed (Prebid Mobile SDK)
     AdViewUtils.findPrebidCreativeSize(bannerView, success: { size in
         guard let bannerView = bannerView as? GAMBannerView else { return }
+        // Resize the ad view using the resolved Prebid creative size.
         bannerView.resize(GADAdSizeFromCGSize(size))
-    }, failure: { (error) in
-        // The received ad is not Prebid’s one 
+    }, failure: { error in
+        // Size resolution may fail for a non-Prebid creative served by GAM,
+        // or when size information cannot be extracted from a Prebid creative.
     })
 }
 {% endcapture %}
 
 {% include code/gma-versions-tabs.html id="html-banner-did-receive-ad-callback" gma11=gma11 gma12=gma12 %}
 
 {: .alert.alert-info :}
-Make sure you process all possible cases in the  `AdViewUtils.findPrebidCreativeSize` callbacks (both success and failure).  Sometimes you might not get the size of the creative (or a failure callback) - it simply means that this is not a Prebid creative.  It means that you still need to render the creative, but you most likely don’t need to resize it.
+Size resolution may fail when GAM serves a non-Prebid creative or when the required size information cannot be extracted from a Prebid creative. The failure callback does not distinguish between these cases; leave the ad view’s current size unchanged.
 
 ## Step 1: Create a `BannerAdUnit`
 
@@ -136,7 +140,7 @@ Ensure that you call the _load_ method with the same `AdManagerRequest` object t
 
 ## Step 6: Adjust the ad view size
 
-Once an app receives a signal that an ad is loaded, you should use the method `AdViewUtils.findPrebidCreativeSize` to verify whether it's Prebid Server’s ad and resize the ad slot respectively to the creative's properties. 
+After the banner loads, use `AdViewUtils.findPrebidCreativeSize` to look for Prebid size information in the creative’s HTML. If a size is found, resize the ad view in the success callback.
 
 ## Further Reading
 

prebid-mobile/recipes/subrecipes/ios/gam-bidding-only-multiformat.md

@@ -113,12 +113,14 @@ To handle the banner, video and in-banner native (Native Styles) ads:
     self.bannerView.addSubview(bannerView)
 
     AdViewUtils.findPrebidCreativeSize(bannerView, success: { [weak self] size in
+        // Resize the ad view using the resolved Prebid creative size.
         bannerView.resize(adSizeFor(cgSize: size))
 
         self?.bannerView.constraints.first { $0.firstAttribute == .width }?.constant = size.width
         self?.bannerView.constraints.first { $0.firstAttribute == .height }?.constant = size.height
-    }, failure: { (error) in
-        PrebidDemoLogger.shared.error("Error occurring during searching for Prebid creative size: \(error)")
+    }, failure: { error in
+        // Size resolution may fail for a non-Prebid creative served by GAM,
+        // or when size information cannot be extracted from a Prebid creative.
     })
 }
 {% endcapture %}
@@ -129,12 +131,14 @@ To handle the banner, video and in-banner native (Native Styles) ads:
     self.bannerView.addSubview(bannerView)
 
     AdViewUtils.findPrebidCreativeSize(bannerView, success: { [weak self] size in
+        // Resize the ad view using the resolved Prebid creative size.
         bannerView.resize(GADAdSizeFromCGSize(size))
 
         self?.bannerView.constraints.first { $0.firstAttribute == .width }?.constant = size.width
         self?.bannerView.constraints.first { $0.firstAttribute == .height }?.constant = size.height
-    }, failure: { (error) in
-        PrebidDemoLogger.shared.error("Error occurring during searching for Prebid creative size: \(error)")
+    }, failure: { error in
+        // Size resolution may fail for a non-Prebid creative served by GAM,
+        // or when size information cannot be extracted from a Prebid creative.
     })
 }
 {% endcapture %}
@@ -235,7 +239,7 @@ Be sure that you make the ad request with the same `AdManagerRequest` object tha
 ## Step 7: Process the Ad Response
 {:.no_toc}
 
-Once an app receives a signal that an ad is loaded, you should use the method `AdViewUtils.findPrebidCreativeSize` to verify whether it is a Prebid ad and resize the ad slot respectively to the creative's properties.
+For banner responses, use `AdViewUtils.findPrebidCreativeSize` to look for Prebid size information in the creative’s HTML. If a size is found, resize the ad view and update its container constraints in the success callback.
 
 ## Further Reading