Manual loading

1. Introduction

Manual loading mode can satisfy developers who need flexible access.

1.1 Integration suggestions

Note: The SDK will not hold ads Instance (ATRewardVideoAd) and callback instance (ATRewardVideoListener), so developers need to ensure that the ad instance will not be recycled before the ad ends to avoid callback loss

1. Load ad:
• After starting the application or game, use ATRewardVideoAd.load to load the advertisement. Please call the loading method in advance to request the advertisement (for example, start loading the advertisement when the application starts), so that it can be displayed quickly when the advertisement needs to be triggered< /li>
• It is recommended to call entryAdScenario(placementId,scenarioId) after entering the scene where ads can be displayed to count the cache status of the current ad slot. Specific statistical instructions can be View Advertising scenarios to differentiate between different business scenarios
2. Display ads:
• Pre-display judgmentisAdReady()Whether it is ready, call show for ad display when ready; if it is not ready, initiate ad loading and wait for the ad to load successfully; if it is necessary to display the ad in the successful callback (onRewardedVideoAdLoaded) , you must first determine that the current application is in the foreground before executing the display method, otherwise it may cause the advertisement to be displayed outside the application or fail to display normally;
3. Ad preloading:
• After the rewarded video ad is displayed, there is no need in the callback of onRewardedVideoAdPlayStart isAdReady determines and directly calls load to preload  (helps to improve priority The impression volume of higher-level advertising sources)
• Please refer to Automatically request ads, turn on automatic request for ads (If preloading after display above has been implemented, there is no need to turn it on)

It is recommended to configure the preset strategy: improve the first cold start ad loading For effects, detailed instructions and access tutorials, see SDK preset strategy usage instructions

1.2 Notes

   1. It is forbidden to execute the ad loading method in the onRewardedVideoAdFailed callback, otherwise it will cause a lot of useless requests and may cause the application to freeze p>

   2. The userId and extraData passed in by setLocalExtra will only take effect for the next and subsequent rewarded video loads. , does not take effect on cached rewarded video ads

2. API description

2.1 Advertisement loading

ATRewardVideoAd: Loading class for RewardedVideo ads

2.2 Local parameters

ATAdConst.KEY: LocalExtra local parameter predefined Key value

Ad loading:

//Note: The advertising object must be globally referenced. If the advertising object is a temporary variable, it may be reclaimed during the advertising loading process and unable to receive advertising event callbacks
ATRewardVideoAd mRewardVideoAd;
private void loadAd() {
    if (mRewardVideoAd == null) {
        mRewardVideoAd = new ATRewardVideoAd(this, rewardTopOnPlacementID);
    }
    String userid = "test_userid_001";
    String userdata = "test_userdata_001";
    Map<String, Object> localMap = new HashMap<>();
    localMap.put(ATAdConst.KEY.USER_ID, userid);
    localMap.put(ATAdConst.KEY.USER_CUSTOM_DATA, userdata);
    //Pass custom parameters when loading, and after filling the ad source, the custom parameters will be saved and returned during display. Applicable scenario: Similar to preventing cheating when passing in session information
    mRewardVideoAd.setLocalExtra(localMap);
    mRewardVideoAd.load();
}

Pass custom parameters when loading. After the ad source is filled, the custom parameters will be saved together with the ad source cache. If you want to pass in custom parameters when  ad displaying, please update TopOn SDK v6.3.10 and above.

2.3 Advertising object

ATRewardVideoAd:

ATAdStatusInfo: Status object of the advertising slot

2.4 Advertisement display

ATRewardVideoAd:

Ad display:

private void showAd() {
    /*
     In order to calculate the scene arrival rate, relevant information can be consulted“ https://docs.toponad.com/#/zh -CN/android/NetworkAccess/scenario/scenario“

Call the "Enter Advertising Scene" method when the advertising triggering conditions are met, for example:

**If an advertisement pops up after the cleaning is completed, it will be called at the end of the cleaning;

*1. First call "entryAdScenario"

*2. Can calling "isAdReady" display

*3. Finally, call "show" to display

*4. Scenario ID is passed in to the backend scene management for data display
     */            
       ATRewardVideoAd.entryAdScenario("your rv placementID", "your scenarioID");
    if (mRewardVideoAd.isAdReady()) {
        mRewardVideoAd.show(activity，"your scenarioID");
    }
} 

Pass in custom parameters when ad displaying:

TopOn SDK v6.3.10 and above supports developers to pass in custom parameters during ad display. The custom parameters passed in during display are independent of the custom parameters passed in during load. Custom parameters passed in during presentation can be returned in the TopOn SDK callback information. At the same time, TopOn's server-to-server Rewarded callback also supports returning custom parameters passed in during ad display.

2.5 Advertising Monitoring

ATRewardVideoAd:

ATRewardVideoListener: Event callback monitoring for RewardedVideo ads:

Advertisement listening:

//Note: The advertising object must be globally referenced. If the advertising object is a temporary variable, it may be reclaimed during the advertising loading process and unable to receive advertising event callbacks
        mRewardVideoAd.setAdListener(new ATRewardVideoListener() {
            @Override
            public void onRewardedVideoAdLoaded() {
            }
            @Override
            public void onRewardedVideoAdFailed(AdError adError) {
                //Note: It is prohibited to retry the loading method of advertisements in this callback, otherwise it will cause many useless requests and may cause the application to lag
                //AdError，请参考 https://docs.toponad.com/#/zh-cn/android/android_doc/android_test?id=aderror
                Log.e(TAG, "onRewardedVideoAdFailed:" + adError.getFullErrorInfo());
            }
            @Override
            public void onRewardedVideoAdPlayStart(ATAdInfo adInfo) {
                //ATAdInfo can distinguish between advertising platforms and obtain advertising space IDs for advertising platforms
                //please refer to https://docs.toponad.com/#/zh-cn/android/android_doc/android_sdk_callback_access?id=callback_info

                //It is recommended to call load in this callback to load advertisements for the convenience of next advertisement display (isAdReady() is not required)
                mRewardVideoAd.load();
            }
            @Override
            public void onRewardedVideoAdPlayEnd(ATAdInfo atAdInfo) {
            }
            @Override
            public void onRewardedVideoAdPlayFailed(AdError adError, ATAdInfo atAdInfo) {
                //AdError，please refer to https://docs.toponad.com/#/zh-cn/android/android_doc/android_test?id=aderror
                Log.e(TAG, "onRewardedVideoAdPlayFailed:" + adError.getFullErrorInfo());
            }
            @Override
            public void onRewardedVideoAdClosed(ATAdInfo atAdInfo) {
            }
            @Override
            public void onReward(ATAdInfo atAdInfo) {
                //Suggest issuing rewards in this callback, usually before onRewardedVideoAdClosed
            }
            @Override
            public void onRewardedVideoAdPlayClicked(ATAdInfo atAdInfo) {
            }
        });

2.6 Other monitoring

ATRewardVideoExListener：Inherited from ATRewardVideoListener, same method as

ATRewardVideoListener，The additional callback instructions are as follows：

ATAppDownloadListener： (Only supported by SDK in China) Event callback listening for download status
Currently, only the following platforms are supported：csj

3. Sample code

//Note: The advertising object must be globally referenced. If the advertising object is a temporary variable, it may be reclaimed during the advertising loading process and unable to receive advertising event callbacks
ATRewardVideoAd mRewardVideoAd;
private void loadAd() {
    if (mRewardVideoAd == null) {
        mRewardVideoAd = new ATRewardVideoAd(this, rewardTopOnPlacementID);
        mRewardVideoAd.setAdListener(new ATRewardVideoListener() {
            @Override
            public void onRewardedVideoAdLoaded() {
            }
            @Override
            public void onRewardedVideoAdFailed(AdError adError) {
                //Note: It is prohibited to retry the loading method of advertisements in this callback, otherwise it will cause many useless requests and may cause the application to lag
                //AdError，please refer to https://docs.toponad.com/#/zh-cn/android/android_doc/android_test?id=aderror
                Log.e(TAG, "onRewardedVideoAdFailed:" + adError.getFullErrorInfo());
            }
            @Override
            public void onRewardedVideoAdPlayStart(ATAdInfo adInfo) {
                //ATAdInfo can distinguish between advertising platforms and obtain advertising space IDs for advertising platforms
                //please refer to https://docs.toponad.com/#/zh-cn/android/android_doc/android_sdk_callback_access?id=callback_info

                //It is recommended to call load in this callback to load advertisements for the convenience of next advertisement display (isAdReady() is not required)
                mRewardVideoAd.load();
            }
            @Override
            public void onRewardedVideoAdPlayEnd(ATAdInfo atAdInfo) {
            }
            @Override
            public void onRewardedVideoAdPlayFailed(AdError adError, ATAdInfo atAdInfo) {
                //AdError，please refer to https://docs.toponad.com/#/zh-cn/android/android_doc/android_test?id=aderror
                Log.e(TAG, "onRewardedVideoAdPlayFailed:" + adError.getFullErrorInfo());
            }
            @Override
            public void onRewardedVideoAdClosed(ATAdInfo atAdInfo) {
            }
            @Override
            public void onReward(ATAdInfo atAdInfo) {
                //Suggest issuing rewards in this callback, usually before onRewardedVideoAdClosed
            }
            @Override
            public void onRewardedVideoAdPlayClicked(ATAdInfo atAdInfo) {
            }
        });
    }
    String userid = "test_userid_001";
    String userdata = "test_userdata_001";
    Map<String, Object> localMap = new HashMap<>();
    localMap.put(ATAdConst.KEY.USER_ID, userid);
    localMap.put(ATAdConst.KEY.USER_CUSTOM_DATA, userdata);
    //Pass custom parameters when loading, and after filling the ad source, the custom parameters will be saved and returned during display. Applicable scenario: Similar to preventing cheating when passing in session information
    mRewardVideoAd.setLocalExtra(localMap);
    mRewardVideoAd.load();
}
private void showAd() {
    /*
     In order to calculate the scene arrival rate, relevant information can be consulted“ https://docs.toponad.com/#/zh -CN/android/NetworkAccess/scenario/scenario“

Call the "Enter Advertising Scene" method when the advertising triggering conditions are met, for example:

**If an advertisement pops up after the cleaning is completed, it will be called at the end of the cleaning;

*1. First call "entryAdScenario"

*2. Can calling "isAdReady" display

*3. Finally, call "show" to display

*4. Scenario ID is passed in to the backend scene management for data display
     */            
       ATRewardVideoAd.entryAdScenario("your rv placementID", "your scenarioID");
    if (mRewardVideoAd.isAdReady()) {
        mRewardVideoAd.show(activity，"your scenarioID");
    }
} 

For detailed rewarded video ad sample code, please refer to: RewardVideoAdActivity class of Demo