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.sharedis 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
BidMachineprefix:InterstitialAd,RewardedAd,BannerView,NativeAd,Placement. Objective-C names keep it. - The minimum iOS version is 15.0.
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:
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_Bidmachineinstead ofOMSDK_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")
initializereturns the instance immediately. Ads are loaded and tokens are collected through it.BidMachineSdk.shared.isInitializedis removed. Until the very first initialization on a device has finished, loads and token requests fail with thenotInitializederror code; on later launches the SDK is ready at once.- Calling
initializeagain with the same source ID returns an instance equal to the first one. Several source IDs give several independent instances. withLoggingMode,withBidLoggingModeandwithEventLoggingModeare replaced with one switch,BidMachineSdk.isLoggingEnabled.BidMachineSdk.sdkName,partnerNameandpartnerVersionare removed. Mediation adapters pass their name and version inConfiguration.mediationInfo.
| 3.x | 4.0 |
|---|---|
BidMachineSdk.shared.initializeSdk(sourceId) | BidMachineSdk.initialize(sourceId:configuration:) |
BidMachineSdk.shared.isInitialized | removed |
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.x | 4.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
UserDefaultsare 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.x | 4.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.x | 4.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/Videovariants 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.x | 4.0 Swift | 4.0 Objective-C |
|---|---|---|
BidMachineInterstitial | InterstitialAd | BidMachineInterstitial |
BidMachineRewarded | RewardedAd | BidMachineRewarded |
BidMachineBanner | BannerView | BidMachineBanner |
BidMachineNative | NativeAd | BidMachineNative |
BidMachineAdProtocol | BidMachineAd | BidMachineAd |
BidMachineAdDelegate | InterstitialAdDelegate, RewardedAdDelegate, BannerViewDelegate, NativeAdDelegate | BidMachineInterstitialDelegate, BidMachineRewardedDelegate, BidMachineBannerDelegate, BidMachineNativeDelegate |
| 3.x ad | 4.0 ad |
|---|---|
loadAd() | removed, the loader delivers a loaded ad |
presentAd() | show(from:) for interstitial and rewarded |
controller | the argument of show(from:); rootViewController for banner and native |
canShow | canShow |
auctionInfo | auctionInfo |
requestInfo | removed |
rendererConfiguration.extras | extras |
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 BidMachineAdDelegate | 4.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 AdFormat | 4.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
}
controlleris renamed torootViewController.- 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.x | 4.0 |
|---|---|
BidMachineNativeAdRendering protocol | removed, set your views from the ad's data |
titleLabel, descriptionLabel, callToActionLabel | title, body, callToAction |
iconView | icon (image and url) |
mediaContainerView | mediaView, a view created by the ad that you place |
adChoiceView | adChoice, 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.x | 4.0 |
|---|---|
auctionInfo.cId | auctionInfo.campaignId |
auctionInfo.customExtras | removed |
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.x | Note |
|---|---|
Header bidding: registerBiddingAdapters, BidMachineUnitConfiguration, the BidMachine<Network>Adapter pods | Client-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 ad | The request object is removed. |