Splash ad

1. Introduction to open-screen advertising

Splash's advertisements rely on developers to create their own Activity. They only need to add the container that displays the advertisement ViewGroup strong> Just pass the api to Splash and use it. Splash will automatically render ads to ViewGroup;

1.1 Integration Suggestions

Cold start (the initial startup of the application when the application process does not exist):

• In the application Or after the game is started, call the ATSplashAd.loadAd method to load the open-screen advertisement.
• In order to avoid the loading timeout of open-screen ads, other forms of ad preloading logic and other requests that consume network resources are executed after the open-screen ads are displayed.
• It is recommended to use the first-time installation opening screen loading efficiency improvement solution to improve the loading efficiency of opening screen advertisements after the first installation.
• If the ad loading times out (determined by the onAdLoadTimeout() callback), there is no need to continue waiting for the ad to be filled, and you can directly enter the main interface. However, please note that the opening ad is still loading. If it is loaded successfully, the onAdLoaded(true) callback will be triggered.
• When the onAdLoaded() callback is triggered, if the loading does not time out (isTimeout is false), call the ATSplashAd.show() method to display ads.

Hot start (the application temporarily retreats to the background through the home button, and returns to the application while the application process still exists):

• When the application returns to the foreground, call the ATSplashAd.isAdReady() method to determine whether there is currently an advertisement. cache. If the result is true, the ATSplashAd.show() method is called to display the ad; if the result is false, the ATSplashAd.loadAd is called ()Method to preload ads.

Statistics after entering the scene where ads can be displayed:

• It is recommended to call the entryAdScenario(placementId, scenarioId) method to count the cache status of the current ad slot. For specific statistical explanations, please see the data that distinguishes different business scenarios in advertising scenarios.

Ad preloading:

• After the open-screen ad is displayed, you can call the load method in the onAdShow or onAdDismiss callback to preload.
• If you need to display open-screen ads during hot start, it is recommended to call the ATSplashAd.isAdReady() method when the app exits to the background. Determine whether there is a cache of open-screen advertisements. If there is no cache, call the load method to preload.
• You can refer to Automatically request ads to enable the automatic request for ads function. If you have already implemented the post-impression preloading feature described above, you do not need to enable automatic ad requesting.

Open screen advertising configuration:

• Configure the bottom-up screen advertising source in the background to reduce loading timeouts. For specific configuration methods, please refer to the instructions for open-screen advertising.

Preset policy configuration:

• It is recommended to configure a preset strategy to improve the loading effect of ads during the first cold start. For specific instructions and access tutorials, please refer to the SDK preset policy instructions.

1.2 Notes

   1.SplashThe display area of ​​the ad is the largest It is best to be more than 75% of the screen height and skip seconds for more than 3 seconds, otherwise the ad display may be invalid;

   2.SplashWhen the ad is displayed It is recommended that the incoming container remain visible (View.VISIBLE) before loading the ad, to avoid dynamic hiding of the display causing failure to display the ad.

   3. Avoid calling the show interface to display ads when the app is in the background or the screen is turned off. If the app is not in the foreground, the display of open-screen ads may fail.

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

   5. Some platforms do not pause the countdown after jumping to the landing page. Even if you are viewing the landing page, onAdDismiss will still be called back after the countdown ends. Therefore, special processing is required when the page jumps. Please refer to the sample code for details.

   6.Splash does not support horizontal screen applications. (Pangolin advertising platform supports horizontal screen, you need to contact Pangolin for application; other platforms need to contact advertising platform for enquiry)

   7. Support HUAWEI (HMS) Open-screen ads support Sigmob's open-screen ads.

2. API description

2.1 Advertisement loading

ATSplashAd: Splash ad loading class

Ad loading:

ATSplashAd splashAd = new ATSplashAd(context, placementId, listner, 5000);
splashAd.loadAd();

2.2 Advertising display

ATSplashAd:

Ad display:

  /*
     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 (not mandatory)
     */
 ATSplashAd.entryAdScenario("your splash placementID", "your scenarioID");
//Before displaying, it is necessary to check that the advertisement has a cache and that the current activity is in the foreground
if (splashAd.isAdReady() && inForeBackground) {
    //The container size should occupy at least 75% of the screen
    splashAd.show(activity, container，"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.

2.3 Local parameters

ATSplashAd:

ATAdConst.KEY: LocalExtra local parameter predefined Key value

2.4 Advertisement Object

ATSplashAd:

ATAdStatusInfo: the status object of the advertising slot

2.5 Advertising Listening

ATSplashAdListener: Splash ad event callback class

ATSplashExListener: Inherited from ATSplashAdListener, the method is the same as ATSplashAdListener, additional callback descriptions are as follows:

IATSplashEyeAd: Control class for opening screen eye-catching ads

ATSplashEyeAdListener< /span>：Event callback class for screen-opening ads

ATSplashSkipInfo: Customized SkipView function class

ATSplashSkipAdListener: Customized SkipView event listening class

3 Sample code

String defaultConfig = "";

//To set up the first screen opening advertisement source, please export the configuration of the screen opening advertisement source from the TopOn backend
/*defaultConfig = "{\"unit_id\":1442678,\"nw_firm_id\":15,\"adapter_class\":\"com.anythink.network.toutiao.TTATSplashAdapter\",\"content\":\"{\\\"button_type\\\":\\\"0\\\",\\\"dl_type\\\":\\\"0\\\",\\\"slot_id\\\":\\\"100011\\\",\\\"personalized_template\\\":\\\"0\\\",\\\"zoomoutad_sw\\\":\\\"1\\\",\\\"app_id\\\":\\\"5001121\\\"}\"}";*/

ATSplashAd splashAd = new ATSplashAd(context, placementId, listner, 5000, defaultConfig);
splashAd.loadAd();

 /*
     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 (not mandatory)
     */
 ATSplashAd.entryAdScenario("your splash placementID", "your scenarioID");
//Before displaying, it is necessary to check that the advertisement has a cache and that the current activity is in the foreground
if (splashAd.isAdReady() && inForeBackground) {
    //The container size should occupy at least 75% of the screen
    splashAd.show(activity, container，"your scenarioID");
}

Details For on-screen advertising sample code, please refer to: Demo's SplashAdActivity class

Cold start example:

ATSplashExListener listener = new ATSplashExListener() {
    ......
    @Override
    public void onAdLoaded(boolean isTimeout) {
        //When loading without timeout
        if(!isTimeout){
            //Advertising display when the current activity is in the foreground
            if(inForeBackground){
                //The container size should occupy at least 75% of the screen
                splashAd.show(activity, container);
            }else{
                //Wait for the application to return to the front-end before displaying it
                needShowSplashAd = true;
            }
        }
    }

    @Override
    public void onAdLoadTimeout() {
        //After loading timeout, directly enter the main interface
        jumpToMainActivity();
    }

    @Override
    public void onNoAdError(AdError adError) {
        //Loading failed, directly enter the main interface
        jumpToMainActivity();
    }

    @Override
    public void onAdShow(ATAdInfo entity) {

    }

    @Override
    public void onAdDismiss(ATAdInfo entity, ATSplashAdExtraInfo splashAdExtraInfo) {
        //=1 indistinguishable=2 skip end=3 countdown end=4 click ad end=99 open screen display failure
        if(splashAdExtraInfo.getDismissType()==ATAdConst.DISMISS_TYPE.SHOWFAILED){
    }
        //Enter the main interface after opening and closing the screen advertising display
        //Note: Some platforms do not pause the countdown after jumping to the landing page. Even when viewing the landing page, the onAdDismiss callback will still be triggered after the countdown ends
        //Therefore, special handling is required when jumping to the page. Please refer to the example code below for details
        jumpToMainActivity();
    }
    ......
};

String defaultConfig = "";

//To set up the first screen opening advertisement source, please export the configuration of the screen opening advertisement source from the TopOn backend
defaultConfig = "export json string from server";

ATSplashAd splashAd = new ATSplashAd(context, placementId, listner, 5000, defaultConfig);

if (splashAd.isAdReady()) {
    //The container size should occupy at least 75% of the screen
    splashAd.show(activity, container);
}else{
    splashAd.loadAd();
}

onAdDismiss() open-screen advertising page jump example:

//Do you need to mark page jumps
boolean needJump;

@Override
protected void onResume() {
    super.onResume();
    if (needJump) {
        jumpToMainActivity();
    }
    needJump = true;
}

@Override
protected void onPause() {
    super.onPause();
    needJump = false;
}

public void jumpToMainActivity() {
    if (!needJump) {
        needJump = true;
        return;
    }
    Intent intent = new Intent(this, YourMainActivity.class);
    startActivity(intent);
    finish();
}

4. Special configuration instructions for advertising platform

4.1 Admob

• Admob's open-screen ads do not need to rely on containers for display, and can only be displayed in full screen. There will be no countdown and automatic skipping after the ad is displayed

4.2 Baidu

• If you have Splash ads connected to Baidu SDK, you need to select the SkipView display style in Baidu backend (Baidu backend selects not to display by default SkipView).

4.3 Pangle

• Before loading the ad, you need to set the width and height of the ad. The example is as follows:

splashAd = new ATSplashAd(this, placementId, atMediationRequestInfo, this, 5000); 
Map<String, Object> localMap = new HashMap<>(); 
localMap.put(ATAdConst.KEY.AD_WIDTH, width);//单位：px 
localMap.put(ATAdConst.KEY.AD_HEIGHT, height);//单位：px 
splashAd.setLocalExtra(localMap); 
splashAd.loadAd();

Note: If the set width and height are different from the display The width and height of the container are inconsistent, or the template rendering options of the TopOn backend do not correspond to the Pangolin backend, which will result in incomplete or blurry or distorted ad display.

5. Example of opening the screen to highlight

(1) Because it may not be possible to load open-screen ads that support eye-catching, so if there is a problem with the fill rate of eye-catching materials for open-screen ads, please contact the advertising platform for processing

(2) For the following sample code, please refer to Demo

5.1 The activity that opens the screen and the activity that displays the eye-catching advertisement are not the same

1. Create a new SplashEyeAdHolder class to cache IATSplashEyeAd instances< /p>

public class SplashEyeAdHolder {
    public static IATSplashEyeAd splashEyeAd;
}

public class SplashAdShowActivity extends Activity implements ATSplashAdListener {
    ...
    @Override
    public void onAdDismiss(ATAdInfo entity, ATSplashAdExtraInfo splashAdExtraInfo) {
        Log.i(TAG, "onAdDismiss:\n" + entity.toString());

        //（1）When the open screen advertising materials of pangolins and Youlianghui support highlight, splashEyeAd is not null
        //（2）When a Kwai opening screen advertisement is displayed, splashEyeAd is a non null value, but it does not necessarily mean that the material of the Kwai opening screen advertisement supports the finishing touch. If not, calling the IATSplashEyeAd # show() method will directly call back the ATSplashEyeAdListener # onAdDismiss() method
        //（3）When splashEyeAd is not null, but developers do not want to support the highlight feature, they must call splashEyeAd. destroy() to release resources, then jump to the main page or remove the open screen view

        SplashEyeAdHolder.splashEyeAd = splashAdExtraInfo.getAtSplashEyeAd();

        jumpToMainActivity();
    }
}

2. Set the information related to opening the screen (please refer to Demo for SplashZoomOutManager), jump to the homepage Activity and cancel the page jump animation, and close the current page

public class SplashAdShowActivity extends Activity implements ATSplashAdListener {
    ...
    public void jumpToMainActivity() {
        if (!hasHandleJump) {
            hasHandleJump = true;

            if (SplashEyeAdHolder.splashEyeAd != null) {
                try {
                    SplashZoomOutManager zoomOutManager = SplashZoomOutManager.getInstance(getApplicationContext());
                    zoomOutManager.setSplashInfo(container.getChildAt(0),
                            getWindow().getDecorView());
                } catch (Throwable e) {
                    Log.e(TAG, "jumpToMainActivity: ------------------------------------------ error");
                    e.printStackTrace();
                }

                Intent intent = new Intent(this, TestMainActivity.class);
                startActivity(intent);

                overridePendingTransition(0, 0);
            }

            finish();
            Toast.makeText(this, "start your MainActivity.", Toast.LENGTH_SHORT).show();
        }
    }
}

3. In the homepage Activity, create the showSplashEyeAd() method

public class TestMainActivity extends Activity {
    ...
    private void showSplashEyeAd() {

        if (SplashEyeAdHolder.splashEyeAd == null) {
            return;
        }

        SplashEyeAdHolder.splashEyeAd.show(TestMainActivity.this, null, new ATSplashEyeAdListener() {
            @Override
            public void onAnimationStart(View splashView) {
                //Execute scaling animation
                SplashZoomOutManager zoomOutManager = SplashZoomOutManager.getInstance(getApplicationContext());

                //It is recommended to prioritize using the size returned by IATSplashEyeAd # getSuggestedSize() as the target size for scaling animations
                int[] suggestedSize = SplashEyeAdHolder.splashEyeAd.getSuggestedSize(getApplicationContext());
                if (suggestedSize != null) {
                    zoomOutManager.setSplashEyeAdViewSize(suggestedSize[0], suggestedSize[1]);
                }
                zoomOutManager.startZoomOut((ViewGroup) getWindow().getDecorView(),
                        findViewById(android.R.id.content), new SplashZoomOutManager.AnimationCallBack() {

                            @Override
                            public void animationStart(int animationTime) {

                            }

                            @Override
                            public void animationEnd() {
                                Log.i(TAG, "animationEnd---------: eye ad");

                                //When the scaling animation is completed, IATSplashEyeAd # onFinished() must be called to notify the SDK
                                SplashEyeAdHolder.splashEyeAd.onFinished();
                            }
                        });

            }

            @Override
            public void onAdDismiss(boolean isSupportEyeSplash, String errorMsg) {
                Log.i(TAG, "onAdDismiss---------: close eye ad");

                //It is recommended to call IATPlashEyeAd # destroy() in this callback to release resources and other resources to avoid memory leaks
                SplashZoomOutManager zoomOutManager = SplashZoomOutManager.getInstance(getApplicationContext());
                zoomOutManager.clearStaticData();

                SplashEyeAdHolder.splashEyeAd.destroy();
                SplashEyeAdHolder.splashEyeAd = null;
            }
        });
    }

}

4. In the homepage Activity, call showSplashEyeAd() to display the eye-catching ad (it is recommended to call back in onAttachedToWindow() Call showSplashEyeAd())

 public class TestMainActivity extends Activity {
     ...
     @Override
    public void onAttachedToWindow() {
        super.onAttachedToWindow();

        showSplashEyeAd();
    }
}

5.2 The activity that opens the screen and the activity that displays the eye-catching advertisement are the same

public class SplashAdShowActivity extends Activity implements ATSplashAdListener {
    ...
    @Override
    public void onAdDismiss(ATAdInfo entity, IATSplashEyeAd splashEyeAd) {
        Log.i(TAG, "onAdDismiss:\n" + entity.toString());

        //(1) When the open screen advertising materials of pangolins and Youlianghui support highlight, splashEyeAd is not null

//(2) When a Kwai opening screen advertisement is displayed, splashEyeAd is a non null value, but it does not necessarily mean that the material of the Kwai opening screen advertisement supports the finishing touch. If not, calling the IATSplashEyeAd # show() method will directly call back the ATSplashEyeAdListener # onAdDismiss() method

//(3) When splashEyeAd is not null, but developers do not want to support the highlight feature, they must call splashEyeAd. destroy() to release resources, then jump to the main page or remove the open screen view


        if (container != null) {
            container.removeAllViews();
            container.setVisibility(View.GONE);
        }  

        //Display highlight advertisements
        showSplashEyeAd(splashEyeAd);
    }

     private void showSplashEyeAd(IATSplashEyeAd splashEyeAd) {
        if (splashEyeAd == null) {
            return;
        }

        splashEyeAd.show(SplashAdShowInCurrentActivity.this, null, new ATSplashEyeAdListener() {
            @Override
            public void onAnimationStart(View splashView) {
                //Execute scaling animation
                SplashZoomOutManager zoomOutManager = SplashZoomOutManager.getInstance(getApplicationContext());

                //It is recommended to prioritize using the size returned by IATSplashEyeAd # getSuggestedSize() as the target size for scaling animations
                int[] suggestedSize = splashEyeAd.getSuggestedSize(getApplicationContext());
                if (suggestedSize != null) {
                    zoomOutManager.setSplashEyeAdViewSize(suggestedSize[0], suggestedSize[1]);
                }

                zoomOutManager.setSplashInfo(splashView, getWindow().getDecorView());
                ViewGroup content = findViewById(android.R.id.content);
                zoomOutManager.startZoomOut(splashView, content, content, new SplashZoomOutManager.AnimationCallBack() {

                    @Override
                    public void animationStart(int animationTime) {

                    }

                    @Override
                    public void animationEnd() {
                        Log.i(TAG, "animationEnd---------: eye ad");

                        //When the scaling animation is completed, IATSplashEyeAd # onFinished() must be called to notify the SDK
                        splashEyeAd.onFinished();
                    }
                });


            }

            @Override
            public void onAdDismiss(boolean isSupportEyeSplash, String errorMsg) {
                Log.i(TAG, "onAdDismiss---------: eye ad");

                //It is recommended to call IATPlashEyeAd # destroy() in this callback to release resources and other resources to avoid memory leaks
                SplashZoomOutManager zoomOutManager = SplashZoomOutManager.getInstance(getApplicationContext());
                zoomOutManager.clearStaticData();
                splashEyeAd.destroy();
            }
        });
    }
}

6. First-time installation screen loading efficiency improvement solution

​ Background: The first time an open-screen advertisement is loaded when an application is installed, TopOn needs to pull the configured ad slot information from the background and cache it locally before going to Requesting advertisements from the advertising platform involves two network requests (serial), which affects the loading efficiency of the opening screen advertisement. The following provides two methods to improve the loading efficiency of the first opening screen after the application is installed.

6.1 (v6.1.78 and later versions) preset policy settings (recommended Use)

In order to improve the ad loading effect of the first cold start, create a traffic grouping of the SDK preset strategy on the open screen ad slot, and then Configure waterfall flow for this traffic grouping. It is also recommended that you add a bottom-up advertising source, and finally export the SDK preset strategy and preset it into the application. For specific access documents, see SDK Preset Strategy Usage Instructions.

Configuration effect: It can implement the SDK's preset screen opening strategy, while also providing a backup function for advertising sources. That is, this advertising source will initiate requests in parallel with the overall waterfall flow under the advertising space. And users do not necessarily use backdoor ads on their first request, but instead follow the normal parallel request of waterfall flow and backdoor ad sources. It can achieve maximum realization value.

Note: The timing of using the preset policy is only called when there is no cache policy available locally.