Skip to main content

Native Carousel Ad

Native Carousel ads are supported starting from GFPSDK version 7.6.0.
This format is supported as a Native Normal type. Except for the special notes below, it is applied in the same way as a Native Normal (NN) type ad.
For the Native Normal integration guide, please refer to the link.

Carousel image

Applying Preferred Height​

Due to the nature of carousel ads, each slot is rendered based on the Height of the MediaView (in landscape mode) or the Width (in portrait mode).
To ensure the loaded ad renders at the appropriate height, the most suitable MediaView height is provided in MediaData at the time the ad loads.

func adLoader(_ unifiedAdLoader: GFPAdLoader, didReceiveNativeAd nativeAd: GFPNativeAd) {
    ...
    if nativeAd.mediaData.preferredMediaHeight > 0 {
        self.nativeAdView.frame = CGRect(x: self.nativeAdView.frame.origin.x,
                                         y: self.nativeAdView.frame.origin.y,
                                         width: self.nativeAdView.frame.size.width,
                                         height: nativeAd.mediaData.preferredMediaHeight)
    }
    ...
    self.nativeAdView.nativeAd = nativeAd
    ...
}

It is recommended to adjust the MediaView height before setting nativeAd on the NativeAdView.
However, even if you do not set the exact height, the MediaView will automatically adjust to fit the height that has been set.

Applying Preferred Width​

When a carousel ad uses a specific layout format (e.g., 2x2 or 1x3 ads), the ideal width is provided in addition to the ideal height. For standard carousel products, Preferred Width is provided as -1. When both Preferred Height and Preferred Width are positive values, the MediaView size is adjusted to those values.

If you want to set a width different from the provided value, use the preferredHeightWithFixedWidth: method of MediaData to receive and use the corresponding height value.

info

This property is available from GFPSDK version 7.9.0 and later.

func adLoader(_ unifiedAdLoader: GFPAdLoader, didReceiveNativeAd nativeAd: GFPNativeAd) {
    ...
    if nativeAd.mediaData.preferredMediaHeight > 0 {
        self.nativeAdView.frame = CGRect(x: self.nativeAdView.frame.origin.x,
                                         y: self.nativeAdView.frame.origin.y,
                                         width: self.nativeAdView.frame.size.width,
                                         height: nativeAd.mediaData.preferredMediaHeight)
    }

    if nativeAd.mediaData.preferredMediaWidth > 0 {
        self.nativeAdView.frame = CGRect(x: self.nativeAdView.frame.origin.x,
                                         y: self.nativeAdView.frame.origin.y,
                                         width: nativeAd.mediaData.preferredMediaWidth, 
                                         height: self.nativeAdView.frame.size.height)
    }
    ...
    //If you want to use a fixed width different from the provided value
    if nativeAd.mediaData.preferredMediaHeight > 0 && nativeAd.mediaData.preferredMediaWidth > 0 {
        let fixedSize = self.nativeAdView.mediaView.frame.size.width;
        self.nativeAdView.frame = CGRect(x: self.nativeAdView.frame.origin.x,
                                         y: self.nativeAdView.frame.origin.y,
                                         width: fixedSize, 
                                         height: nativeAd.mediaData.preferredHeightWithFixedWidth(fixedSize))
        
    }

    ...
    self.nativeAdView.nativeAd = nativeAd
    ...
}

Applying Collection View Insets​

Carousel ads use a UICollectionView internally.
If you need to add padding depending on how the service places the MediaView, use the following option.

Controlled via the richMediaInsets value of GFPNativeAdRenderingSetting. The default value is UIEdgeInsetsZero.

info

Carousel ads use GFPNativeAdRenderingSetting. For other available options besides richMediaInsets, refer to Native Rendering Options.

Reference image

self.adLoader = GFPAdLoader(unitID: self.unitId, 
                            rootViewController: self.rvc, 
                            adParam: self.nativeInfo.param)

let nativeOptions = GFPAdNativeOptions()
nativeOptions.renderingSetting = GFPNativeAdRenderingSetting()
nativeOptions.renderingSetting.richMediaInsets = UIEdgeInsets(top: 0, left: 16, bottom: 16, right: 16)
self.adLoader.setNativeDelegate(self, nativeOptions: nativeOptions)

Slot Placeholder Configuration​

For carousel ads, publishers can configure placeholder and load-failure images separately. Use the following properties of GFPNativeAdRenderingSetting to specify the loading color and image.

PropertyDescription
slotLoadingColorBackground color to display while a slot is loading (light mode)
slotLoadingDarkColorBackground color to display while a slot is loading (dark mode)
slotPlaceHolderImageImage to display when a slot fails to load (light mode)
slotPlaceHolderDarkImageImage to display when a slot fails to load (dark mode)
let renderingSetting = GFPNativeAdRenderingSetting()
renderingSetting.slotLoadingColor     = UIColor(white: 0.9, alpha: 1.0)
renderingSetting.slotLoadingDarkColor = UIColor(white: 0.2, alpha: 1.0)
renderingSetting.slotPlaceHolderImage     = UIImage(named: "placeholder")
renderingSetting.slotPlaceHolderDarkImage = UIImage(named: "placeholder_dark")

let nativeOptions = GFPAdNativeOptions()
nativeOptions.renderingSetting = renderingSetting
self.adLoader.setNativeDelegate(self, nativeOptions: nativeOptions)