iOS GAM Bidding-Only Integration - Multiformat Interstitial Banner+Video

Back to Bidding-Only Integration

Integration example:

// 1. Create an InterstitialAdUnit
adUnit = InterstitialAdUnit(configId: CONFIG_ID, minWidthPerc: 60, minHeightPerc: 70)
adUnit.adUnitConfig.adSize = CGSize(width: 1, height: 1)

// 2. Set adFormats
adUnit.adFormats = [.banner, .video]

// 3. Configure parameters
let parameters = VideoParameters(mimes: ["video/mp4"])
parameters.protocols = [Signals.Protocols.VAST_2_0]
parameters.playbackMethod = [Signals.PlaybackMethod.AutoPlaySoundOff]
adUnit.videoParameters = parameters

// 4. Make a bid request to Prebid Server
let gamRequest = GAMRequest()
adUnit.fetchDemand(adObject: gamRequest) { [weak self] resultCode in
    PrebidDemoLogger.shared.info("Prebid demand fetch for GAM \(resultCode.name())")

    // 5. Load a GAM interstitial ad
    GAMInterstitialAd.load(withAdManagerAdUnitID: gamAdUnitMultiformatInterstitialOriginal, request: gamRequest) { ad, error in
        guard let self = self else { return }

        if let error = error {
            PrebidDemoLogger.shared.error("Failed to load interstitial ad with error: \(error.localizedDescription)")
        } else if let ad = ad {
            // 5. Present the interstitial ad
            ad.fullScreenContentDelegate = self
            ad.present(fromRootViewController: self)
        }
    }
}

Step 1: Create an InterstitialAdUnit

Initialize the InterstitialAdUnit with the following properties:

  • configId - an ID of Stored Impression on the Prebid Server
  • minWidthPerc: Optional parameter to specify the minimum width percent an ad may occupy of a device’s real estate. Support in SDK version 1.2+
  • minHeightPrec: Optional parameter to specify the minimum height percent an ad may occupy of a device’s real estate. Support in SDK version 1.2+

Here’s how min size percentages work. If the adunit size is 1x1, Prebid Server takes the screen width/height and the minWidthPerc/minHeightPerc as a size range, generating a list of ad sizes from a predefined list. It selects the first 10 sizes that fall within the max size and minimum percentage size. All the interstitial parameters will still be passed to the bidders, allowing them to use their own size matching algorithms if they prefer. If you’d prefer to just define the size list, that’s ok too - just set the sizes a nd don’t define minWidthPerc/minHeightPerc.

Step 2: Set ad formats

For multiformat ad unit, you must set both banner and video ad formats.

Step 3: Configure parameters

Using the BannerParameters object you can customize the bid request for banner ads.

Starting from PrebidMobile 2.1.0 the BannerBaseAdUnit.Parameters class is deprecated. Use BannerParameters instead.

adSizes

Defines the OpenRTB banner.formats array.

interstitialMinWidthPerc and interstitialMinHeightPerc

For interstitials only, these define which sizes Prebid Server will choose to send to bidders. See Prebid Server interstitial support. If this option is used, you’ll need to set the size to 1x1.

api

The api property is dedicated to adding values for API Frameworks to bid response according to the OpenRTB 2.6 spec. The supported values for GMA SDK integration are:

  • 3 or Signals.Api.MRAID_1 : MRAID-1 support signal
  • 5 or Signals.Api.MRAID_2 : MRAID-2 support signal
  • 6 or Signals.Api.MRAID_3 : MRAID-3 support signal
  • 7 or Signals.Api.OMID_1 : signals OMSDK support

Video parameters

Using the VideoParameters object you can customize the bid request for video ads.

placement

Not needed for Instream video integration, which uses placement=1 and plcmt=1.

The OpenRTB 2.6 Placement Type for the auction can be expressed as an integer array or you can use an enum for easier readability.

  • 2 or InBanner : In-Banner placement exists within a web banner that leverages the banner space to deliver a video experience as opposed to another static or rich media format. The format relies on the existence of display ad inventory on the page for its delivery.
  • 3 or InArticle : In-Article placement loads and plays dynamically between paragraphs of editorial content; existing as a standalone branded message.
  • 4 or InFeed : In-Feed placement is found in content, social, or product feeds.
  • 5 or Slider, Floating or Interstitial : Open RTB supports one of three values for option 5 as either Slider, Floating or Interstitial. If an enum value is supplied in placement, bidders will receive value 5 for placement type and assume to be interstitial with the instl flag set to 1.

Notes:

  • VideoInterstitialAdUnit and rewarded video ads will default to placement= 5 if no placement value is supplied.

api

The api property is dedicated to adding values for API Frameworks to bid response according to the OpenRTB 2.6 spec. The supported values for GMA SDK integration are:

  • 1 or Signals.Api.VPAID_1 : VPAID 1.0
  • 2 or Signals.Api.VPAID_2 : VPAID 2.0
  • 3 or Signals.Api.MRAID_1 : MRAID-1 support signal
  • 5 or Signals.Api.MRAID_2 : MRAID-2 support signal
  • 6 or Signals.Api.MRAID_3 : MRAID-3 support signal
  • 7 or Signals.Api.OMID_1 : signals OMSDK support

maxBitrate

Integer representing the OpenRTB 2.6 maximum bit rate in Kbps.

minBitrate

Integer representing the OpenRTB 2.6 minimum bit rate in Kbps.

maxDuration

Integer representing the OpenRTB 2.6 maximum video ad duration in seconds.

minDuration

Integer representing the OpenRTB 2.6 minimum video ad duration in seconds.

mimes

Array of strings representing the supported OpenRTB 2.6 content MIME types (e.g., “video/x-ms-wmv”, “video/mp4”). Required property.

playbackMethod

Array of OpenRTB 2.6 playback methods. If none are specified, any method may be used. Only one method is typically used in practice. It is strongly advised to use only the first element of the array.

  • 1 or Signals.PlaybackMethod.AutoPlaySoundOn : Initiates on Page Load with Sound On
  • 2 or Signals.PlaybackMethod.AutoPlaySoundOff : Initiates on Page Load with Sound Off by Default
  • 3 or Signals.PlaybackMethod.ClickToPlay : Initiates on Click with Sound On
  • 4 or Signals.PlaybackMethod.MouseOver : Initiates on Mouse-Over with Sound On
  • 5 or Signals.PlaybackMethod.EnterSoundOn : Initiates on Entering Viewport with Sound On
  • 6 or Signals.PlaybackMethod.EnterSoundOff: Initiates on Entering Viewport with Sound Off by Default

protocols

Array or enum of OpenRTB 2.6 supported Protocols. Values can be one of:

  • 1 or Signals.Protocols.VAST_1_0 : VAST 1.0
  • 2 or Signals.Protocols.VAST_2_0 : VAST 2.0
  • 3 or Signals.Protocols.VAST_3_0 : VAST 3.0
  • 4 or Signals.Protocols.VAST_1_0_Wrapper : VAST 1.0 Wrapper
  • 5 or Signals.Protocols.VAST_2_0_Wrapper : VAST 2.0 Wrapper
  • 6 or Signals.Protocols.VAST_3_0_Wrapper : VAST 3.0 Wrapper
  • 7 or Signals.Protocols.VAST_4_0 : VAST 4.0
  • 8 or Signals.Protocols.VAST_4_0_Wrapper : VAST 4.0 Wrapper

Step 4: Make a bid request

The fetchDemand method makes a bid request to the Prebid Server. You should provide a GAMRequest object to this method so Prebid SDK sets the targeting keywords of the winning bid for future ad requests.

Step 5: Load a GAM interstitial ad

You should now request the ad from GAM. If the GAMRequest contains targeting keywords. The respective Prebid line item will be returned from GAM and GMA SDK will render its creative.

Be sure that you make the ad request with the same GAMRequest object that you passed to the fetchDemand method. Otherwise the ad request won’t contain targeting keywords and Prebid’s ad won’t ever be displayed.

Step 6: Present the interstitial ad

Follow the GMA SDK guide to display an interstitial ad right after receiving it or later in a natural pauses in the flow of an app.

Further Reading