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.
javaCopy
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
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
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
javaCopy
//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;
}
javaCopy
//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
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
Return the bidding success result and pass the bidding-related info to TopOnprice: the bid price for this roundtoken: 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 documentcurrency: the price currency, supports RMB (Chinese yuan), RMB_CENT (Chinese fen), USD (US dollar)
Return the bidding success result and pass the bidding-related info to TopOnNote: 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
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
Return the bidding success result and pass the bidding-related info to TopOnprice: the bid price for this roundtoken: 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 documentcurrency: the price currency, supports RMB (Chinese yuan), RMB_CENT (Chinese fen), USD (US dollar)
Return the bidding success result and pass the bidding-related info to TopOnNote: 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
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 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);
}
}
});
}
javaCopy
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
javaCopy
CustomInterstitialAd customInterstitialAd;
@Override
public boolean isAdReady() {
if (customInterstitialAd != null) {
return customInterstitialAd.isReady();
}
return false;
}
5. Show the Ad
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
javaCopy
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)
javaCopy
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)
javaCopy
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
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()
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()
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)
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
javaCopy
@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;
}
javaCopy
@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;
}
Implement notifying the custom ad network's ad; triggered when there is a current ad impressionisWinner: whether the currently displayed ad is the winnerdisplayPrice: the price of the currently displayed ad Note: the price currency is the ATAdConst.CURRENCY passed in when calling the ATBiddingResult#success() method
Implement notifying the custom ad network's ad; triggered when there is a current ad impressionisWinner: whether the currently displayed ad is the winnerdisplayPrice: the price of the currently displayed ad Note: the price currency is the TUAdConst.CURRENCY passed in when calling the TUBiddingResult#success() method