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:
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
javaCopy
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
javaCopy
// 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
javaCopy
...
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
javaCopy
...
CustomInterstitialAd customInterstitialAd;
@Override
public boolean isAdReady() {
if (customInterstitialAd != null) {
return customInterstitialAd.isReady();
}
return false;
}
5. Display the Ad
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
javaCopy
...
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.
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
javaCopy
@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.