Banner Ads

Ad Request

Placement

Create placement from AdFormat with your parameters:

Swift

let placement = try? BidMachineSdk.shared.placement(.banner320x50) {
  $0.withPlacementId("")
  $0.withCustomParameters([String:Any]())
}

Objective-C

NSError *error = nil;

BidMachinePlacement *placement = [BidMachineSdk.shared placement:BidMachineAdFormat.banner320x50
                                                           error:&error
                                                         builder:^(id<BidMachinePlacementBuilderProtocol> _Nonnull builder) {
  [builder withPlacementId:@""];
  [builder withCustomParameters:@{}];
}];

Parameter	Type	Description
placementId	String	Placement ID
customParameters	[String: Any] / NSDictionary	Passed directly to the server

AdFormat

The placement format is defined by static properties of the AdFormat class:

Swift

@objc(BidMachineAdFormat)
final public class AdFormat : NSObject {
    @objc public static var banner320x50: BidMachine.AdFormat { get }
    @objc public static var banner728x90: BidMachine.AdFormat { get }
    @objc public static var banner300x250: BidMachine.AdFormat { get }
    @objc public static func bannerAdaptive(width: UInt32, maxHeight: UInt32) -> BidMachine.AdFormat
}

Objective-C

@interface BidMachineAdFormat (SWIFT_EXTENSION(BidMachine))
  + (BidMachineAdFormat * _Nonnull)banner320x50;
  + (BidMachineAdFormat * _Nonnull)banner728x90;
  + (BidMachineAdFormat * _Nonnull)banner300x250;
  + (BidMachineAdFormat * _Nonnull)bannerAdaptiveWithWidth:(uint32_t)width maxHeight:(uint32_t)maxHeight;
@end

Available banner formats

Format	Description
banner320x50	Standard 320×50 banner
banner728x90	Leaderboard 728×90 banner
banner300x250	Medium rectangle 300×250 banner
bannerAdaptive	Adaptive banner with custom width and max height

Adaptive Banner Height

When using bannerAdaptive, the maxHeight parameter defaults to 0 if not specified. A value of 0 acts as a wildcard, allowing the banner to use any height based on the ad content.

Swift

// Adaptive banner with width 320 and wildcard height
let placement = try? BidMachineSdk.shared.placement(.bannerAdaptive(width: 320))

// Or with specific max height
let placement = try? BidMachineSdk.shared.placement(.bannerAdaptive(width: 320, maxHeight: 50))

Objective-C

// Adaptive banner with width 320 and wildcard height
BidMachineAdFormat *format = [BidMachineAdFormat bannerAdaptiveWithWidth:320 maxHeight:0];
BidMachinePlacement *placement = [BidMachineSdk.shared placement:format error:&error builder:nil];

// Or with specific max height
BidMachineAdFormat *format = [BidMachineAdFormat bannerAdaptiveWithWidth:320 maxHeight:50];
BidMachinePlacement *placement = [BidMachineSdk.shared placement:format error:&error builder:nil];

General Request

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

Swift

let request = BidMachineSdk.shared.auctionRequest(placement: placement) {
  $0.withUnitConfigurations([BidMachineUnitConfiguration]())
  $0.appendPriceFloor(Double(10), UUID().uuidString)
}

Objective-C

BidMachineAuctionRequest *request = [[BidMachineSdk shared] auctionRequestWithPlacement:placement 
                                                                                builder:^(id<BidMachineAuctionRequestBuilderProtocol> _Nonnull builder) {
    [builder withUnitConfigurations:@[]];
    [builder appendPriceFloor:10.0 identifier:[[NSUUID UUID] UUIDString]];
}];

Parameter	Type	Description
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:

Swift

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

Objective-C

[BidMachineSdk.shared tokenWithPlacement:placement completion:^(NSString *token) {

}];

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.

Swift

let request = BidMachineSdk.shared.auctionRequest(placement: placement) {
  $0.withPayload("")
}

Objective-C

BidMachineAuctionRequest *request = [[BidMachineSdk shared] auctionRequestWithPlacement:placement 
                                                                              builder:^(id<BidMachineAuctionRequestBuilderProtocol> _Nonnull builder) {
  [builder withPayload:@""];
}];

Parameter	Type	Description
payload	String	Custom BidMachine payload string

Ad Display

The ad object handles downloading and displaying ads.

Prepare the ad object

Request an ad using your auction request:

Swift

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

Objective-C

__weak typeof(self) weakSelf = self;
[[BidMachineSdk shared] bannerWithRequest:request
                              completion:^(BidMachineBanner *ad, NSError * _Nullable error) {
    __strong typeof(weakSelf) strongSelf = weakSelf;
    if (!strongSelf) {
        return;
    }
    strongSelf.banner = ad;
}];

The loaded ad contains 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:

Swift

ad.delegate = self

Objective-C

ad.delegate = self;

Implement BidMachineAdDelegate methods:

Swift

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) {}

Objective-C

- (void)didLoadAd:(id<BidMachineAdProtocol>)ad {}
- (void)didFailLoadAd:(id<BidMachineAdProtocol>)ad :(NSError *)error {}
- (void)didPresentAd:(id<BidMachineAdProtocol>)ad {}
- (void)didFailPresentAd:(id<BidMachineAdProtocol>)ad :(NSError *)error {}
- (void)didDismissAd:(id<BidMachineAdProtocol>)ad {}
- (void)willPresentScreen:(id<BidMachineAdProtocol>)ad {}
- (void)didDismissScreen:(id<BidMachineAdProtocol>)ad {}
- (void)didUserInteraction:(id<BidMachineAdProtocol>)ad {}
- (void)didExpired:(id<BidMachineAdProtocol>)ad {}
- (void)didTrackImpression:(id<BidMachineAdProtocol>)ad {}
- (void)didTrackInteraction:(id<BidMachineAdProtocol>)ad {}
- (void)didReceiveReward:(id<BidMachineAdProtocol>)ad {}

Loading and presenting ads

Loading prerequisites

Make sure both the delegate and controller are set before loading.

Example of banner ad loading:

Swift

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

Objective-C

  NSError *error = nil;
  BidMachinePlacement *placement = [BidMachineSdk.shared placement:BidMachineAdFormat.banner320x50
                                                             error:&error
                                                           builder:nil];
  if (!placement) {
      return;
  }

  BidMachineAuctionRequest *request = [[BidMachineSdk shared] auctionRequestWithPlacement:placement
                                                                                  builder:nil];

  __weak typeof(self) weakSelf = self;
  [[BidMachineSdk shared] bannerWithRequest:request
                                      completion:^(BidMachineBanner *ad, NSError * _Nullable error) {
      __strong typeof(weakSelf) strongSelf = weakSelf;
      if (!strongSelf) {
          return;
      }
      strongSelf.banner = ad;
      ad.controller = strongSelf;
      ad.delegate = strongSelf;
      [ad loadAd];
  }];

Present the banner ad:

Swift

self.view.addSubview(banner)

Objective-C

[self.view addSubview:self.banner];