Skip to main content
Version: SDK 4.x

Migration from 3.x to 4.0

BidMachine SDK 4.0 replaces the public API of 3.x. There is no compatibility layer: code written for 3.x doesn't compile against 4.0 and has to be updated as described on this page.

The main changes:

  • The SDK is initialized per source ID and returns a BidMachineInstance. Ads are loaded through the instance; BidMachineSdk.shared is gone.
  • Ads are loaded with one call. Placements with formats, auction requests and the separate loadAd() step are removed; the loader delivers an ad that is ready to show.
  • Each ad format has its own delegate protocol, and the result of the load comes to the loader's completion.
  • Privacy settings are passed as a consent provider object, targeting and publisher data as a first-party data provider object.
  • Native ads have a new binding API: your app draws the content, the ad provides its media view, privacy view and "Ad" badge.
  • Swift types lost the BidMachine prefix: InterstitialAd, RewardedAd, BannerView, NativeAd, Placement. Objective-C names keep it.
  • The minimum iOS version is 15.0.
Staying on 3.x

SDK 3.8.x remains available. Its documentation is in the version selector at the top of the page, under 3.x.

1. Dependency​

Raise the deployment target of your app to iOS 15.0 or later and update the version of the pod:

Podfile
platform :ios, '15.0'

pod 'BidMachine', '~> 4.0.0'
  • The minimum iOS version is raised from 12.0 to 15.0.
  • The Open Measurement dependency is now OMSDK_Bidmachine instead of OMSDK_Appodeal. CocoaPods resolves it automatically; for a manual integration replace the framework as described in the integration guide.
  • Header bidding networks inside BidMachine are removed, together with their adapter pods (BidMachine<Network>Adapter). Remove these pods from your Podfile.

2. Initialization​

// 3.x
BidMachineSdk.shared
.withTestMode(true)
.withLoggingMode(true)
BidMachineSdk.shared.initializeSdk("YOUR_SOURCE_ID")
// 4.0
BidMachineSdk.testMode = true
BidMachineSdk.isLoggingEnabled = true
let bidMachine = BidMachineSdk.initialize(sourceId: "YOUR_SOURCE_ID")
  • initialize returns the instance immediately. Ads are loaded and tokens are collected through it.
  • BidMachineSdk.shared.isInitialized is removed. Until the very first initialization on a device has finished, loads and token requests fail with the notInitialized error code; on later launches the SDK is ready at once.
  • Calling initialize again with the same source ID returns an instance equal to the first one. Several source IDs give several independent instances.
  • withLoggingMode, withBidLoggingMode and withEventLoggingMode are replaced with one switch, BidMachineSdk.isLoggingEnabled.
  • BidMachineSdk.sdkName, partnerName and partnerVersion are removed. Mediation adapters pass their name and version in Configuration.mediationInfo.
3.x4.0
BidMachineSdk.shared.initializeSdk(sourceId)BidMachineSdk.initialize(sourceId:configuration:)
BidMachineSdk.shared.isInitializedremoved
withTestMode(_:)BidMachineSdk.testMode
withLoggingMode(_:), withBidLoggingMode(_:), withEventLoggingMode(_:)BidMachineSdk.isLoggingEnabled
BidMachineSdk.shared.extrasValue(by:)bidMachine.customParams[key]
withFrameworkName(_:)removed

3. Privacy​

All privacy setters are replaced with one object that conforms to ConsentProvider, assigned to BidMachineSdk.consentProvider. See Data Privacy.

3.x4.0 ConsentProvider
withGDPRZone(_:)gdprApplies
withGDPRConsent(_:)gdprConsent
withCOPPA(_:)coppa
withNonPersonalized(_:)nonPersonalized
withGPP(_:_:)gppString, gppSids
withUSPrivacyString(_:)removed, use GPP
// 3.x
BidMachineSdk.shared
.withGDPRZone(true)
.withGDPRConsent(true)
.withCOPPA(false)
// 4.0
final class AppConsent: NSObject, ConsentProvider {
var coppa: NSNumber? { false }
var gdprApplies: NSNumber? { true }
var gdprConsent: NSNumber? { true }
var nonPersonalized: NSNumber? { nil }
var gppString: String? { nil }
var gppSids: [NSNumber]? { nil }
}

BidMachineSdk.consentProvider = AppConsent()
  • The values the CMP stores in UserDefaults are still read automatically.
  • When consent changes during the app's run, assign the provider again. The SDK doesn't watch the object or the CMP's values for changes.

4. Targeting and Publisher Data​

The targeting, store, publisher and block list setters are replaced with one object that conforms to FirstPartyDataProvider, assigned to the instance: bidMachine.firstPartyDataProvider. See First-Party Data.

3.x4.0 FirstPartyDataProvider
withUserId(_:)userId
withUserGender(_:)gender
withUserYOB(_:)yearOfBirth
withKeywords(_:) (one string)keywords (an array)
withCountry(_:), withCity(_:), withZip(_:)country, city, zip
withLocation(_:)location
appendExternalId(_:_:)externalIds
withStoreId(_:), withStoreURL(_:), withStoreCategory(_:), withStoreSubCategories(_:), withPaid(_:)storeId, storeUrl, storeCategory, storeSubcategories, paid
withPubId(_:), withPubName(_:), withPubDomain(_:), withPubCategories(_:)publisherId, publisherName, publisherDomain, publisherCategories
withBlockedCategories(_:), withBlockedAdvertisers(_:), withBlockedApps(_:)blockedCategories, blockedAdvertisers, blockedApps

The data is set per instance and is copied when the provider is assigned: to update it, assign the provider again.

5. Loading Ads​

In 3.x an ad went through four steps: a placement with a format, an auction request, an empty ad object and loadAd(). In 4.0 it is one call on the instance, and the completion delivers a loaded ad.

// 3.x
let placement = try? BidMachineSdk.shared.placement(.interstitial) {
$0.withPlacementId("YOUR_PLACEMENT_ID")
$0.withCustomParameters(["key": "value"])
}
let request = BidMachineSdk.shared.auctionRequest(placement: placement) {
$0.appendPriceFloor(10, "price_floor_id")
}
BidMachineSdk.shared.interstitial(request: request) { [weak self] ad, error in
guard let self else { return }
self.interstitial = ad
self.interstitial.controller = self
self.interstitial.delegate = self
self.interstitial.loadAd()
}

// later, in didLoadAd
interstitial.presentAd()
// 4.0
let placement = Placement(
id: "YOUR_PLACEMENT_ID",
extras: ["key": "value", "price_floor": 10.0]
)

bidMachine.loadInterstitial(placement: placement) { [weak self] ad, error in
guard let self, let ad else {
// Load failed, see `error`
return
}
ad.delegate = self
self.interstitial = ad
}

// later
interstitial.show(from: self)
3.x4.0
BidMachineSdk.shared.placement(format) { ... }Placement(id:extras:)
withPlacementId(_:)Placement.id
withCustomParameters(_:)Placement.extras
AdFormat (.interstitial, .rewardedVideo, .banner320x50, .native, ...)removed, the format is chosen by the load method
BidMachineSdk.shared.auctionRequest(placement:)removed
appendPriceFloor(_:_:)Placement.extras["price_floor"], see Price floor
withUnitConfigurations(_:)removed with header bidding
BidMachineSdk.shared.interstitial(request:) + loadAd()bidMachine.loadInterstitial(placement:completion:)
BidMachineSdk.shared.rewarded(request:) + loadAd()bidMachine.loadRewarded(placement:completion:)
BidMachineSdk.shared.banner(request:) + loadAd()bidMachine.loadBanner(placement:size:completion:)
BidMachineSdk.shared.native(request:) + loadAd()bidMachine.loadNative(placement:completion:)
  • The placement is optional. Without it the ad is requested for the default slot of your source.
  • The Static / Video variants of the interstitial and rewarded formats and the asset variants of the native format are removed: the content is no longer chosen in the app.
  • The completion delivers either a loaded ad or a BidMachineError, on the main thread. Keep a strong reference to the ad.

Client Bidding​

The bid token is collected per instance and is no longer tied to an ad format. The payload goes to the payload variant of the loader instead of the auction request.

// 3.x
BidMachineSdk.shared.token(placement: placement) { token in
// token is nil on failure
}

let request = BidMachineSdk.shared.auctionRequest(placement: placement) {
$0.withPayload(payload)
}
// 4.0
bidMachine.collectToken(placements: [placement]) { token, error in
// Either the token or the error is set
}

bidMachine.loadInterstitial(payload: payload) { ad, error in }

collectToken always reports the reason of a failure in error, so "not initialized" can be told apart from other failures.

6. Ad Objects and Delegates​

3.x4.0 Swift4.0 Objective-C
BidMachineInterstitialInterstitialAdBidMachineInterstitial
BidMachineRewardedRewardedAdBidMachineRewarded
BidMachineBannerBannerViewBidMachineBanner
BidMachineNativeNativeAdBidMachineNative
BidMachineAdProtocolBidMachineAdBidMachineAd
BidMachineAdDelegateInterstitialAdDelegate, RewardedAdDelegate, BannerViewDelegate, NativeAdDelegateBidMachineInterstitialDelegate, BidMachineRewardedDelegate, BidMachineBannerDelegate, BidMachineNativeDelegate
3.x ad4.0 ad
loadAd()removed, the loader delivers a loaded ad
presentAd()show(from:) for interstitial and rewarded
controllerthe argument of show(from:); rootViewController for banner and native
canShowcanShow
auctionInfoauctionInfo
requestInforemoved
rendererConfiguration.extrasextras

The single BidMachineAdDelegate is replaced with one protocol per format. The ad comes typed, so no casts are needed. In Objective-C the selectors carry the format prefix, for example interstitialDidPresent:.

3.x BidMachineAdDelegate4.0
didLoadAd(_:)the loader's completion, with an ad
didFailLoadAd(_:_:)the loader's completion, with an error
didPresentAd(_:)didPresent(_:)
didFailPresentAd(_:_:)didFailPresent(_:error:)
didDismissAd(_:)didDismiss(_:), interstitial and rewarded only
didTrackImpression(_:)didTrackImpression(_:)
didUserInteraction(_:)didClick(_:)
didTrackInteraction(_:)removed, use didClick(_:)
didExpired(_:)didExpire(_:)
didReceiveReward(_:)didReceiveReward(_:), rewarded only
willPresentScreen(_:), didDismissScreen(_:)willPresentScreen(_:), didDismissScreen(_:)

didPresent, didFailPresent, didTrackImpression and didClick are required for every format, didDismiss for interstitial and rewarded, didReceiveReward for rewarded. The rest are optional.

7. Banner​

The banner size moved from the format of the placement to the size argument of loadBanner.

3.x AdFormat4.0 BannerSize
.banner320x50.banner
.banner728x90.leaderboard
.banner300x250.mrec
.bannerAdaptive(width:maxHeight:).adaptive(width:maxHeight:)
BidMachineBannerSize.getMaxAdaptiveHeight(width:)BannerSize.maxAdaptiveHeight(width:)
// 4.0
bidMachine.loadBanner(placement: placement, size: .banner) { [weak self] banner, error in
guard let self, let banner else { return }
banner.delegate = self
banner.rootViewController = self
self.view.addSubview(banner)
// Lay the banner out using banner.adSize
}
  • controller is renamed to rootViewController.
  • The ad is shown when the delivered view enters a window. There is no loadAd() call after adding it.
  • A banner is shown once and the SDK doesn't refresh it: to refresh, load a new banner.

See Banner Ads.

8. Native​

BidMachineNativeAdRendering, presentAd(in:rendering:) and registerAssetsForInteraction are replaced with bind / unbind. The SDK no longer fills your labels and image views: your app sets them from the ad's data.

// 3.x
nativeAd.registerAssetsForInteraction([
BidMachineNativeAdRenderingAssetType.titleLabel.rawValue
])
try nativeAd.presentAd(in: nativeAdView, rendering: nativeAdView)
// 4.0
titleLabel.text = nativeAd.title
bodyLabel.text = nativeAd.body
callToActionButton.setTitle(nativeAd.callToAction, for: .normal)
iconView.image = nativeAd.icon?.image
mediaContainer.addSubview(nativeAd.mediaView)

nativeAd.rootViewController = self
nativeAd.bind(nativeAdView, clickables: [
NativeAd.Entry(titleLabel, as: .title),
NativeAd.Entry(callToActionButton, as: .callToAction)
])
3.x4.0
BidMachineNativeAdRendering protocolremoved, set your views from the ad's data
titleLabel, descriptionLabel, callToActionLabeltitle, body, callToAction
iconViewicon (image and url)
mediaContainerViewmediaView, a view created by the ad that you place
adChoiceViewadChoice, a view created by the ad
—adBadge, advertiser, starRating, mainImage, hasVideoContent (new)
presentAd(in:rendering:)bind(_:clickables:)
registerAssetsForInteraction(_:)the clickables argument of bind
unregisterView()unbind()

See Native Ads.

9. Auction Info, Win/Loss and Errors​

3.x4.0
auctionInfo.cIdauctionInfo.campaignId
auctionInfo.customExtrasremoved
auctionInfo.demandSource (String)auctionInfo.demandSource (String?)
BidMachineSdk.shared.notifyMediationWin(ad)ad.notifyWin()
BidMachineSdk.shared.notifyMediationLoss(winner, price, ad)ad.notifyLoss(winner:price:) or ad.notifyLoss()

Errors are BidMachineError everywhere, an NSError subclass in the com.adx.bidmachine.kit.error domain. The codes are listed in Errors.

10. Removed Without Replacement​

3.xNote
Header bidding: registerBiddingAdapters, BidMachineUnitConfiguration, the BidMachine<Network>Adapter podsClient-side header bidding is removed from the SDK.
populate and the info protocols (regulationInfo, targetingInfo, publisherInfo)Replaced by the consent and first-party data providers.
withUSPrivacyString(_:)Use GPP.
withFrameworkName(_:)Not used by the server anymore.
requestInfo on the adThe request object is removed.