Customize Client Bidding Network

The article focuses on how to implement Client Bidding with custom Adapter with example of interstitial Ad. For more on Custom Adapter implementation, please refer to Custom Network.

 

1. Customize Adapter

public class CustomSDKInterstitialAdapter extends CustomInterstitialAdapter { 
    ...
}

 

2. Initiate Bidding

• The startBiddingRequest() will be invoked by calling ATInterstitialAd#load().
• Override startBiddingRequest() to initiate Ad bid by calling custom network API in within it.

/**
 * Initiate Client Bidding and return the bidding results through biddingListener
 * Notify the TopOn SDK of the bidding results via biddingListener#onC2SBiddingResultWithCache(ATBiddingResult bidResult, BaseAd baseAd)
 * Note: This method must return true
 * @param serverExtra: custom parameters configured on the server
 * @param localExtra: custom parameters passed in for this load
 * @param biddingListener: bidding result callback
 * @return true
 */
@Override
public boolean startBiddingRequest(final Context context, Map<String, Object> serverExtra, Map<String, Object> localExtra, final ATBiddingListener biddingListener) {

    // Retrieve the custom network placementId configured in the dashboard from serverExtra
    String placementId = (String) serverExtra.get("unit_id");

    CustomSDKInitManager.getInstance().initSDK(context, serverExtra, new MediationInitCallback() {
        @Override
        public void onSuccess() {
            // Initiate a bidding request after the network has been successfully initialized
            ...
        }

        @Override
        public void onFail(String errorMsg) {
            // Through ATBiddingListener, callback the failure of the bid
            if (biddingListener != null) {
                biddingListener.onC2SBiddingResultWithCache(ATBiddingResult.fail(errorMsg), null);
            }
        }
    });
    return true;
}

 

3. Notify the TopOn SDK of Bidding Results

• Ad loading successful: Use the network's API to obtain the returned price and other information, and call ATBiddingListener#onC2SBiddingResultWithCache()to notify the TopOn SDK of a successful bid.
• Ad loading failed: Call ATBiddingListener#onC2SBiddingResultWithCache()to notify the TopOn SDK of a failed bid.

 

● ATBiddingListener

 

● ATBiddingResult

Method	Description
ATBiddingResult success(double price, String token, ATBiddingNotice biddingNotice, ATAdConst.CURRENCY currency)	Return the successful bidding result and pass the bidding-related information to TopOn. price：The bidding price for this instance. token：The cache ID for this bidding ad ATBiddingNotice biddingNotice：An event management class related to ad bidding, can be set to null; refer to the appendix of this document for details. currency：The currency unit for the price, supporting RMB (Renminbi Yuan), RMB_CENT (Renminbi Fen), USD (US Dollar).
ATBiddingResult success(double sortPrice, double price, String token, ATBiddingNotice biddingNotice, ATAdConst.CURRENCY currency)	Return the successful bidding result and pass the bidding-related information to TopOn. Note: sortPrice will affect the sorting of this ad in TopOn's internal waterfall. The higher the sortPrice, the more likely this ad will be prioritized. Unless there are special needs, please use the above method. sortPrice：The sorting price for this ad. Other parameters have the same meanings as above.
ATBiddingResult fail(String errorMsg)	Return the bidding failure result and notify TopOn along with the bidding. errorMsg：Description of the bidding failure.

 

private void startBid(Context context, final ATBiddingListener biddingListener) {
    CustomInterstitialAd customInterstitialAd = new CustomInterstitialAd(placementId);
    customInterstitialAd.load(placementId, new CustomAdLoadListener() {
        @Override
        public void onLoadSuccess() {
            // obtain the price
            double bidPrice = customInterstitialAd.getBidPrice();
            // obtain the unit
            ATAdConst.CURRENCY currency = ATAdConst.CURRENCY.USD;
            if (customInterstitialAd.getCurrency() == "RMB") {
                currency = ATAdConst.CURRENCY.RMB;
            }
            // A unique ID used to identify this bidding instance, which can be a UUID or a timestamp.
            String token = UUID.randomUUID().toString();
            // Bidding result notification
            ATBiddingNotice biddingNotice = new CustomSDKBiddingNotice(customInterstitialAd);

            // Notify the TopOn SDK of the bidding results
            if (biddingListener != null) {
                //Note: onC2SBiddingResultWithCache() for native ads needs to return BaseAd, while other format ads can pass null
                biddingListener.onC2SBiddingResultWithCache(ATBiddingResult.success(bidPrice, token, biddingNotice, currency), null);
            }
        }

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

 

4. Ad is Ready

• When calling ATInterstitialAd#isAdReady(), the customize adapter's isAdReady()will be invoked.
• You need to override the isAdReady(). In this method, call the API of the custom network to return the ad's status.

CustomInterstitialAd customInterstitialAd;

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

 

5. Show Ad

• When calling ATInterstitialAd#show(), the customize adapter'sisAdReady()andshow()will be called in sequence.
• You need to override theshow(). In this method, call the API of the custom network to display the custom ad, and notify the TopOn SDK of ad exposure, clicks, closures, and other events via CustomInterstitialEventListener.

CustomInterstitialAd customInterstitialAd;

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

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

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

 

6. Notify Custom Network of Bidding Results

• By implementing the ATBiddingNotice interface and overriding related methods, you can notify the custom network of bidding win or loss.

 

6.1 Implementing ATBiddingNotice

• Implement the ATBiddingNotice interface to notify the custom network of bidding result events (TopOn SDK decides the moment to trigger the call).

public class CustomSDKBiddingNotice implements ATBiddingNotice {
    CustomInterstitialAd customInterstitialAd;
    protected GDTATBiddingNotice(CustomInterstitialAd customInterstitialAd) {
        this.customInterstitialAd = customInterstitialAd;
    }
}

 

6.2 Notifying Bidding Win

• When this platform's ad lose the bid due to reasons such as cache expiration, trigger the notifyBidLoss().
• Override the notifyBidLoss(). In this method, call the API of the custom network to notify that the bidding fails.

Method	Description
void notifyBidWin(double costPrice, double secondPrice, Map<String, Object> extra)	Implement notification of bidding win to the custom network; this method will be triggered when the ad bidding is successful. costPrice：Winning bidder's price. secondPrice：The price of the second-place bidder (second price). extra: Additional parameters. Note: The currency unit for the price is as provided in ATBiddingResult#success()using ATAdConst.CURRENCY.

@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 of bidding win
    customInterstitialAd.sendWinNotification(map);
    customInterstitialAd = null;
}

 

6.3 Notifying Bidding Loss

• When this platform's ad is deemed to have lost the bid due to reasons such as cache expiration, trigger the notifyBidLoss().
• You need to override the notifyBidLoss(). In this method, call the API of the custom network to notify that the bidding has lost.

Method

Description

void notifyBidLoss(String lossCode, double winPrice, Map<String, Object> extra)

Implement notification of bidding loss to the custom network; this method will be triggered when the ad bidding fails. lossCode：Reason for the failure, refer to the ATAdConst.BIDDING_TYPE class for details below. extra：You can retrieve the winning bidder's channel through Key: ATBiddingNotice.ADN_ID from extra. The enum values for winning channels can be referenced in the ATAdConst.BIDDING_ADN_ID class below. Note: The currency unit for the price is as provided in ATBiddingResult#success() using ATAdConst.CURRENCY.

 

● ATAdConst.BIDDING_TYPE

Reasons for bidding loss

Enum	Description
BIDDING_LOSS_WITH_LOW_PRICE_IN_NORMAL	Lower than the price of regular ads.
BIDDING_LOSS_WITH_LOW_PRICE_IN_HB	Lower than the price of bidding ads.
BIDDING_LOSS_WITH_BIDDING_TIMEOUT	Bidding timeout, such as long periods without bidding result notification to TopOn SDK.
BIDDING_LOSS_WITH_EXPIRE	Ad cache expiration.

 

● ATAdConst.BIDDING_ADN_ID

Winning channel

Enum	Description
LOSE_TO_NORMAL_IN_SAME_ADN	Lost to a regular ad from the same network.
LOSE_TO_HB_IN_SAME_ADN	Lost to a bidding ad from the same network.
LOSE_TO_OWN_ADN	Lost to self-owned ads (direct ads, cross-promotion).
LOSE_TO_OTHER_ADN	Lost to other networks.

 

@Override
public void notifyBidLoss(String lossCode, double winPrice, Map<String, Object> extra) {
    // Reason for bidding loss
    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;
    }
    // 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<String, Object> map = new HashMap<>();
    map.put(CustomSDK.WIN_PRICE, winPrice);
    map.put(CustomSDK.LOSS_REASON, lossReason);
    map.put(CustomSDK.ADN_ID, adnId);
    // Notify of bidding loss
    customInterstitialAd.sendLossNotification(map);
    customInterstitialAd = null;
}

 

6.4 Other API Descriptions

Method	Description
void notifyBidDisplay(boolean isWinner, double displayPrice)	Implement notification to the custom network for the ad; this method will be triggered when the ad is currently exposed.isWinner: Whether the currently exposed ad is the winning bidder. displayPrice: The price of the currently exposed ad. Note: The currency unit for the price is as provided in ATBiddingResult#success()using ATAdConst.CURRENCY.