Custom Client Bidding Network

This document mainly introduces how to customize the Adapter to integrate Client Bidding. For more customized Adapter implementation, please refer to this document Customized advertising platform

Client Bidding loading process is as shown in the figure:

1. Inherited from Define the Adapter class

• Take interstitial advertising as an example. Developers need to inherit CustomInterstitialAdapter to implement the Client Bidding function.

1.1 Sample Code

public class CustomSDKInterstitialAdapter extends CustomInterstitialAdapter { 
    ...
}

2. Initiate a bid

2.1 API Description

2.2 Sample Code

//Custom advertising platform's placementId
String placementId;

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

    //Obtain the placementId of the custom platform configured in the background from serverExtra
    placementId = (String) serverExtra.get("unit_id");

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

            //Initiate bidding request after successful initialization of advertising platform
            startBid(context, biddingListener);

        }

        @Override
        public void onFail(String errorMsg) {

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

    //Must return true
    return true;
} 

3. Notify TopOn SDK of bidding results

• Ad loading is successful: call the API of the advertising platform to obtain the returned price, currency unit, etc., and call onC2SBiddingResultWithCache through ATBiddingListener () method to notify TopOn SDK of successful bidding
• Ad loading failure: the onC2SBiddingResultWithCache() method needs to be called through ATBiddingListener to notify TopOn SDK of the error message of failed bidding

3.1 API Description

ATBiddingListener bidding result callback description

ATBiddingResult bidding result method description

3.2 Sample Code

...

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();
    		
    		//Obtain currency units
    		ATAdConst.CURRENCY currency = ATAdConst.CURRENCY.USD;
    		if (customInterstitialAd.getCurrency() == "RMB") {
    			currency = ATAdConst.CURRENCY.RMB;
    		}
    		
    		//The unique ID used to identify this bidding can be UUID or timestamp
    		String token = UUID.randomUUID().toString();
    		
    		//Advertising bidding related event management class, can pass null
    		ATBiddingNotice biddingNotice = new CustomSDKBiddingNotice(customInterstitialAd);
    		
    		//Native advertising requires BaseAd to be returned, while other forms of advertising can pass null
    		BaseAd basead = null;
    		
    		//Notify TopOn SDK of bidding results
    		if (biddingListener != null) {
            	biddingListener.onC2SBiddingResultWithCache(
                    ATBiddingResult.success(bidPrice, token, biddingNotice, currency), basead
                );
            }
	
    	}
    		
    	@Override
    	public void onLoadFailed(String errorMsg) {
    		//Notify TopOn SDK of bidding results
            if (biddingListener != null) {
            	biddingListener.onC2SBiddingResultWithCache(ATBiddingResult.fail(errorMsg), null);
            }
    	}
    	
   });
    
}

4. Determine if the advertisement is ready

• When developers call the isAdReady() API of ATInterstialAd, they will call the isAdReady() method of the custom adapter
• The developer needs to rewrite the isAdReady() method. In this method, call the API of the customized advertising platform to return the status of the advertisement

4.1 API Description

4.2 Sample code

...
CustomInterstitialAd customInterstitialAd;

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

5. Display advertising

• When developers call the show() API of ATInterstialAd, they will sequentially call the isAdReady() and show() methods of the custom adapter
• Developers need to rewrite the show() method. In this method, they call the API of the custom advertising platform to display custom advertisements, notify TopOn SDK through CustomInterstitialEventListener, and expose, click, close and other events of advertisements

5.1 API Description

5.2 Sample code

...
CustomInterstitialAd customInterstitialAd;

@Override
public void show(Activity activity) {
    if (customInterstitialAd != null) {
        
        customInterstitialAd.setEventListener(new CustomAdEventListener() {
            @Override
            public void onAdImpression() {
                //Notify TopOn SDK of successful advertisement exposure
                if (mImpressListener != null) {
                    mImpressListener.onInterstitialAdShow();
                }
            }
            
            @Override
            public void onADClicked() {
                //Notify TopOn SDK that the advertisement has been clicked
                if (mImpressListener != null) {
                    mImpressListener.onInterstitialAdClicked();
                }
            }
            
            @Override
            public void onADClicked() {
                //Notify TopOn SDK that advertising has been closed
                if (mImpressListener != null) {
                    mImpressListener.onInterstitialAdClose();
                }
            }
            
        });
        
        //Trigger advertising display
        customInterstitialAd.show(activity);
    }
}

Appendix Implementation of ATBiddingNotice Notification for Customized Platform Bidding Results

By implementing the ATBiddingNotice interface and rewriting relevant methods to notify custom advertising platforms of winning or losing events

1. Implement ATBiddingNotice

• Taking insert ads as an example, developers can choose to implement the ATBiddingNotice interface to notify custom advertising platforms of bidding result events (the specific timing of sending is determined by the TopOn SDK)

1.1 Sample code

public class CustomSDKBiddingNotice implements ATBiddingNotice {

	//Customized advertising platform's advertising targets
	CustomInterstitialAd customInterstitialAd;

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

}

2. Notify the winning bidder

• When the advertisement on this platform reaches the highest price in this load, trigger the notifyBidWin() method
• Developers need to rewrite the 'notifyBidWin() method. In this method, call the API of the customized advertising platform to notify the advertising platform that it has won

2.1 API Description

2.2 Sample code

@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 the winning bidder
    customInterstitialAd.sendWinNotification(map);

    customInterstitialAd = null;
}

3. Notification of Defeat

• When this platform's advertisement is considered lost by TopOn due to cache expiration or other reasons, the notifyBidLoss() method is triggered
• Developers need to rewrite the 'notifyBidLoss() method. In this method, call the API of the customized advertising platform to notify the advertising platform that it has failed

3.1 API Description

ATAdConst.BIDDING_TYPE：Reasons for losing the competition

ATAdConst.BIDDING_ADN_ID：Winning channel

3.2 Sample code

@Override
public void notifyBidLoss(String lossCode, double winPrice, Map<String, Object> extra) {
        
    //Determine the reason for the defeat
    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);

    //Notification of Defeat
    customInterstitialAd.sendLossNotification(map);

    customInterstitialAd = null;
}

4. Other API descriptions