Splash

Splash ads are a special ad format that displays when an application is soft-launched or cold-launched.

Introduction

Ad styles that appear at natural endpoints and transition segments, supported ad size 9:20, effect image:

9:20

We recommend that you download and experience the Hisavana SSP Demo to gain a more intuitive and in-depth understanding of the SDK's features and usage. Through the Demo, you can quickly get started and explore its application in real-world scenarios.

Integration Mode Comparison

	View Mode (TSplashView)	Activity Mode (TSplash)
Class	`TSplashView`	`TSplash`
XML Layout Required	✅ Must be declared in layout	✗ Not required
Display Method	Rendered inside App's own container	SDK launches a standalone Activity internally
Lifecycle Management	App is responsible (handle click-return logic in onResume)	Managed by SDK, no extra handling needed
Fullscreen Mode	✗ Not supported	✅ Supported via `setEnableFullscreen()`
Best For	Custom layouts or embedding in existing pages	Standard cold-start splash, quick integration

Reminder: Choose your integration method based on the table above. The following steps are organized by View and Activity respectively.

Build the Component

View: Please add TSplashView in xml.

<androidx.constraintlayout.widget.ConstraintLayout 
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    android:layout_width="match_parent"
    android:layout_height="match_parent">

    <com.cloud.hisavana.sdk.api.adx.TSplashView
        android:id="@id/splash_ad"
        app:layout_constraintTop_toTopOf="parent"
        android:layout_width="match_parent"
        android:layout_height="0dp" />
</androidx.constraintlayout.widget.ConstraintLayout>

Activity: No need to build xml file.

Load Ads

Strongly Recommended: To prevent the application from getting stuck on the splash page due to special reasons; please add a timeout mechanism to the application splash page, for example, if the splash ad is not successfully displayed after about 3s, please navigate away automatically.

View：Please configure the corresponding parameters and callback listeners. Be sure to carefully review the documentation for the applicable ad placement types in relevant callbacks to avoid integration discrepancies.

// Bind the view from the xml layout
TSplashView tSplashView = findViewById(R.id.splash_ad);
// Set the ad unit ID, where "splash_id" is the splash ad unit ID
tSplashView.setPlacementId("splash_id");
// Set the ad listener
tSplashView.setListener(new TAdListener());
// Listen for skip actions  
tSplashView.setSkipListener(new TAdOnSkipListener());
// Load the ad
tSplashView.loadAd();

// Example: 'Timeout mechanism'
new Handler(Looper.getMainLooper()).postDelayed(new Runnable() {
    @Override
    public void run() {
       // Execute navigation logic
    }
}, 3000);

// Splash skip action listener
private class TAdOnSkipListener implements OnSkipListener {
        @Override
        public void onClick() {
            Log.i(TAG, "skip button click");
        }

        @Override
        public void onTimeEnd() {
            Log.i(TAG, "time end");
        }
}

// Ad listener, monitors callbacks for ad request timeout, loading completion (fill), display, click, exception, and close actions
private static class TAdListener extends AdListener {
            
            // Exception callback (applicable ad slots: all ad slots)
            @Override
            public void onError(TaErrorCode adError) {
                Log.d(TAG,"Ad failed callback");
            }
            
            // Loading completion callback (applicable ad slots: Splash, Interstitial, Banner, Reward)
            @Override
            public void onAdLoaded() {
                Log.d(TAG,"Ad loaded callback");
            }

            // Click callback (applicable ad slots: Splash, Interstitial, Banner, Reward)
            @Override
            public void onAdClicked() {
                Log.d(TAG,"Ad click callback");
            }

            // Display callback (applicable ad slots: Splash, Interstitial, Banner, Reward)
            @Override
            public void onAdShow() {
               Log.d(TAG,"Ad show callback");
            }

            // onTimeOut() is deprecated. The SDK combines the current request result with its ad cache when loading times out:
            // if no usable ad is available, onError(...) is called; if a usable ad has already been obtained, including from cache,
            // the load is treated as successful and onAdLoaded(...) is called instead of onError(...).
            @Override
            public void onTimeOut() {
                Log.d(TAG,"Ad request timeout callback");
            }

            // Close callback (applicable ad slots: Splash, Interstitial, Reward)
            @Override
            public void onAdClosed() {
                Log.d(TAG,"Ad close callback");
            }
}

If you want to add a sub-layout, such as displaying a logo and name at the bottom

/**
 * Optional
 * Allows the app to pass in a logo and name by adding a sub-layout
 * The SDK internally loads the sub-layout to render the media logo information at the bottom, the bottom area is 14% of the phone screen height (default)
 */
View logoLayout = LayoutInflater.from(this).inflate(R.layout.splash_logo_layout, null, false);
tSplashView.setLogoLayout(logoLayout);
// Optional: customize the logo area height ratio, range 0.1~0.2, default 0.14
tSplashView.setLogoLayoutHeightRatio(0.14f);

Activity: Please configure the corresponding parameters and callback listeners. Be sure to carefully review the documentation for the applicable ad placement types in relevant callbacks to avoid integration discrepancies.

// Initialize the splash ad object, where "splash_id" is the splash ad unit ID
TSplash tSplash = new TSplash(context, "splash_id");
// Set the ad listener
tSplash.setListener(new TAdListener());
// Listen for skip actions  
tSplash.setSkipListener(new TAdOnSkipListener());
// Load the ad
tSplash.loadAd();

// Example: 'Timeout mechanism'
new Handler(Looper.getMainLooper()).postDelayed(new Runnable() {
    @Override
    public void run() {
       // Execute navigation logic
    }
}, 3000);


// Splash skip action listener
private class TAdOnSkipListener implements OnSkipListener {
        @Override
        public void onClick() {
            Log.i(TAG, "skip button click");
        }

        @Override
        public void onTimeEnd() {
            Log.i(TAG, "time end");
        }
}

// Ad listener, monitors callbacks for ad request timeout, loading completion (fill), display, click, exception, and close actions
private static class TAdListener extends AdListener {
            
            // Exception callback (applicable ad slots: all ad slots)
            @Override
            public void onError(TaErrorCode adError) {
                Log.d(TAG,"Ad failed callback");
            }
            
            // Loading completion callback (applicable ad slots: Splash, Interstitial, Banner, Reward)
            @Override
            public void onAdLoaded() {
                Log.d(TAG,"Ad loaded callback");
            }

            // Click callback (applicable ad slots: Splash, Interstitial, Banner, Reward)
            @Override
            public void onAdClicked() {
                Log.d(TAG,"Ad click callback");
            }

            // Display callback (applicable ad slots: Splash, Interstitial, Banner, Reward)
            @Override
            public void onAdShow() {
               Log.d(TAG,"Ad show callback");
            }

            // onTimeOut() is deprecated. The SDK combines the current request result with its ad cache when loading times out:
            // if no usable ad is available, onError(...) is called; if a usable ad has already been obtained, including from cache,
            // the load is treated as successful and onAdLoaded(...) is called instead of onError(...).
            @Override
            public void onTimeOut() {
                Log.d(TAG,"Ad request timeout callback");
            }

            // Close callback (applicable ad slots: Splash, Interstitial, Reward)
            @Override
            public void onAdClosed() {
                Log.d(TAG,"Ad close callback");
            }
}

If you want to add a sub-layout, such as displaying a logo and name at the bottom

/**
 * Optional
 * Allows the app to pass in a logo and name by adding a sub-layout
 * The SDK internally loads the sub-layout to render the media logo information at the bottom, the bottom area is 14% of the phone screen height (default)
 */
View logoLayout = LayoutInflater.from(this).inflate(R.layout.splash_logo_layout, null, false);
tSplash.setLogoLayout(logoLayout);
// Optional: customize the logo area height ratio, range 0.1~0.2, default 0.14
tSplash.setLogoLayoutHeightRatio(0.14f);

Important Reminder

Scenario: When the splash ad is clicked and opened, and then returns to the main flow, the handling method for needing to jump to the home page is as follows:

Record the click status isClicked = true in a global variable in the ad listener onAdClicked(),
Perform the logic for jumping to the main page and removing the splash view in the lifecycle onResume() method.

View: Implementation as follows.

// Ad listener "onAdClicked()"
@Override
public void onAdClicked() {
   super.onAdClicked();
   isClicked = true;
   Log.d(TAG,"SplashAdActivity --> onAdClicked --> Ad clicked");
}

// Lifecycle "onResume()"
@Override
protected void onResume() {
    super.onResume();
    if (isClicked){
        // TODO Jump to home page
        ...
        // Remove splash view
        if (splashView!= null && tSplashView.getParent() != null){
            ((ViewGroup) tSplashView.getParent()).removeView(splashView);
        }
    }
}

Activity：No action required.

Display Ads

View: Please display the splash ad.

if (tSplashView != null) {
  tSplashView.show();
}

Activity：Please display the splash ad.

if (tSplash != null) {
  tSplash.show();
}

Destroy Ads

Please recycle ads promptly, otherwise the App may experience memory leaks.

View: Please destroy the ad view.

@Override
protected void onDestroy() {
    super.onDestroy();
    if (tSplashView != null) {
        tSplashView.destroy();
        tSplashView = null;
    }
}

Activity：Please destroy the ad object.

@Override
protected void onDestroy() {
    super.onDestroy();
    if (tSplash != null) {
        tSplash.destroy();
        tSplash = null;
    }
}

Other APIs

View：Details as follows.

API Call	Description
tSplashView.isReady()	Whether the current ad is loaded successfully and within the delivery period, if yes display, otherwise do not display
tSplashView.isOfflineAd()	Whether the current ad is offline
tSplashView.getFillAdType()	Whether the current filled ad is offline or online; 1: offline ad, 0: online ad, -1: no fill
tSplashView.getBidPrice()	Gets the effective bid price of the ad, in cents/eCPM

Activity：Details as follows.

API Call	Description
tSplash.isReady()	Whether the current ad is loaded successfully and within the delivery period, if yes display, otherwise do not display
tSplash.isOfflineAd()	Whether the current ad is offline
tSplash.getFillAdType()	Whether the current filled ad is offline or online; 1: offline ad, 0: online ad, -1: no fill
tSplash.getBidPrice()	Gets the effective bid price of the ad, in cents/eCPM

Splash

Introduction​

Integration Mode Comparison​

Build the Component​

Load Ads​

Display Ads​

Destroy Ads​

Other APIs​