Banner / MREC Ads

Ad Request

Placement

Create a placement configuration using AdPlacementConfig.BannerBuilder() with a BannerAdSize, optional placement id, and custom parameters.

var config = AdPlacementConfig.BannerBuilder(BannerAdSize.Banner)
    .WithPlacementId("your_placement_id") // Optional placement id
    .WithCustomParams(customParams)       // Optional custom parameters
    .Build();

BannerAdSize

BannerAdSize is a required parameter for banner placement:

Type	Size	Description
BannerAdSize.Banner	320×50	Standard banner size
BannerAdSize.Leaderboard	728×90	Leaderboard banner size for tablets
BannerAdSize.MediumRectangle	300×250	Medium rectangle (MREC) banner

Adaptive Banners

You can create adaptive banners with a custom width and maximum height:

// Adaptive banner with width 350 and max height 100
var adaptiveSize = BannerAdSize.Adaptive(350, 100);

var config = AdPlacementConfig.BannerBuilder(adaptiveSize)
    .WithPlacementId("your_placement_id")
    .Build();

// Check if banner is adaptive
if (adaptiveSize.IsAdaptive)
{
    // Handle responsive rendering
}

Calculating Adaptive Height

Use BannerAdSize.GetMaxAdaptiveHeight(width) to get the maximum expected banner height for a given width:

int maxHeight = BannerAdSize.GetMaxAdaptiveHeight(screenWidthDp);
var adaptiveSize = BannerAdSize.Adaptive(screenWidthDp, maxHeight);

Build the Request

Create a BannerRequest.Builder with the placement config, set optional targeting and price floor parameters, attach an IAdAuctionRequestListener, and call Build(). Building the request triggers the auction.

var bannerRequest = (IBannerRequest)new BannerRequest.Builder(config)
    .SetPriceFloorParams(priceFloorParams)   // Optional price floor parameters
    .SetTargetingParams(targetingParams)     // Optional targeting parameters
    .SetLoadingTimeOut(10000)                // Optional timeout in milliseconds
    .SetListener(bannerRequestListener)      // Auction request listener
    .Build();

Auction Request Listener

Implement IAdAuctionRequestListener to receive auction callbacks:

private class BannerRequestListener : IAdAuctionRequestListener
{
    public void onRequestSuccess(IAdRequest request, AuctionResult auctionResult)
    {
        Debug.Log("BannerRequest succeeded");
    }

    public void onRequestFailed(IAdRequest request, BMError error)
    {
        Debug.Log($"BannerRequest failed: {error.Message}");
    }

    public void onRequestExpired(IAdRequest request)
    {
        Debug.Log("BannerRequest expired");
    }
}

Client Bidding Request

For server-to-server (S2S) integration, pass the Base64-encoded bid payload received from your server-side auction to the builder:

var bannerRequest = (IBannerRequest)new BannerRequest.Builder(config)
    .SetBidPayload(bidPayloadString)
    .SetListener(bannerRequestListener)
    .Build();

Ad Display

Define Ad Listener

Before loading, create a BannerView and set an IAdListener<IBannerView> listener:

var bannerView = new BannerView();
bannerView.SetListener(bannerListener);
bannerView.Load(bannerRequest);

Implement the listener to handle ad lifecycle events:

private class BannerListener : IAdListener<IBannerView>
{
    public void onAdLoaded(IBannerView ad)
    {
        // Ad is loaded and ready to be displayed
    }

    public void onAdLoadFailed(IBannerView ad, BMError error)
    {
        // Ad failed to load
    }

    public void onAdShown(IBannerView ad)
    {
        // Ad has been shown
    }

    public void onAdShowFailed(IBannerView ad, BMError error)
    {
        // Ad failed to show
    }

    public void onAdImpression(IBannerView ad)
    {
        // Ad impression has been tracked
    }

    public void onAdExpired(IBannerView ad)
    {
        // Ad has expired
    }
}

Show the Banner

Use onAdLoaded to determine when the ad is ready. Before displaying, check CanShow():

if (bannerView.CanShow())
{
    var size = bannerRequest.GetBannerAdSize();
    bannerView.Show(
        BidMachine.BannerVerticalBottom,
        BidMachine.BannerHorizontalCenter,
        bannerView,
        size
    );
}

Banner Position Constants

Use the following constants to control banner placement on screen:

Horizontal	Vertical
BidMachine.BannerHorizontalCenter	BidMachine.BannerVerticalCenter
BidMachine.BannerHorizontalLeft	BidMachine.BannerVerticalTop
BidMachine.BannerHorizontalRight	BidMachine.BannerVerticalBottom

Get Loaded Ad Size

Read the actual creative size in onAdLoaded:

public void onAdLoaded(IBannerView ad)
{
    BannerAdSize loadedSize = ad.GetAdSize();
    int width = loadedSize.Width;
    int height = loadedSize.Height;
}

Hide the Banner

To temporarily hide the banner without destroying it:

bannerView.Hide();

Destroy the Banner

When the ad is no longer needed, clean up resources:

bannerView.SetListener(null);
bannerView.Destroy();
bannerView = null;
bannerRequest = null;

warning

Don't destroy the BannerRequest if it will be used to load a BannerView, or if the loaded BannerView has not been shown yet. Premature destruction can affect display rate, fill rate, and revenue.