Skip to main content

Native Ads

Ad Request​

Placement​

Create placement from PlacementFormat with your parameters:

let placement = try? BidMachineSdk.shared.placement(from: .native) {
  $0.withPlacementId("")
  $0.withCustomParameters([String:Any]())
}
ParameterTypeDescription
placementIdStringPlacement ID
customParameters[String: Any] / NSDictionaryPassed directly to the server

PlacementFormat​

The placement format is defined by the PlacementFormat enum:

@objc(BidMachinePlacementFormat)
public enum PlacementFormat: Int {
  case native
  case nativeIcon
  case nativeImage
  case nativeVideo
  case nativeIconAndVideo
  case nativeIconAndImage
  case nativeImageAndVideo
}

You can also get a format from a string:

let format = "native".bidmachine_placement_format

Registered placement formats​

NameDescription
nativeFull native ad with all assets
native_iconIcon only
native_imageImage only
native_videoVideo only
native_icon_and_videoIcon plus video
native_icon_and_imageIcon plus image
native_image_and_videoImage plus video

General Request​

Auction request is used to set bidding parameters: The request is created with a special placement and your parameters

let request = BidMachineSdk.shared.auctionRequest(placement: placement) {
  $0.withUnitConfigurations([BidMachineUnitConfiguration]())
  $0.appendPriceFloor(Double(10), UUID().uuidString)
}
ParameterTypeDescription
unitConfigurations[BidMachineUnitConfiguration]Header bidding unit configurations
priceFloor(Double, String)Price floor (value and identifier)

Client Bidding Request​

Bid Token​

With S2S integration, you will need a token that you need to transfer in the request. To get a token, you can use method:

 BidMachineSdk.shared.token(placement: placement) { token in }

Bid Payload​

After completing the server-side auction, you will receive a Base64-encoded payload string, which must be passed as a parameter to the AuctionRequest.

let request = BidMachineSdk.shared.auctionRequest(placement: placement) {
  $0.withPayload("")
}
ParameterTypeDescription
payloadStringCustom BidMachine payload string

Ad Display​

The ad object downloads and displays native ads.

Prepare the ad object​

Request an ad using your auction request:

BidMachineSdk.shared.native(request: request) { [weak self] ad, error in
  guard let self else { return }
  self.native = ad
}

The loaded ad provides auctionInfo and requestInfo.

Auction Info

The auctionInfo contains information about the auction, such as the winning bidder, price, and other relevant details. The auctionInfo is described here.

Delegate​

Assign the delegate to receive ad events:

ad.delegate = self

Implement BidMachineAdDelegate methods:

func didLoadAd(_ ad: BidMachineAdProtocol) {}
func didFailLoadAd(_ ad: BidMachineAdProtocol, _ error: Error) {}
func didPresentAd(_ ad: BidMachineAdProtocol) {}
func didFailPresentAd(_ ad: BidMachineAdProtocol, _ error: Error) {}
func didDismissAd(_ ad: BidMachineAdProtocol) {}
func willPresentScreen(_ ad: BidMachineAdProtocol) {}
func didDismissScreen(_ ad: BidMachineAdProtocol) {}
func didUserInteraction(_ ad: BidMachineAdProtocol) {}
func didExpired(_ ad: BidMachineAdProtocol) {}
func didTrackImpression(_ ad: BidMachineAdProtocol) {}
func didTrackInteraction(_ ad: BidMachineAdProtocol) {}
func didReceiveReward(_ ad: BidMachineAdProtocol) {}

Loading and presenting native ads​

Loading prerequisites

Ensure both delegate and controller are set before loading.

Example of native ad loading:

guard let placement = try? BidMachineSdk.shared.placement(from: .native) else { return }
let request = BidMachineSdk.shared.auctionRequest(placement: placement)
BidMachineSdk.shared.native(request: request) { [weak self] ad, error in
  guard let self = self else {
    return
  }
  self.native = ad
  self.native.controller = self
  self.native.delegate = self
  self.native.loadAd()
}

When presenting, implement BidMachineNativeAdRendering to expose UI assets and register them for interaction:

@objc public protocol BidMachineNativeAdRendering {
  var titleLabel: UILabel? { get }
  var callToActionLabel: UILabel? { get }
  var descriptionLabel: UILabel? { get }
  var iconView: UIImageView? { get }
  var mediaContainerView: UIView? { get }
  var adChoiceView: UIView? { get }
}

@objc public enum BidMachineNativeAdRenderingAssetType: Int {
  case titleLabel
  case callToActionLabel
  case descriptionLabel
  case iconView
  case mediaContainerView
  case adChoiceView
}

class NativeAdView: UIView, BidMachineNativeAdRendering {
    var titleLabel: UILabel? { titleLab }
    var callToActionLabel: UILabel? { callToActionLab }
    var descriptionLabel: UILabel? { descriptionLab }
    var iconView: UIImageView? { icon }
    var mediaContainerView: UIView? { mediaContainer }
    var adChoiceView: UIView? { nil }
    
    @IBOutlet weak var titleLab: UILabel!
    @IBOutlet weak var descriptionLab: UILabel!
    @IBOutlet weak var icon: UIImageView!
    @IBOutlet weak var mediaContainer: UIView!
    @IBOutlet weak var callToActionLab: UILabel!
}

// Register assets and present
nativeAd.registerAssetsForInteraction([
  BidMachineNativeAdRenderingAssetType.descriptionLabel.rawValue
])

let nativeAdView = NativeAdView()
try nativeAd.presentAd(in: nativeAdView, rendering: nativeAdView)

Mediation​

If the request is involved in third-party mediation, you can use such methods to notify the SDK about the win or loss events:

//Where ad - is loaded bidmachine ad
//Mediation WIN ( ad )
BidMachineSdk.shared.notifyMediationWin(ad)
//Mediation LOSS ( winner, price, ad )
BidMachineSdk.shared.notifyMediationLoss("WINNER_NETWORK", 1.0, ad)