In-app environment - Technical Requirements

Welcome to the integration documentation for In-App Bidding mode with Pubstack. This integration relies on Prebid Mobile SDK (v3+), in GAM Bidding-only mode.

---

✅ Prerequisites

• Native iOS (Swift) or Android (Kotlin) application (WebView not supported by Prebid Mobile SDK - available with a standard web integration)

• SDKs to integrate:

  • Prebid Mobile SDK v3+

  • Google Mobile Ads SDK (GMA)

  • Google IMA SDK (for Instream video ads)

  • Consent Management Platform (CMP) compatible with TCF v2

  • iOS only: ATT (App Tracking Transparency)

---

1. 🧱 Prebid SDK Initialization

The initialization of the Prebid SDK establishes the connection with Prebid Server – in our case, the server managed or instrumented by Pubstack. This includes configuring the endpoint URL and client identifiers.

Pubstack Identifiers: Pubstack provides an Account ID (publisher ID on Prebid Server) per application (and per OS) and uses config IDs (ad unit configuration IDs) for inventory.

• The Account ID is used during SDK initialization.

• Each ad placement will have its own config ID (see AdUnits section).

Android (Kotlin)

// Kotlin (Android) – Prebid Configuration
PrebidMobile.setPrebidServerAccountId("PUBSTACK_ACCOUNT_ID")
PrebidMobile.initializeSdk(
    context,
    "https://prebid-server.pbstck.com/openrtb2/auction",
) { status ->
    if (status == PrebidMobile.InitializationStatus.Succeeded) {
        Log.d("Prebid", "SDK initialized ✅")
    } else {
        Log.e("Prebid", "SDK init failed: $status")
    }
}

iOS (Swift)

import PrebidMobile

// Prebid configuration for iOS
Prebid.shared.prebidServerAccountId = "PUBSTACK_ACCOUNT_ID"
Prebid.shared.prebidServerHost = Host.Custom
Prebid.shared.customPrebidServerUrl = "https://prebid-server.pbstck.com/openrtb2/auction"

PrebidMobile.initializeSDK { status in
    switch status {
    case .succeeded:
        print("Prebid SDK initialized ✅")
    case .failed:
        print("Prebid SDK init failed ❌")
    @unknown default:
        print("Prebid SDK init status unknown ⚠️")
    }
}

In these examples, Prebid is initialized with:

• Account ID provided by Pubstack (available in Media & stacks > Select your app > Connect to Pubstack).

• Prebid Server URL: Pubstack endpoint.

Then Prebid Mobile will:

1. Check Prebid Server health (internal /status call) to ensure it’s reachable.

2. Prepare its internal components (local cache, etc.).

3. Use these parameters for all subsequent bid requests.

⚠️ Important: Prebid.initializeSDK must be called only once (typically at app launch, after the CMP). The SDK must be initialized before creating AdUnit objects or calling fetchDemand().

---

2. 🛡️ CMP and ATT

CMP

Include Pubstack vendor (ID 1408) in the list of allowed vendors, similar to other partners.

The CMP usually provides standardized keys in the app’s local storage, which Prebid SDK can automatically read:

• IABTCF_gdprApplies → whether the user is subject to GDPR (1 or 0).

• IABTCF_TCString → encoded TCF v2 consent string summarizing user choices.

• IABTCF_PurposeConsents → binary string indicating consent or not for each purpose (e.g. the first bit = Purpose 1: access device info).

Prebid SDK reads these values at initialization and on each bid request, without modifying or validating them.

👉 If the CMP stores them in the IAB format, no need to pass them explicitly into Prebid – the SDK will use them automatically.

SDK behavior depending on GDPR consent:

• Non-GDPR (gdprApplies=false): SDK sends advertising ID (IDFA/AAID) by default.

• GDPR, no consent for Purpose 1: SDK does not send IDFA/AAID; bid requests are anonymous.

• GDPR, consent given for Purpose 1: SDK sends IDFA/AAID normally.

• Invalid or undefined consent: SDK defaults to not sending any ID unless gdprApplies is explicitly false.

✅ To comply with GDPR:

1. Initialize the CMP at app launch, before requesting ads.

2. Ensure the TC String is stored locally (NSUserDefaults / SharedPreferences) before initializing Prebid or calling fetchDemand().

Once consent is obtained (or updated during session), Prebid automatically uses the latest value for the next bid request. If consent changes, trigger an update (e.g. re-run fetchDemand or recreate the AdUnit) to reflect new privacy parameters.

---

ATT (iOS only)

On iOS 14+, AppTrackingTransparency (ATT) requires explicit user permission to access IDFA. This directly impacts Prebid: if the user denies tracking, IDFA won’t be available or sent to partners.

Scenarios:

• Authorized: App has ATT permission → Prebid SDK retrieves IDFA via AdSupport and includes it in bid requests (unless blocked by GDPR).

• Denied/Not requested: No IDFA collection possible → Prebid still sends bid request, but without IDFA. Bidders must rely on other signals (IP, context, alternative IDs).

Integration required: Developer must trigger the ATT authorization request via ATTrackingManager.requestTrackingAuthorization at the right moment (often at app launch or before personalized ads). Apple recommends explaining ATT usage to the user before showing the popup.

ATTrackingManager.requestTrackingAuthorization { status in
    // Continue loading ads after response
}

⚠️ Don’t forget to add NSUserTrackingUsageDescription in Info.plist, otherwise the ATT popup won’t show.

<key>NSUserTrackingUsageDescription</key>
<string>We use your IDFA to personalize advertising.</string>

---

3. 📦 Declaring AdUnits

A Pubstack ad unit represents an ad placement in the app, linked to a bidding configuration on Prebid Server.

Currently, Pubstack supports Banner, Interstitial, and Instream Video formats.

---

Banner

Each Banner AdUnit is defined by:

• A configId (identifier of the placement configured in Pubstack/Prebid Server).

• A size (largest standard size the placement can accept).

💡 This size will be the only one injected in the bid request.

Naming rules – pbAdSlot (pubstack_adunit_name):

It is important to clearly name and identify placements. Prebid provides the pbAdSlot field (placement name) to pass the ad unit name to the server. Pubstack uses it to track the adunit_name.

• Sent in imp.ext.data.pbadslot of the bid request.

• Stored by Pubstack.

• Prebid 3.0 also supports GPID (Global Publisher ID) for standardized placement IDs (often GAM code) → adUnit.setGpid("...") on Android / adUnit.gpid = "..." on iOS.

iOS Example

let adUnit = BannerAdUnit(configId: "pubstack_adunit_name", size: CGSize(width:300, height:250))
adUnit.pbAdSlot = "pubstack_adunit_name"
adUnit.gpid = "/\(GAMNetworkCode)/\(AdUnitPath)"   // e.g. "/123456/homepage/top_banner"

Android Example

val adUnit = BannerAdUnit("pubstack_adunit_name", 320, 50)
adUnit.pbAdSlot = "pubstack_adunit_name"
adUnit.setGpid("/<NETWORK_CODE>/<AD_UNIT_PATH>")  // e.g. "/123456/homepage/top_banner"

---

Interstitial

Each Interstitial AdUnit is defined by:

• configId: ad unit name in Pubstack.

• minWidthPerc & minHeightPerc: % of screen width/height the ad must occupy to qualify as an interstitial.

Example:

• minWidthPerc=80 → must cover ≥80% of screen width.

• minHeightPerc=60 → must cover ≥60% of screen height.

As with banners, use clear naming rules:

• pbAdSlot (pubstack_adunit_name) → sent in imp.ext.data.pbadslot and stored by Pubstack.

• GPID (optional but recommended) → standardized GAM ad unit ID, sent in imp.gpid.

iOS Example

let interstitialAdUnit = InterstitialAdUnit(configId: "pubstack_adunit_name", minWidthPerc: 80, minHeightPerc: 60)
interstitialAdUnit.pbAdSlot = "pubstack_adunit_name"
interstitialAdUnit.gpid = "/\(GAMNetworkCode)/\(AdUnitPath)"   // e.g. "/123456/app/interstitial"

Android Example

val interstitialAdUnit = InterstitialAdUnit("pubstack_adunit_name", 80, 60)
interstitialAdUnit.pbAdSlot = "pubstack_adunit_name"
interstitialAdUnit.setGpid("/<NETWORK_CODE>/<AD_UNIT_PATH>")  // e.g. "/123456/app/interstitial"

---

Instream Video (pre-/mid-/post-roll)

Instream video ads are served within video content (pre-roll, mid-roll, or post-roll) using the IMA SDK. Each Instream AdUnit is defined by:

• A configId (identifier of the placement configured in Pubstack/Prebid Server).

• A size (video player dimensions, typically 640x480).

• Video parameters following OpenRTB 2.6 specification.

💡 Instream ads require the Google IMA SDK (Interactive Media Ads) in addition to the standard Prebid and GMA SDKs.

Required video parameters:

Parameter	Value	Description
plcmt	Signals.Plcmt.InStream	Placement type (plcmt=1)
placement	Signals.Placement.InStream	OpenRTB placement

Customizable video parameters:

Parameter	Type	Description
mimes	Array	Supported MIME types (e.g., "video/mp4")
protocols	Array	VAST versions supported
playbackMethod	Array	Auto-play behavior
minDuration	Integer	Minimum ad duration (seconds)
maxDuration	Integer	Maximum ad duration (seconds)
minBitrate	Integer	Minimum bitrate (kbps)
maxBitrate	Integer	Maximum bitrate (kbps)
api	Array	Supported APIs (e.g., OMSDK)
isSkippable	Boolean	Whether the ad can be skipped
startDelay	Enum	Pre-roll, mid-roll, or post-roll position

iOS Example

import PrebidMobile
import GoogleInteractiveMediaAds // IMA SDK

// 1) Declare the Instream ad unit
let instreamAdUnit = InstreamVideoAdUnit(
  configId: "pubstack_adunit_name",
  size: CGSize(width: 640, height: 480)
)

// 2) Configure video parameters (OpenRTB 2.6)
let videoParams = VideoParameters(mimes: ["video/mp4"])
videoParams.protocols = [
  Signals.Protocols.VAST_2_0,
  Signals.Protocols.VAST_2_0_Wrapper,
  Signals.Protocols.VAST_3_0,
  Signals.Protocols.VAST_3_0_Wrapper,
  Signals.Protocols.VAST_4_0,
  Signals.Protocols.VAST_4_0_Wrapper
]
// Required fields - must have these values
videoParams.plcmt = Signals.Plcmt.InStream   // plcmt=1
videoParams.placement = Signals.Placement.InStream

// Customizable fields
videoParams.playbackMethod = [Signals.PlaybackMethod.AutoPlaySoundOn]
videoParams.minDuration = 5          // seconds
videoParams.maxDuration = 30         // seconds
videoParams.minBitrate  = 300        // kbps
videoParams.maxBitrate  = 2500       // kbps
videoParams.api = [Signals.Api.OMID_1] // OMSDK
videoParams.isSkippable = true
videoParams.startDelay = Signals.StartDelay.Preroll
// Use .Midroll or .Postroll for mid-roll/post-roll ads

instreamAdUnit.videoParameters = videoParams

Android Example

import org.prebid.mobile.*
import com.google.ads.interactivemedia.v3.api.* // IMA SDK

// 1) Declare the Instream ad unit
val instreamAdUnit = InstreamVideoAdUnit(
  configId = "pubstack_adunit_name",
  AdSize(640, 480)
)

// 2) Configure video parameters (OpenRTB 2.6)
val videoParams = VideoParameters(arrayListOf("video/mp4"))
videoParams.protocols = listOf(
  Signals.Protocols.VAST_2_0,
  Signals.Protocols.VAST_2_0_Wrapper,
  Signals.Protocols.VAST_3_0,
  Signals.Protocols.VAST_3_0_Wrapper,
  Signals.Protocols.VAST_4_0,
  Signals.Protocols.VAST_4_0_Wrapper
)
// Required fields - must have these values
videoParams.plcmt = Signals.Plcmt.InStream
videoParams.placement = Signals.Placement.InStream

// Customizable fields
videoParams.playbackMethod = listOf(Signals.PlaybackMethod.AutoPlaySoundOn)
videoParams.minDuration = 5
videoParams.maxDuration = 30
videoParams.minBitrate = 300
videoParams.maxBitrate = 2500
videoParams.api = listOf(Signals.Api.OMID_1)
videoParams.isSkippable = true
videoParams.startDelay = Signals.StartDelay.Preroll

instreamAdUnit.videoParameters = videoParams

All video parameter fields follow the OpenRTB 2.6 specification.

---

4. 🎯 Prebid Fetch & GAM Ad Load

Once the Prebid AdUnit is configured, the flow to display an ad via GAM is:

1. Prebid auction call → Trigger fetchDemand() on the Prebid AdUnit, passing the GAM ad request object.

2. GAM Ad Request → GAM SDK sends the request with the ad unit ID + Prebid-enriched targeting.

3. Creative rendering → If a Prebid line item matches, GAM serves a universal creative (Prebid Universal Creative or cache-based) which retrieves and renders the actual winning ad.

Important: The code snippets below are provided as a reference template only. They must be reviewed and adapted by your application developers to fit your specific app architecture (e.g. lifecycle management, view hierarchy, error handling).

Android Example (Kotlin, GMA SDK 23.6.0+)

Banner

package io.pubstack.prebid_sdk.component

import android.content.Context
import android.util.Log
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.runtime.Composable
import androidx.compose.ui.Modifier
import androidx.compose.ui.platform.LocalContext
import androidx.compose.ui.unit.dp
import androidx.compose.ui.viewinterop.AndroidView
import com.google.android.gms.ads.AdSize
import com.google.android.gms.ads.admanager.AdManagerAdRequest
import com.google.android.gms.ads.admanager.AdManagerAdView
import org.prebid.mobile.BannerAdUnit

@Composable
fun PrebidBannerAd(
    adUnitId: String,          // GAM Ad Unit ID (ex: "/123456/home/top_banner")
    configId: String,          // Pubstack adunit name
    width: Int,                // Banner width (e.g., 320)
    height: Int,               // Banner height (e.g., 50)
    context: Context = LocalContext.current
) {
    AndroidView(
        modifier = Modifier
            .fillMaxWidth()
            .height(height.dp),
        factory = {
            // 1) Create GAM banner view
            val adView = AdManagerAdView(context).apply {
                adUnitId = adUnitId
                setAdSizes(AdSize(width, height))
            }

            // 2) Create Prebid banner ad unit
            val adUnit = BannerAdUnit(configId, width, height).apply {
                pbAdSlot = configId
                gpid = adUnitId
            }

            // 3) Create GAM request
            val gamRequest = AdManagerAdRequest.Builder().build()

            // 4) Enrich GAM request with Prebid demand
            adUnit.fetchDemand(gamRequest) { resultCode ->
                Log.d("PrebidBannerAd", "Prebid fetch result: $resultCode")
                // 5) Load GAM banner with SAME enriched request
                adView.loadAd(gamRequest)
            }

            adView
        }
    )
}

Interstitial

import android.app.Activity
import com.google.android.gms.ads.LoadAdError
import com.google.android.gms.ads.admanager.AdManagerAdRequest
import com.google.android.gms.ads.admanager.AdManagerInterstitialAd
import com.google.android.gms.ads.admanager.AdManagerInterstitialAdLoadCallback

fun loadInterstitial(activity: Activity, adUnitId: String) {
    // 1) Create a GAM request
    val gamRequest = AdManagerAdRequest.Builder().build()

    // 2) Enrich with Prebid targeting
    interstitialAdUnit.fetchDemand(gamRequest) { _ ->
        // 3) Load the GAM interstitial with the SAME enriched request
        AdManagerInterstitialAd.load(
            activity,
            adUnitId,
            gamRequest,
            object : AdManagerInterstitialAdLoadCallback() {
                override fun onAdLoaded(ad: AdManagerInterstitialAd) {
                    // 4) Present at the right UX moment
                    ad.show(activity)
                }
                override fun onAdFailedToLoad(error: LoadAdError) {
                    // Handle failure (retry/backoff/metrics)
                }
            }
        )
    }
}

iOS Example (Swift, GMA SDK 11.9.0+)

Banner

import UIKit
import GoogleMobileAds
import PrebidMobile

final class BannerController {

    private var gamBanner: GAMBannerView?
    private let bannerAdUnit: BannerAdUnit
    private let gamAdUnitId: String

    init(configId: String, gamAdUnitId: String) {
        self.bannerAdUnit = BannerAdUnit(configId: configId, size: CGSize(width: 320, height: 50))
        self.bannerAdUnit.pbAdSlot = configId
        self.bannerAdUnit.gpid = gamAdUnitId
        self.gamAdUnitId = gamAdUnitId
    }

    func load(in viewController: UIViewController, container: UIView) {
        // 1️) Create the GAM banner view
        let gamBanner = GAMBannerView(adSize: GADAdSizeBanner)
        gamBanner.adUnitID = gamAdUnitId
        gamBanner.rootViewController = viewController
        container.addSubview(gamBanner)
        gamBanner.center = container.center

        // 2️) Create a GAM request
        let request = GAMRequest()

        // 3️) Enrich with Prebid demand
        bannerAdUnit.fetchDemand(adObject: request) { result in
            print("Prebid fetchDemand result: \(result.name())")
            // 4️) Load the GAM banner ad
            gamBanner.load(request)
        }

        self.gamBanner = gamBanner
    }
}

Interstitial

import GoogleMobileAds
import PrebidMobile

final class InterstitialController {
    private var gamInterstitial: GAMInterstitialAd?
    private let interstitialAdUnit: PrebidMobile.InterstitialAdUnit
    private let gamAdUnitId: String

    init(configId: String, gamAdUnitId: String) {
        self.interstitialAdUnit = PrebidMobile.InterstitialAdUnit(
            configId: configId,
            minWidthPerc: 80,
            minHeightPerc: 60
        )
        self.gamAdUnitId = gamAdUnitId
    }

    func load(rootViewController: UIViewController) {
        // 1) Create a GAM request
        let request = GAMRequest()

        // 2) Enrich with Prebid targeting
        interstitialAdUnit.fetchDemand(adObject: request) { _ in
            // 3) Load the GAM interstitial with the SAME enriched request
            GAMInterstitialAd.load(withAdManagerAdUnitID: self.gamAdUnitId,
                                   request: request) { [weak self] ad, error in
                guard let self = self, let ad = ad, error == nil else {
                    // Handle failure (retry/backoff/metrics)
                    return
                }
                self.gamInterstitial = ad

                // 4) Present at the right UX moment (not necessarily immediately)
                ad.present(fromRootViewController: rootViewController)
            }
        }
    }
}

🔎 How it works

• fetchDemand(): Sends an OpenRTB request to Prebid Server (with size, configId, pbAdSlot/gpid).

• Prebid Server: Runs the auction across connected SSPs/DSPs and returns the winning bid.

• Prebid SDK: Adds targeting key-values into the GAM request (bid_bidder, bid_cpm, hb_cache_id, etc.).

• GAM: Uses these targeting keys to match against Prebid line items. If a Prebid line item wins, GAM serves the universal creative which then fetches and renders the actual winning ad.

The same GAM request instance enriched by fetchDemand() must be used for the subsequent load call (banner or interstitial).

---

Instream Video (via IMA SDK)

The Bidding-Only Instream flow works as follows:

1. fetchDemand from Prebid to retrieve the winning keywords.

2. Generate the IMA ad tag URL for GAM using those keywords (Prebid utility).

3. Load and play the ad via IMA SDK in your video player (pre-/mid-/post-roll).

🍏 iOS Example (Swift, IMA SDK 3.18+)

// 3) Prepare the IMA AdsLoader (instantiate once)
let adsLoader = IMAAdsLoader(settings: nil)
adsLoader.delegate = self

// 4) Prebid bid request
instreamAdUnit.fetchDemand { [weak self] (code, prebidKeys) in
  guard let self = self, code == .prebidDemandFetchSuccess, let prebidKeys else {
    // Fallback: start content playback
    return
  }

  do {
    // 5) Build the IMA ad tag URL for GAM with Prebid keywords
    let imaTag = try IMAUtils.shared.generateInstreamUriForGAM(
      adUnitID: "/<GAM_NETWORK>/<GAM_ADUNIT_ID>",
      adSlotSizes: [.Size640x480],
      customKeywords: prebidKeys
    )

    // 6) Load the IMA request
    let container = IMAAdDisplayContainer(
      adContainer: self.videoContainerView,
      viewController: self
    )
    let request = IMAAdsRequest(
      adTagUrl: imaTag,
      adDisplayContainer: container,
      contentPlayhead: nil,
      userContext: nil
    )
    adsLoader.requestAds(with: request)

  } catch {
    // Fallback: start content playback
  }
}

// 7-8) Handle IMA callbacks
func adsLoader(_ loader: IMAAdsLoader, adsLoadedWith data: IMAAdsLoadedData) {
  let manager = data.adsManager
  manager?.delegate = self
  manager?.initialize(with: nil)
}

func adsManager(_ manager: IMAAdsManager, didReceive event: IMAAdEvent) {
  if event.type == .LOADED { manager.start() }
}

🤖 Android Example (Kotlin, IMA SDK 3.31+)

// 3) Prepare the player + IMA AdsLoader
val adsLoader = ImaAdsLoader.Builder(context).build()

// 4) Prebid bid request
instreamAdUnit.fetchDemand { code, prebidKeys ->
  if (code != FetchDemandResult.Success || prebidKeys == null) {
    // Fallback: start content playback
    return@fetchDemand
  }

  // 5) Build the IMA ad tag URL for GAM with Prebid keywords
  val imaTag = IMAUtils.generateInstreamUriForGAM(
    "/<GAM_NETWORK>/<GAM_ADUNIT_ID>",
    listOf(AdSize(640, 480)),
    prebidKeys
  )

  // 6) Initialize IMA + start the ad
  val adViewProvider = ... // your container/view
  val adsMediaSourceFactory = AdsMediaSource.MediaSourceFactory { mediaItem ->
    player.createMediaSource(mediaItem)
  }
  val adsMediaSource = AdsMediaSource(
    contentMediaSource,
    Uri.parse(imaTag),
    adsMediaSourceFactory,
    adsLoader,
    adViewProvider
  )
  player.setMediaSource(adsMediaSource)
  player.prepare()
  player.playWhenReady = true
}

The code snippets above are provided as a reference template only. They must be reviewed and adapted by your application developers to fit your specific app architecture (e.g., lifecycle management, view hierarchy, error handling).

🔎 How Instream works

• fetchDemand(): Sends an OpenRTB request to Prebid Server with video parameters.

• Prebid Server: Runs the auction across connected SSPs/DSPs and returns the winning VAST URL.

• IMAUtils: Generates a GAM ad tag URL containing Prebid targeting keys.

• IMA SDK: Loads the ad tag, GAM matches against Prebid line items, and serves the winning VAST creative.

• Video Player: Renders the VAST ad at the appropriate position (pre-/mid-/post-roll).

Always handle the fallback case when Prebid fails or returns no demand – start content playback without ads rather than blocking the user experience.

---

5. 🧪 Test & Debug

• Check Prebid logs for bid responses.

• Ensure GAM request contains targeting keys (bid_bidder, bid_cpm, etc.).

• Use Google Ad Inspector for local testing.