Client Bidding supports returning a specific price when ad fills. Publishers are able to use this function to compete with other ad networks on client end to determine the highest price ad, which will maximum gross revenue.

Below is the working flow of Client Bidding:

Step1、 Send ad request to TopOn SDK and mediation SDK concurrently;

Step2、 Ad fills asynchronously from both side, and TopOn will return a specific price once ad fills;

Step3、 When an ad opportunity takes place, publisher shall verify the status of each ads, if ads expire, remove the ads, otherwise the ads are ready to compete with each other

Step4、 Compare the price of ads and determine which ad could win this impression;

Step5、 If no ads win, or after finishing displaying the ad, repeat step1

* This document is only applicable to the in-house mediation integration mode exclusively for TopOn ADX. For scenarios that require access to TopOn's mediation features in addition to TopOn ADX, please contact our Account Manager for integration assistance.

Android Guide

一、Prerequisites

1. Android TopOn SDK version >= 6.2.79

二、integration Guide

1. Create TopOn AppId & Placement Id

Creation details：TopOn Application Management.

 2. Integrate TopOn SDK

Step 1:

You can integrate TopOn SDK through this document ：Android SDK Intergrate.

Step 2 :

Before initializing the TopOn SDK, call this code to set the advertising placement to Adx single mode. "TopOnPlacementId" needs to be replaced with the corresponding TopOn placement ID.

ATAdxSetting.getInstance().openAdxNetworkMode(TopOnPlacementId);

Step 3:

You can start using the TopOn SDK for Ad requests and impressions: Android SDK initialization.

3. Get Price 

Please follow instruction of integrating each ad types. Then you can follow the below method to get price when an ad fills:

You can get "ATAdInfo" in the callback interface when the ad is loaded successfully, and then get the Ecpm of this ad through "getEcpm()" of ATAdInfo.

p.s: The units of ecpm mentioned below must be in US dollars.

The sample code is as follows:

        // Native Ad
        ATNative atNative = new ATNative(context, "Your Placement Id", new ATNativeNetworkListener() {
            @Override
            public void onNativeAdLoaded() {
                ATAdStatusInfo adStatusInfo = atNative.checkAdStatus();
                ATAdInfo adInfo = adStatusInfo.getATTopAdInfo();
                String currency = adInfo.getCurrency();
                double ecpm = adInfo.getEcpm();
            }
        });

        // Rewarded Video
        ATRewardVideoAd rewardVideoAd = new ATRewardVideoAd(context, "Your Placement Id");
        rewardVideoAd.setAdListener(new ATRewardVideoListener() {
            @Override
            public void onRewardedVideoAdLoaded() {
                ATAdStatusInfo adStatusInfo = rewardVideoAd.checkAdStatus();
                ATAdInfo adInfo = adStatusInfo.getATTopAdInfo();
                String currency = adInfo.getCurrency();
                double ecpm = adInfo.getEcpm();

            }

        });

        // Interstitial
        ATInterstitial interstitial = new ATInterstitial(context, "Your Placement Id");
        interstitial.setAdListener(new ATInterstitialListener() {
            @Override
            public void onInterstitialAdLoaded() {
                ATAdStatusInfo adStatusInfo = interstitial.checkAdStatus();
                ATAdInfo adInfo = adStatusInfo.getATTopAdInfo();
                String currency = adInfo.getCurrency();
                double ecpm = adInfo.getEcpm();

            }

        });

        // App Open Ad
        ATSplashAd splashAd = new ATSplashAd(context, "Your Placement Id", new ATSplashAdListener() {
            @Override
            public void onAdLoaded(boolean isTimeout) {
                ATAdStatusInfo adStatusInfo = interstitial.checkAdStatus();
                ATAdInfo adInfo = adStatusInfo.getATTopAdInfo();
                String currency = adInfo.getCurrency();
                double ecpm = adInfo.getEcpm();

            }

        });


        // Banner Ad
        ATBannerView bannerView = new ATBannerView(context);
        bannerView.setPlacementId("Your Placement Id");
        bannerView.setBannerAdListener(new ATBannerListener() {
            @Override
            public void onBannerLoaded() {
                ATAdStatusInfo adStatusInfo = bannerView.checkAdStatus();
                ATAdInfo adInfo = adStatusInfo.getATTopAdInfo();
                String currency = adInfo.getCurrency();
                double ecpm = adInfo.getEcpm();

            }

        });

 4. Auction

4.1 TopOn Adx win

If TopOn wins, you should pass the highest price of second bidder to TopOn before you show the ad. This step will help us to optimize performance

ATAdStatusInfo adStatusInfo = rewardVideoAd.checkAdStatus();
ATAdInfo adInfo = adStatusInfo.getATTopAdInfo();
IATAdxHandler adxHandler = adInfo.getAdxHandler();
if(adxHandler != null) {
     Map<String, Object> winExtraMap = new HashMap<>();
     winExtraMap.put(IATAdxHandler.SECOND_PRICE, <Loss ecpm>);//<Loss ecpm>: double
      //Loss Network Name
     winExtraMap.put(IATAdxHandler.BIDDER_NAME, <Loss Network Name>);//<Loss Network Name>: String
     adxHandler.notifyWin(winExtraMap);
}

4.1 TopOn Adx loss

If TopOn losses, you should pass the price of first bidder to TopOn before you show the ad. This step will help us to optimize performance

ATAdStatusInfo adStatusInfo = rewardVideoAd.checkAdStatus();
ATAdInfo adInfo = adStatusInfo.getATTopAdInfo();
IATAdxHandler adxHandler = adInfo.getAdxHandler();
if(adxHandler != null) {
     Map<String, Object> lossExtraMap = new HashMap<>();
      //Win Network Name
     winExtraMap.put(IATAdxHandler.BIDDER_NAME, <Loss Network Name>);//<Loss Network Name>: String
     /**
        * @param lossReason // loss reason
        * @param winEcpm // win price
        * @param lossExtraMap // loss extra info
      */
     adxHandler.notifyLose(lossReason, winEcpm, lossExtraMap);
}

 LossReason:

Code	Description
IATAdxHandler.LOSS_REASON.LOSS_TO_HIGHER_BID	The adx price is lower than the higher priced auction ad
IATAdxHandler.LOSS_REASON.LOSS_TO_NORMAL	The price of adx is lower than higher priced fixed price ads (non-auction ads)

 5.Show Ads

If TopOn wins, please refer to Android SDK Intergrate and show TopOn ads

iOS Guide

一、Prerequisites

1. iOS Taku SDK version >= 6.2.76

二、integration Guide

1. Create Taku AppId & Placement Id

Creation details：Taku Application Management。

 2. Integrate Taku SDK

Step 1:

You can integrate Taku SDK through this document ：iOS SDK Intergrate。

Step 2 :

Before initializing the Taku SDK, call this code to set the advertising placement to Adx single mode. Once this mode is enabled, it will take effect during the current app startup cycle and cannot be reset. "TakuPlacementId" needs to be replaced with the corresponding Taku placement ID.

[[ATADXSettings shareInstance] setAdxNetworkModeWithPlacementId:@"TakuPlacementId"];

Step 3:

You can start using the Taku SDK for Ad requests and impressions: iOS SDK initialization

3. Get Price 

Please follow instruction of integrating each ad types. Then you can follow the below method to get price when an ad fills:

After the ad is loaded successfully, you can call the API interface of the corresponding ad style to get the valid cache list in the loading success callback interface to get the validAds array, and then get the first cache information "adOfferInfo" through the validAds array. Through the "adOfferInfo" dictionary information key, take the value of "adsource_price" to get the Ecpm of the ad.

p.s: The currency unit returned by "adsource_price" is consistent with the currency unit under the background account, usually RMB (CNY) or US dollar (USD), which can be determined by adOfferInfo[@"currency"]. For more key values, please refer to the official website document: Callback Description

The sample code is as follows:

- (void)didFinishLoadingADWithPlacementID:(NSString *)placementID {
    // RewardedVideo
    NSArray *validAds = [[ATAdManager sharedManager] getRewardedVideoValidAdsForPlacementID:@"Your Placement Id"];
    NSDictionary *adOfferInfo = validAds.firstObject;
    NSString *ecpm = adOfferInfo[@"adsource_price"];
    NSString *currency = adOfferInfo[@"currency"];
    
    // InterstitialLoad
    NSArray *validAds = [[ATAdManager sharedManager] getInterstitialValidAdsForPlacementID:@"Your Placement Id"];
    NSDictionary *adOfferInfo = validAds.firstObject;
    NSString *ecpm = adOfferInfo[@"adsource_price"];
    NSString *currency = adOfferInfo[@"currency"];
    
    // Native
    NSArray *validAds = [[ATAdManager sharedManager] getNativeValidAdsForPlacementID:@"Your Placement Id"];
    NSDictionary *adOfferInfo = validAds.firstObject;
    NSString *ecpm = adOfferInfo[@"adsource_price"];
    NSString *currency = adOfferInfo[@"currency"];
    
    // Banner
    NSArray *validAds = [[ATAdManager sharedManager] getBannerValidAdsForPlacementID:@"Your Placement Id"];
    NSDictionary *adOfferInfo = validAds.firstObject;
    NSString *ecpm = adOfferInfo[@"adsource_price"];
    NSString *currency = adOfferInfo[@"currency"];
    
    // Splash
    NSArray *validAds = [[ATAdManager sharedManager] getSplashValidAdsForPlacementID:@"Your Placement Id"];
    NSDictionary *adOfferInfo = validAds.firstObject;
    NSString *ecpm = adOfferInfo[@"adsource_price"];
    NSString *currency = adOfferInfo[@"currency"];
}

 4. Auction

Please refer to the acquisition method in the third point above. After obtaining the array according to different ad types, call the following method to obtain adxObject. This object can be used for subsequent Adx winning and losing operations. Take rewarded video ads as an example:

// RewardedVideo
NSArray *validAds = [[ATAdManager sharedManager] getRewardedVideoValidAdsForPlacementID:@"Your Placement Id"];
NSDictionary *adOfferInfo = validAds.firstObject;
ATADXObject *adxObject = adOfferInfo[@"adx_object"];

4.1 Taku Adx win

If Taku wins, you should pass the highest price of second bidder to Taku before you show the ad. This step will help us to optimize performance

Note: The price currency unit passed in kATADXObjectSecondLossPrice must be US dollars

- (void)sendWinNotification {
    // RewardedVideo
    NSArray *validAds = [[ATAdManager sharedManager] getRewardedVideoValidAdsForPlacementID:@"Your Placement Id"];
    NSDictionary *adOfferInfo = validAds.firstObject;
    ATADXObject *adxObject = adOfferInfo[@"adx_object"];

    //  send win
    [adxObject sendWinNotificationWithInfo:@{
        kATADXObjectNetwokName: @"Second ad netwok name",
        kATADXObjectSecondLossPrice: @"The second price is in US dollars."
    }];
}

4.2 Taku Adx loss

If Taku losses, you should pass the price of first bidder to Taku before you show the ad. This step will help us to optimize performance

Note: The price currency unit passed by kATADXObjectWinPrice must be US dollars

- (void)sendLossNotification {
    // RewardedVideo
    NSArray *validAds = [[ATAdManager sharedManager] getRewardedVideoValidAdsForPlacementID:@"Your Placement Id"];
    NSDictionary *adOfferInfo = validAds.firstObject;
    ATADXObject *adxObject = adOfferInfo[@"adx_object"];

    // send loss
    [adxObject sendLossNotificationWithInfo:@{
        kATADXObjectNetwokName: @"win ad network name",
        kATADXObjectWinPrice: @"win price, Currency required USD",
        kATADXObjectLossReason: kATADXObjectLossReasonBidLowPrice,//If the price is lower than other bidding ad sources
    }];
}

 LossReason:

Code	Description
kATADXObjectLossReasonBidLowPrice	The adx price is lower than the higher priced auction ad
kATADXObjectLossReasonLowPrice	The price of adx is lower than higher priced fixed price ads (non-auction ads)

 5.Show Ads

If Taku wins, please refer to iOS SDK Intergrate and show Taku ads