Menu

Custom Client Bidding Ad

This document mainly describes how to integrate Client Bidding with a custom Adapter. For more custom Adapter implementations, please refer to this document: Custom Adapter.

The Client Bidding loading flow is shown below:

Article Image

1. Inherit the Custom Adapter Class

  • Taking Interstitial Ad as an example, developers need to inherit CustomInterstitialAdapter to implement the Client Bidding feature.

1.1 Sample Code

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

2. Initiate Bidding

  • When the developer calls the load() API of ATInterstitialAd, the custom Adapter's startBiddingRequest() method will be called.
  • Developers need to override startBiddingRequest(). In this method, call the custom ad platform's API to initiate ad bidding.

2.1 API Description

Abstract Method Parameter Description Return Value Purpose Description
startBiddingRequest Context applicationContext: Context Map boolean Initiate a Client Bidding request and return the bidding result through biddingListener. In this method, initiate the header bidding request and notify the Taku SDK of the bidding result through biddingListener's onC2SBiddingResultWithCache(ATBiddingResult bidResult,BaseAd baseAd) method. Note: This method must return true.

2.2 Sample Code

java Copy
// Custom ad platform's ad placement ID
String placementId;

@Override
public boolean startBiddingRequest(final Context context, Map serverExtra, Map localExtra, final ATBiddingListener biddingListener) {

    // Get the custom platform's ad placement ID configured in the dashboard from serverExtra.
    placementId = (String) serverExtra.get("unit_id");

    CustomSDKInitManager.getInstance().initSDK(context, serverExtra, new MediationInitCallback() {
        @Override
        public void onSuccess() {

            // Initiate bidding request after the ad platform Initialization succeeds.
            startBid(context, biddingListener);

        }

        @Override
        public void onFail(String errorMsg) {

            // Callback bidding failure through ATBiddingListener.
            if (biddingListener != null) {
            	biddingListener.onC2SBiddingResultWithCache(ATBiddingResult.fail(errorMsg), null);
            }
        }
    });

    // Must return true.
    return true;
} 

3. Notify Taku SDK of the Bidding Result

  • Ad load success: Call the ad platform's API to obtain the returned price, currency unit, etc., and call the onC2SBiddingResultWithCache() method through ATBiddingListener to notify the Taku SDK that the bidding was successful.
  • Ad load failure: Call the onC2SBiddingResultWithCache() method through ATBiddingListener to notify the Taku SDK of the bidding failure error info.

3.1 API Description

ATBiddingListener Bidding Result Callback Description

Callback Method Parameter Description Description
onC2SBiddingResultWithCache (ATBiddingResult biddingResult, BaseAd baseAd) Return the bidding result to Taku after the ad bidding ends. biddingResult: Bidding success or failure. See the ATBiddingResult description below. baseAd: On bidding success, Native Ads need to return CustomNativeAd to provide creative info (please refer to Native Ad instructions for returning this object). Other ad formats can return null. On bidding failure, return null.

ATBiddingResult Bidding Result Method Description

Method Parameter Description Return Value Purpose
success double price: The bid price for this time String cacheId: The cache ID of this bidding ad ATBiddingNotice biddingNotice: Ad bidding related event management class. Can be passed as null. For details, refer to the appendix section of this document. ATAdConst.CURRENCY currency: Price currency unit. Supports RMB (CNY), RMB_CENT (CNY cents), USD (US dollars). ATBiddingResult Return a bidding success result and pass the bidding related information to Taku.
success double sortPrice: The sorting price for this ad. Other parameters have the same meaning as above. ATBiddingResult Same purpose as above. Note: sortPrice affects the ranking of this ad within Taku's internal WaterFall. The larger the sortPrice, the more likely this ad will be prioritized. If there is no special need, please use the above method.
fail String errorMsg: Bidding failure description. ATBiddingResult Return a bidding failure result and notify Taku that this Ad Source has failed to bid.

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 price
    		double bidPrice = customInterstitialAd.getBidPrice();
    		
    		// Get currency unit
    		ATAdConst.CURRENCY currency = ATAdConst.CURRENCY.USD;
    		if (customInterstitialAd.getCurrency() == "RMB") {
    			currency = ATAdConst.CURRENCY.RMB;
    		}
    		
    		// A unique ID used to identify this bidding. UUID or timestamp can be used.
    		String token = UUID.randomUUID().toString();
    		
    		// Ad bidding related event management class. Can be passed as null.
    		ATBiddingNotice biddingNotice = new CustomSDKBiddingNotice(customInterstitialAd);
    		
    		// Native Ads need to return BaseAd. Other ad formats can pass null.
    		BaseAd basead = null;
    		
    		// Notify Taku SDK of the bidding result.
    		if (biddingListener != null) {
            	biddingListener.onC2SBiddingResultWithCache(
                    ATBiddingResult.success(bidPrice, token, biddingNotice, currency), basead
                );
            }
	
    	}
    		
    	@Override
    	public void onLoadFailed(String errorMsg) {
    		// Notify Taku SDK of the bidding result.
            if (biddingListener != null) {
            	biddingListener.onC2SBiddingResultWithCache(ATBiddingResult.fail(errorMsg), null);
            }
    	}
    	
   });
    
}

4. Check Whether the Ad is Ready

  • When the developer calls the isAdReady() API of ATInterstitialAd, the custom Adapter's isAdReady() method will be called.
  • Developers need to override the isAdReady() method. In this method, call the custom ad platform's API to return the ad's status.

4.1 API Description

Abstract Method Parameter Description Return Value Purpose Description
isAdReady - boolean Used to determine whether the custom ad platform's Interstitial Ad is in a ready state. Used to determine whether the ad is in a ready state.

4.2 Sample Code

java Copy
...
CustomInterstitialAd customInterstitialAd;

@Override
public boolean isAdReady() {
    if (customInterstitialAd != null) {
        return customInterstitialAd.isReady();
    }
    return false;
}
  • When the developer calls the show() API of ATInterstitialAd, the custom Adapter's isAdReady() and show() methods will be called in sequence.
  • Developers need to override the show() method. In this method, call the custom ad platform's API to display the custom ad. Notify the Taku SDK of ad impression, click, close, and other events through CustomInterstitialEventListener.

5.1 API Description

Abstract Method Parameter Description Return Value Purpose Description
show Depends on the ad format. void Implement the logic for displaying the custom ad platform's ad. Implement the ad display logic.

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 Taku SDK that the ad impression was successful.
                if (mImpressListener != null) {
                    mImpressListener.onInterstitialAdShow();
                }
            }
            
            @Override
            public void onADClicked() {
                // Notify Taku SDK that the ad was clicked.
                if (mImpressListener != null) {
                    mImpressListener.onInterstitialAdClicked();
                }
            }
            
            @Override
            public void onADClicked() {
                // Notify Taku SDK that the ad was closed.
                if (mImpressListener != null) {
                    mImpressListener.onInterstitialAdClose();
                }
            }
            
        });
        
        // Trigger ad display.
        customInterstitialAd.show(activity);
    }
}

Appendix: Implement ATBiddingNotice to Notify the Custom Platform of Bidding Results

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

1. Implement ATBiddingNotice

  • Taking Interstitial Ad as an example, developers can choose to implement the ATBiddingNotice interface to notify the custom ad platform of bidding result events (the specific sending timing is determined by the Taku SDK).

1.1 Sample Code

Copy
public class CustomSDKBiddingNotice implements ATBiddingNotice {

	// Custom ad platform's ad object
	CustomInterstitialAd customInterstitialAd;

    protected GDTATBiddingNotice(CustomInterstitialAd customInterstitialAd) {
        this.customInterstitialAd = customInterstitialAd;
    }

}

2. Notify Bid Win

  • When this platform's ad is the highest priced in this load, the notifyBidWin() method is triggered.
  • Developers need to override the notifyBidWin() method. In this method, call the custom ad platform's API to notify the ad platform that the bid has won.

2.1 API Description

Abstract Method Parameter Description Return Value Purpose Required Description
notifyBidWin double costPrice: The winning bid price double secondPrice: The price of the first losing bidder Map Map void Implement notification to the custom ad platform that the ad bid has won. Yes This method is triggered when this ad's bidding succeeds. costPrice parameter: The winning party's price. secondPrice parameter: The price of the party ranked after the winning party (second price). Note: The currency unit of the price is the ATAdConst.CURRENCY passed by the developer when calling the ATBiddingResult.success() method.

2.2 Sample Code

java Copy
@Override
public void notifyBidWin(double costPrice, double secondPrice, Map extra) {
    
    Map map = new HashMap<>();

    map.put(CustomSDK.COST_PRICE, costPrice);
    map.put(CustomSDK.HIGHEST_LOSS_PRICE, secondPrice);

    // Notify bid win.
    customInterstitialAd.sendWinNotification(map);

    customInterstitialAd = null;
}

3. Notify Bid Loss

  • When this platform's ad is considered to have lost the bid by Taku due to reasons such as cache expiration, the notifyBidLoss() method is triggered.
  • Developers need to override the notifyBidLoss() method. In this method, call the custom ad platform's API to notify the ad platform that the bid has lost.

3.1 API Description

Abstract Method Parameter Description Return Value Purpose Required Description
notifyBidLoss String lossCode: Bid loss code double winPrice: The winning bid price Map Map void Implement notification to the custom ad platform that the ad bid has lost. Yes This method is triggered when this ad's bidding fails. lossCode parameter: Failure reason. Refer to the ATAdConst.BIDDING_TYPE class. See the description below. extra parameter: You can use Key: ATBiddingNotice.ADN_ID to obtain the winning channel from extra. For the enumeration value of the winning channel, refer to the ATAdConst.BIDDING_ADN_ID class. See the description below. Note: The currency unit of the price is the ATAdConst.CURRENCY passed by the developer when calling the ATBiddingResult.success() method.

ATAdConst.BIDDING_TYPE: Bid Loss Reasons

Enum Description
BIDDING_LOSS_WITH_LOW_PRICE_IN_NORMAL Price is lower than regular non-bidding ads.
BIDDING_LOSS_WITH_LOW_PRICE_IN_HB Price is lower than other bidding ads.
BIDDING_LOSS_WITH_BIDDING_TIMEOUT Bidding timed out, e.g., no bidding result was notified to Taku SDK for a long time.
BIDDING_LOSS_WITH_EXPIRE Ad cache expired.

ATAdConst.BIDDING_ADN_ID: Winning Channel

Enum Description
LOSE_TO_NORMAL_IN_SAME_ADN Lost to a regular non-bidding ad from the same ad platform.
LOSE_TO_HB_IN_SAME_ADN Lost to a bidding ad from the same ad platform.
LOSE_TO_OWN_ADN Lost to an owned ad (Direct Ad, Cross-Promotion).
LOSE_TO_OTHER_ADN Lost to another ad platform.

3.2 Sample Code

java Copy
@Override
public void notifyBidLoss(String lossCode, double winPrice, Map 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 winning 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 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;
}

4. Other API Description

Abstract Method Parameter Description Return Value Purpose Required Description
notifyBidDisplay boolean isWinner: Whether it is the winning party double displayPrice: The price of the ad currently being impressed. void Implement notification to the custom ad platform's ad that an ad is currently being impressed. Yes This method is triggered when an ad impression occurs. isWinner parameter: Whether the ad currently being impressed is the winning party. displayPrice: The price of the ad currently being impressed. Note: The currency unit of the price is the ATAdConst.CURRENCY passed by the developer when calling the ATBiddingResult.success() method.
Previous
Banner Ad
Next
Interstitial Ad
Last modified: 2026-07-08Powered by