Menu

Customize Client Bidding Network

This section uses the Interstitial ad as an example to mainly explain how to implement a custom Adapter to integrate Client Bidding. For more custom Adapter implementations, please refer to Custom Adapter

The Client Bidding loading flow is shown in the figure:

1. Inherit the Custom Adapter Class

The Adapter must inherit CustomInterstitialAdapter to implement the Client Bidding feature.

java Copy
public class CustomSDKInterstitialAdapter extends CustomInterstitialAdapter { 
    ...
}

2. Start Bidding

  • When ATInterstitialAd#load() is called, the custom Adapter's startBiddingRequest() method is invoked
  • You need to override startBiddingRequest(). In this method, call the custom ad network's API to start the ad bidding
  • When TUInterstitialAd#load() is called, the custom Adapter's startBiddingRequest() method is invoked
  • You need to override startBiddingRequest(). In this method, call the custom ad network's API to start the ad bidding

2.1 API Reference

Method Description
boolean startBiddingRequest(Context context, Map<String, Object> serverExtra, Map<String, Object> localExtra, ATBiddingListener biddingListener) Start a Client Bidding request and return the bidding result via biddingListener. In this method, start the header bidding request and notify the TopOn SDK of the bidding result via biddingListener#onC2SBiddingResultWithCache(ATBiddingResult bidResult,BaseAd baseAd)
Note: this method must return ture;
context: context
serverExtra: custom parameters configured on the server
localExtra: custom parameters passed in for this load
biddingListener: bidding result callback
Method Description
boolean startBiddingRequest(Context context, Map<String, Object> serverExtra, Map<String, Object> localExtra, TUBiddingListener biddingListener) Start a Client Bidding request and return the bidding result via biddingListener. In this method, start the header bidding request and notify the TopOn SDK of the bidding result via biddingListener#onC2SBiddingResultWithCache(TUBiddingResult bidResult,BaseAd baseAd)
Note: this method must return ture;
context: context
serverExtra: custom parameters configured on the server
localExtra: custom parameters passed in for this load
biddingListener: bidding result callback

2.2 Sample Code

java Copy
//The Ad Placement ID of the custom ad network
String placementId;

@Override
public boolean startBiddingRequest(final Context context, Map<String, Object> serverExtra, Map<String, Object> localExtra, final ATBiddingListener biddingListener) {
    
    //Get the custom network's Ad Placement ID configured on the backend from serverExtra
    placementId = (String) serverExtra.get("unit_id");

    CustomSDKInitManager.getInstance().initSDK(context, serverExtra, new MediationInitCallback() {
        @Override
        public void onSuccess() {
            //Start the bidding request after the ad network initializes successfully
            //...
        }

        @Override
        public void onFail(String errorMsg) {
            //Call back a bidding failure via ATBiddingListener
            if (biddingListener != null) {
                biddingListener.onC2SBiddingResultWithCache(ATBiddingResult.fail(errorMsg), null);
            }
        }
    });
    //Must return true
    return true;
}
java Copy
//The Ad Placement ID of the custom ad network
String placementId;

@Override
public boolean startBiddingRequest(final Context context, Map<String, Object> serverExtra, Map<String, Object> localExtra, final TUBiddingListener biddingListener) {
    
    //Get the custom network's Ad Placement ID configured on the backend from serverExtra
    placementId = (String) serverExtra.get("unit_id");

    CustomSDKInitManager.getInstance().initSDK(context, serverExtra, new MediationInitCallback() {
        @Override
        public void onSuccess() {
            //Start the bidding request after the ad network initializes successfully
            //...
        }

        @Override
        public void onFail(String errorMsg) {
            //Call back a bidding failure via TUBiddingListener
            if (biddingListener != null) {
                biddingListener.onC2SBiddingResultWithCache(TUBiddingResult.fail(errorMsg), null);
            }
        }
    });
    //Must return true
    return true;
}

3. Notify the TopOn SDK of the Bidding Result

  • Ad load succeeds: call the ad network's API to get the returned price, currency, etc., and call the ATBiddingListener#onC2SBiddingResultWithCache() method to notify the TopOn SDK that the bidding succeeded
  • Ad load fails: call the ATBiddingListener#onC2SBiddingResultWithCache() method to notify the TopOn SDK of the bidding failure error info
  • Ad load succeeds: call the ad network's API to get the returned price, currency, etc., and call the TUBiddingListener#onC2SBiddingResultWithCache() method to notify the TopOn SDK that the bidding succeeded
  • Ad load fails: call the TUBiddingListener#onC2SBiddingResultWithCache() method to notify the TopOn SDK of the bidding failure error info

3.1 API Reference

● ATBiddingListener bidding result callback description

Method Description
void onC2SBiddingResultWithCache(ATBiddingResult biddingResult, BaseAd baseAd) Return the bidding result to TopOn after the ad bidding ends
biddingResult: bidding success or failure, refer to the ATBiddingResult description below
baseAd: on bidding success, Native Ad needs to return CustomNativeAd to provide the material info (refer to the Native Ad description and return this object); for other ad formats, just return null; on bidding failure, just return null

● ATBiddingResult bidding result method description

Method Description
ATBiddingResult success(double price, String token, ATBiddingNotice biddingNotice, ATAdConst.CURRENCY currency) Return the bidding success result and pass the bidding-related info to TopOn
price: the bid price for this round
token: the cache ID of the bidding ad for this round
biddingNotice: the ad bidding event management class, may pass null; for details refer to the appendix section of this document
currency: the price currency, supports RMB (Chinese yuan), RMB_CENT (Chinese fen), USD (US dollar)
ATBiddingResult success(double sortPrice, double price, String token, ATBiddingNotice biddingNotice, ATAdConst.CURRENCY currency) Return the bidding success result and pass the bidding-related info to TopOn
Note: sortPrice affects this ad's ranking in TopOn's internal Waterfall; the larger the sortPrice, the more likely this ad is used first. Unless you have special needs, use the method above
sortPrice: the ranking price for this ad
Other parameters have the same meaning as above
ATBiddingResult fail(String errorMsg) Return the bidding failure result to notify TopOn that this Ad Source's bidding failed
errorMsg: bidding failure description

● TUBiddingListener bidding result callback description

Method Description
void onC2SBiddingResultWithCache(TUBiddingResult biddingResult, BaseAd baseAd) Return the bidding result to TopOn after the ad bidding ends
biddingResult: bidding success or failure, refer to the TUBiddingResult description below
baseAd: on bidding success, Native Ad needs to return CustomNativeAd to provide the material info (refer to the Native Ad description and return this object); for other ad formats, just return null; on bidding failure, just return null

● TUBiddingResult bidding result method description

Method Description
TUBiddingResult success(double price, String token, TUBiddingNotice biddingNotice, TUAdConst.CURRENCY currency) Return the bidding success result and pass the bidding-related info to TopOn
price: the bid price for this round
token: the cache ID of the bidding ad for this round
biddingNotice: the ad bidding event management class, may pass null; for details refer to the appendix section of this document
currency: the price currency, supports RMB (Chinese yuan), RMB_CENT (Chinese fen), USD (US dollar)
TUBiddingResult success(double sortPrice, double price, String token, TUBiddingNotice biddingNotice, TUAdConst.CURRENCY currency) Return the bidding success result and pass the bidding-related info to TopOn
Note: sortPrice affects this ad's ranking in TopOn's internal Waterfall; the larger the sortPrice, the more likely this ad is used first. Unless you have special needs, use the method above
sortPrice: the ranking price for this ad
Other parameters have the same meaning as above
TUBiddingResult fail(String errorMsg) Return the bidding failure result to notify TopOn that this Ad Source's bidding failed
errorMsg: bidding failure description

3.2 Sample Code

java Copy
CustomInterstitialAd customInterstitialAd;

private void startBid(Context context, final ATBiddingListener biddingListener) {
    
    customInterstitialAd = new CustomInterstitialAd(placementId);
    
    customInterstitialAd.load(placementId, new CustomAdLoadListener() {

        @Override
        public void onLoadSuccess() {
            //Get the price
            double bidPrice = customInterstitialAd.getBidPrice();
            //Get the currency
            ATAdConst.CURRENCY currency = ATAdConst.CURRENCY.USD;
            if (customInterstitialAd.getCurrency() == "RMB") {
                currency = ATAdConst.CURRENCY.RMB;
            }
            //A unique ID to identify this bidding, you can use a UUID or a timestamp
            String token = UUID.randomUUID().toString();
            //The ad bidding event management class, may pass null
            ATBiddingNotice biddingNotice = new CustomSDKBiddingNotice(customInterstitialAd);

            //Notify the TopOn SDK of the bidding result
            if (biddingListener != null) {
                //Note: for onC2SBiddingResultWithCache(ATBiddingResult biddingResult, BaseAd baseAd), Native Ad needs to return BaseAd, other ad formats may pass null
                biddingListener.onC2SBiddingResultWithCache(ATBiddingResult.success(bidPrice, token, biddingNotice, currency), null);
            }
        }

        @Override
        public void onLoadFailed(String errorMsg) {
            //Notify the TopOn SDK of the bidding result
            if (biddingListener != null) {
                biddingListener.onC2SBiddingResultWithCache(ATBiddingResult.fail(errorMsg), null);
            }
        }
    });
}
java Copy
CustomInterstitialAd customInterstitialAd;

private void startBid(Context context, final TUBiddingListener biddingListener) {
    
    customInterstitialAd = new CustomInterstitialAd(placementId);
    
    customInterstitialAd.load(placementId, new CustomAdLoadListener() {

        @Override
        public void onLoadSuccess() {
            //Get the price
            double bidPrice = customInterstitialAd.getBidPrice();
            //Get the currency
            TUAdConst.CURRENCY currency = TUBiddingResult.CURRENCY.USD;
            if (customInterstitialAd.getCurrency() == "RMB") {
                currency = TUBiddingResult.CURRENCY.RMB;
            }
            //A unique ID to identify this bidding, you can use a UUID or a timestamp
            String token = UUID.randomUUID().toString();
            //The ad bidding event management class, may pass null
            TUBiddingNotice biddingNotice = new CustomSDKBiddingNotice(customInterstitialAd);

            //Notify the TopOn SDK of the bidding result
            if (biddingListener != null) {
                //Note: for onC2SBiddingResultWithCache(TUBiddingResult biddingResult, BaseAd baseAd), Native Ad needs to return BaseAd, other ad formats may pass null
                biddingListener.onC2SBiddingResultWithCache(TUBiddingResult.success(bidPrice, token, biddingNotice, currency), null);
            }
        }

        @Override
        public void onLoadFailed(String errorMsg) {
            //Notify the TopOn SDK of the bidding result
            if (biddingListener != null) {
                biddingListener.onC2SBiddingResultWithCache(TUBiddingResult.fail(errorMsg), null);
            }
        }
    });
}

4. Determine Whether the Ad Is Ready

  • When ATInterstitialAd#isAdReady() is called, the custom Adapter's isAdReady() method is invoked
  • You need to override the isAdReady() method. In this method, call the custom ad network's API and return the ad's status
  • When TUInterstitialAd#isAdReady() is called, the custom Adapter's isAdReady() method is invoked
  • You need to override the isAdReady() method. In this method, call the custom ad network's API and return the ad's status

4.1 API Reference

Method Description
boolean isAdReady() Used to determine whether the ad is in the ready state

4.2 Sample Code

java Copy
CustomInterstitialAd customInterstitialAd;

@Override
public boolean isAdReady() {
    if (customInterstitialAd != null) {
        return customInterstitialAd.isReady();
    }
    return false;
}

  • When ATInterstitialAd#show() is called, the custom Adapter's isAdReady() and show() are invoked in turn
  • You need to override the show() method. In this method, call the custom ad network's API to display the custom ad, and notify the TopOn SDK of events such as ad impression, click, and close via CustomInterstitialEventListener
  • When TUInterstitialAd#show() is called, the custom Adapter's isAdReady() and show() are invoked in turn
  • You need to override the show() method. In this method, call the custom ad network's API to display the custom ad, and notify the TopOn SDK of events such as ad impression, click, and close via CustomInterstitialEventListener

5.1 API Reference

Method Description
void show(......) Implement the ad display logic the parameters depend on the ad format

5.2 Sample Code

java Copy
CustomInterstitialAd customInterstitialAd;

@Override
public void show(Activity activity) {
    if (customInterstitialAd != null) {
        customInterstitialAd.setEventListener(new CustomAdEventListener() {
            @Override
            public void onAdImpression() {
                //Notify the TopOn SDK that the ad impression succeeded
                if (mImpressListener != null) {
                    mImpressListener.onInterstitialAdShow();
                }
            }

            @Override
            public void onADClicked() {
                //Notify the TopOn SDK that the ad was clicked
                if (mImpressListener != null) {
                    mImpressListener.onInterstitialAdClicked();
                }
            }

            @Override
            public void onADClicked() {
                //Notify the TopOn SDK that the ad was closed
                if (mImpressListener != null) {
                    mImpressListener.onInterstitialAdClose();
                }
            }
        });
        //Trigger the ad display
        customInterstitialAd.show(activity);
    }
}

6. Implement BiddingNotice to Notify the Custom Network of the Bidding Result

By implementing the ATBiddingNotice interface and overriding the related methods, you can notify the custom ad network of bid win or bid loss events

By implementing the TUBiddingNotice interface and overriding the related methods, you can notify the custom ad network of bid win or bid loss events

6.1 Implement BiddingNotice

Implement the ATBiddingNotice interface to notify the custom ad network of bidding result events (the exact sending time is determined by the TopOn SDK)

java Copy
public class CustomSDKBiddingNotice implements ATBiddingNotice {
    //The ad object of the custom ad network
    CustomInterstitialAd customInterstitialAd;
    protected GDTATBiddingNotice(CustomInterstitialAd customInterstitialAd) {
        this.customInterstitialAd = customInterstitialAd;
    }
}

By implementing the TUBiddingNotice interface and overriding the related methods, you can notify the custom ad network of bidding result events (the exact sending time is determined by the TopOn SDK)

java Copy
public class CustomSDKBiddingNotice implements TUBiddingNotice {
    //The ad object of the custom ad network
    CustomInterstitialAd customInterstitialAd;
    protected GDTTUBiddingNotice(CustomInterstitialAd customInterstitialAd) {
        this.customInterstitialAd = customInterstitialAd;
    }
}

6.2 Notify Bid Win

  • When this network's ad is the highest price in this load, the notifyBidWin() method is triggered
  • You need to override the notifyBidWin() method. In this method, call the custom ad network's API to notify the ad network that it won the bid

6.2.1 API Reference

Method Description
void notifyBidWin(double costPrice, double secondPrice, Map<String, Object> extra) Implement notifying the custom ad network of a bid win; this method is triggered when this ad wins the bid
costPrice: the winner's price
secondPrice: the price of the runner-up after the winner (second price)
extra: extra parameters
Note: the price currency is the ATAdConst.CURRENCY passed in when calling ATBiddingResult#success()
Method Description
void notifyBidWin(double costPrice, double secondPrice, Map<String, Object> extra) Implement notifying the custom ad network of a bid win; this method is triggered when this ad wins the bid
costPrice: the winner's price
secondPrice: the price of the runner-up after the winner (second price)
extra: extra parameters
Note: the price currency is the TUAdConst.CURRENCY passed in when calling TUBiddingResult#success()

6.2.2 Sample Code

java Copy
@Override
public void notifyBidWin(double costPrice, double secondPrice, Map<String, Object> extra) {
    Map<String, Object> map = new HashMap<>();
    map.put(CustomSDK.COST_PRICE, costPrice);
    map.put(CustomSDK.HIGHEST_LOSS_PRICE, secondPrice);
    //Notify bid win
    customInterstitialAd.sendWinNotification(map);
    customInterstitialAd = null;
}

6.3 Notify Bid Loss

  • When TopOn considers this network's ad as a bid loss due to reasons such as cache expiration, the notifyBidLoss() method is triggered
  • You need to override the notifyBidLoss() method. In this method, call the custom ad network's API to notify the ad network that it lost the bid

6.3.1 API Reference

Method Description
void notifyBidLoss(String lossCode, double winPrice, Map<String, Object> extra) Implement notifying the custom ad network of a bid loss; this method is triggered when this ad loses the bid
lossCode: the failure reason, refer to the ATAdConst.BIDDING_TYPE class, see the description below
extra: you can get the winner's channel from extra via Key: ATBiddingNotice.ADN_ID; for the enum values of the winner's channel, refer to the ATAdConst.BIDDING_ADN_ID class, see the description below
Note: the price currency is the ATAdConst.CURRENCY passed in when calling the ATBiddingResult#success() method

● ATAdConst.BIDDING_TYPE: bid loss reason

Enum Description
BIDDING_LOSS_WITH_LOW_PRICE_IN_NORMAL Lower than the price of a normal regular ad
BIDDING_LOSS_WITH_LOW_PRICE_IN_HB Lower than the price of a bidding ad
BIDDING_LOSS_WITH_BIDDING_TIMEOUT Bidding timed out, e.g. no bidding result was notified to the TopOn SDK for a long time
BIDDING_LOSS_WITH_EXPIRE Ad cache expired

● ATAdConst.BIDDING_ADN_ID: winner's channel

Enum Description
LOSE_TO_NORMAL_IN_SAME_ADN Lost to a normal regular ad of the same ad network
LOSE_TO_HB_IN_SAME_ADN Lost to a bidding ad of the same ad network
LOSE_TO_OWN_ADN Lost to an owned ad (direct-sold ad, cross-promotion)
LOSE_TO_OTHER_ADN Lost to another ad network
Method Description
void notifyBidLoss(String lossCode, double winPrice, Map<String, Object> extra) Implement notifying the custom ad network of a bid loss; this method is triggered when this ad loses the bid
lossCode: the failure reason, refer to the TUAdConst.BIDDING_TYPE class, see the description below
extra: you can get the winner's channel from extra via Key: TUBiddingNotice.ADN_ID; for the enum values of the winner's channel, refer to the TUAdConst.BIDDING_ADN_ID class, see the description below
Note: the price currency is the TUAdConst.CURRENCY passed in when calling the TUBiddingResult#success() method

● TUAdConst.BIDDING_TYPE: bid loss reason

Enum Description
BIDDING_LOSS_WITH_LOW_PRICE_IN_NORMAL Lower than the price of a normal regular ad
BIDDING_LOSS_WITH_LOW_PRICE_IN_HB Lower than the price of a bidding ad
BIDDING_LOSS_WITH_BIDDING_TIMEOUT Bidding timed out, e.g. no bidding result was notified to the TopOn SDK for a long time
BIDDING_LOSS_WITH_EXPIRE Ad cache expired

● TUAdConst.BIDDING_ADN_ID: winner's channel

Enum Description
LOSE_TO_NORMAL_IN_SAME_ADN Lost to a normal regular ad of the same ad network
LOSE_TO_HB_IN_SAME_ADN Lost to a bidding ad of the same ad network
LOSE_TO_OWN_ADN Lost to an owned ad (direct-sold ad, cross-promotion)
LOSE_TO_OTHER_ADN Lost to another ad network

6.3.2 Sample Code

java Copy
@Override
public void notifyBidLoss(String lossCode, double winPrice, Map<String, Object> extra) {
    //Determine the bid loss reason
    int lossReason = CustomSDKLossReason.OTHER;
    switch (lossCode) {
        case ATAdConst.BIDDING_TYPE.BIDDING_LOSS_WITH_BIDDING_TIMEOUT:
            lossReason = CustomSDKLossReason.NO_AD;
            break;
        case ATAdConst.BIDDING_TYPE.BIDDING_LOSS_WITH_LOW_PRICE_IN_HB:
        case ATAdConst.BIDDING_TYPE.BIDDING_LOSS_WITH_LOW_PRICE_IN_NORMAL:
            lossReason = CustomSDKLossReason.LOW_PRICE;
            break;
    }
    //Determine the winner's channel
    int adnId = ATInitMediation.getIntFromMap(extra, ATBiddingNotice.ADN_ID, -1);
    switch (adnId) {
        case ATAdConst.BIDDING_ADN_ID.LOSE_TO_NORMAL_IN_SAME_ADN:
            adnId = CustomSDKADNID.NORMAL;
            break;
        case ATAdConst.BIDDING_ADN_ID.LOSE_TO_HB_IN_SAME_ADN:
            adnId = CustomSDKADNID.HB;
            break;
        case ATAdConst.BIDDING_ADN_ID.LOSE_TO_OWN_ADN:
            adnId = CustomSDKADNID.OWN_AD;
            break;
        case ATAdConst.BIDDING_ADN_ID.LOSE_TO_OTHER_ADN:
            adnId = CustomSDKADNID.OTHER;
            break;
    }
    Map<String, Object> map = new HashMap<>();
    map.put(CustomSDK.WIN_PRICE, winPrice);
    map.put(CustomSDK.LOSS_REASON, lossReason);
    map.put(CustomSDK.ADN_ID, adnId);
    //Notify bid loss
    customInterstitialAd.sendLossNotification(map);
    customInterstitialAd = null;
}
java Copy
@Override
public void notifyBidLoss(String lossCode, double winPrice, Map<String, Object> extra) {
    //Determine the bid loss reason
    int lossReason = CustomSDKLossReason.OTHER;
    switch (lossCode) {
        case TUAdConst.BIDDING_TYPE.BIDDING_LOSS_WITH_BIDDING_TIMEOUT:
            lossReason = CustomSDKLossReason.NO_AD;
            break;
        case TUAdConst.BIDDING_TYPE.BIDDING_LOSS_WITH_LOW_PRICE_IN_HB:
        case TUAdConst.BIDDING_TYPE.BIDDING_LOSS_WITH_LOW_PRICE_IN_NORMAL:
            lossReason = CustomSDKLossReason.LOW_PRICE;
            break;
    }
    //Determine the winner's channel
    int adnId = TUInitMediation.getIntFromMap(extra, TUBiddingNotice.ADN_ID, -1);
    switch (adnId) {
        case TUAdConst.BIDDING_ADN_ID.LOSE_TO_NORMAL_IN_SAME_ADN:
            adnId = CustomSDKADNID.NORMAL;
            break;
        case TUAdConst.BIDDING_ADN_ID.LOSE_TO_HB_IN_SAME_ADN:
            adnId = CustomSDKADNID.HB;
            break;
        case TUAdConst.BIDDING_ADN_ID.LOSE_TO_OWN_ADN:
            adnId = CustomSDKADNID.OWN_AD;
            break;
        case TUAdConst.BIDDING_ADN_ID.LOSE_TO_OTHER_ADN:
            adnId = CustomSDKADNID.OTHER;
            break;
    }
    Map<String, Object> map = new HashMap<>();
    map.put(CustomSDK.WIN_PRICE, winPrice);
    map.put(CustomSDK.LOSS_REASON, lossReason);
    map.put(CustomSDK.ADN_ID, adnId);
    //Notify bid loss
    customInterstitialAd.sendLossNotification(map);
    customInterstitialAd = null;
}

6.4 Other API Reference

Method Description
void notifyBidDisplay(boolean isWinner, double displayPrice) Implement notifying the custom ad network's ad; triggered when there is a current ad impression
isWinner: whether the currently displayed ad is the winner
displayPrice: the price of the currently displayed ad
Note: the price currency is the ATAdConst.CURRENCY passed in when calling the ATBiddingResult#success() method
Method Description
void notifyBidDisplay(boolean isWinner, double displayPrice) Implement notifying the custom ad network's ad; triggered when there is a current ad impression
isWinner: whether the currently displayed ad is the winner
displayPrice: the price of the currently displayed ad
Note: the price currency is the TUAdConst.CURRENCY passed in when calling the TUBiddingResult#success() method
Previous
Splash Ads
Next
AdMob Content mapping for apps
Last modified: 2026-07-08Powered by