> ## Documentation Index
> Fetch the complete documentation index at: https://docs.adrop.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Splash Ads

> Learn how to implement splash ads in your Android app.

## Overview

Splash Ads are advertisements displayed on the splash screen when the app launches. The ad is shown alongside your app's logo, providing a natural user experience.

### Features

* Natural ad exposure at app launch
* Maintains brand image with app logo
* 360dp × 270dp ad area, 288dp × 288dp logo area
* Image ad support
* Android 12+ system splash screen support

<Note>
  Use the test unit ID during development: `PUBLIC_TEST_UNIT_ID_SPLASH`
</Note>

***

## Caching Behavior

Splash ads are prefetched and cached on the device so the creative can appear instantly at launch, before any network request completes. On the next launch the cached creative is shown first, and a fresh ad request runs in the background to refresh the cache for subsequent launches.

<Warning>
  Because of this prefetch model, a creative that is **paused** in Ad Control Console may still be shown from the device cache until the next refresh cycle completes on each user's device. Plan creative pauses and replacements with a buffer for the cache to roll over across the install base.
</Warning>

***

## Ad and Logo Sizes

Splash ads use predefined areas:

* **Logo area**: 288dp × 288dp (center of screen)
* **Ad area**: 360dp × 270dp (bottom of screen)
* The ad is displayed at the bottom of the screen, with the app logo positioned at the top

***

## Implementation Methods

Splash ads can be implemented in two ways depending on your app's requirements:

1. **Using AdropSplashAd** - Integrates with system splash screen (Android 12+)
2. **Using AdropSplashAdView** - Custom splash screen configuration

***

## Method 1: Using AdropSplashAd (System Splash Integration)

This method integrates with the system splash screen on Android 12 (API 31) and above. `AdropSplashAdActivity` automatically manages the splash screen.

### Step 1: Configure strings.xml

Add the following settings to `app/src/main/res/values/strings.xml`.

```xml title="res/values/strings.xml" theme={null}
<resources>
    <!-- App name -->
    <string name="app_name">My App</string>

    <!-- Splash ad unit ID -->
    <string name="adrop_splash_ad_unit_id" translatable="false">YOUR_SPLASH_UNIT_ID</string>

    <!-- Activity to navigate to after splash ends -->
    <string name="adrop_splash_ad_next_activity" translatable="false">com.yourcompany.yourapp.MainActivity</string>
</resources>
```

<Note>
  Use `PUBLIC_TEST_UNIT_ID_SPLASH` instead of `YOUR_SPLASH_UNIT_ID` for testing.
</Note>

### Step 2: Add Splash Logo Image

Add your app logo to the `res/drawable/` folder.

```
app/src/main/res/drawable/splash_logo.png
```

Recommended size: 288dp × 288dp (@2x: 576px, @3x: 864px)

### Step 3: Configure AndroidManifest.xml

Set `AdropSplashAdActivity` as the launcher activity.

```xml title="AndroidManifest.xml" theme={null}
<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <application
        android:name=".MyApplication"
        android:theme="@style/Theme.App">

        <!-- Splash Ad Activity -->
        <activity
            android:name="io.adrop.ads.splash.AdropSplashAdActivity"
            android:theme="@style/Theme.App.Splash"
            android:exported="true">
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>

        <!-- Main Activity (navigates here after splash ends) -->
        <activity
            android:name=".MainActivity"
            android:exported="false" />

    </application>
</manifest>
```

<Warning>
  `android:exported="true"` is required for `AdropSplashAdActivity`.
</Warning>

### Step 4: Configure Splash Theme

Add the splash theme to `res/values/themes.xml`.

```xml title="res/values/themes.xml" theme={null}
<resources>
    <!-- App default theme -->
    <style name="Theme.App" parent="Theme.Material3.DayNight.NoActionBar">
        <!-- App theme settings -->
    </style>

    <!-- Splash theme (Android 12+) -->
    <style name="Theme.App.Splash" parent="Theme.SplashScreen">
        <item name="windowSplashScreenBackground">@color/white</item>
        <item name="windowSplashScreenAnimatedIcon">@drawable/splash_logo</item>
        <item name="postSplashScreenTheme">@style/Theme.App</item>
    </style>
</resources>
```

<Note>
  On devices below Android 12, the system splash is not displayed and `AdropSplashAdActivity` is shown directly.
</Note>

### Step 5: Customize Layout (Optional)

If you want to use a custom layout instead of the default, create `activity_adrop_splash_ad.xml` in your app's `res/layout/` folder.

```xml title="res/layout/activity_adrop_splash_ad.xml" theme={null}
<?xml version="1.0" encoding="utf-8"?>
<RelativeLayout
    xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:background="#ffffff"
    android:paddingHorizontal="24dp"
    android:fitsSystemWindows="true">

    <!-- App logo (center) -->
    <ImageView
        android:src="@drawable/splash_logo"
        android:layout_width="288dp"
        android:layout_height="288dp"
        android:scaleType="fitXY"
        android:layout_centerInParent="true"/>

    <!-- Ad area (bottom) - Required -->
    <ImageView
        android:id="@+id/adrop_splash_ad_image"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:layout_centerHorizontal="true"
        android:layout_alignParentBottom="true"/>
</RelativeLayout>
```

<Warning>
  An `ImageView` with `android:id="@+id/adrop_splash_ad_image"` is required. The ad will be displayed in this view.
</Warning>

### Step 6: Initialize SDK in Application

```kotlin title="MyApplication.kt" theme={null}
import android.app.Application
import io.adrop.ads.Adrop

class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()

        // Initialize SDK
        Adrop.initialize(this, production = false)
    }
}
```

### Step 7: Implement AdropSplashAd Listener (Optional)

To receive splash ad events, set up a listener in your `Application` class.

<CodeGroup>
  ```kotlin Kotlin theme={null}
  import android.app.Application
  import io.adrop.ads.Adrop
  import io.adrop.ads.splash.AdropSplashAd
  import io.adrop.ads.splash.AdropSplashAdListener
  import io.adrop.ads.model.AdropErrorCode

  class MyApplication : Application() {
      private lateinit var splashAd: AdropSplashAd

      override fun onCreate() {
          super.onCreate()

          // Initialize SDK
          Adrop.initialize(this, production = false)

          // Configure splash ad
          splashAd = AdropSplashAd(this) { splashAd ->
              // shouldSkip: Determines whether to skip splash ad
              // Return true to skip the ad and go directly to the main screen
              checkShouldSkipSplash()
          }

          splashAd.splashAdListener = object : AdropSplashAdListener {
              override fun onAdReceived(ad: AdropSplashAd) {
                  println("Splash ad received successfully")
              }

              override fun onAdFailedToReceive(ad: AdropSplashAd, errorCode: AdropErrorCode) {
                  println("Failed to receive splash ad: $errorCode")
              }

              override fun onAdImpression(ad: AdropSplashAd) {
                  println("Splash ad impression")
              }

              override fun onAdClose(ad: AdropSplashAd, impressed: Boolean) {
                  println("Splash ad closed - impressed: $impressed")
              }
          }
      }

      private fun checkShouldSkipSplash(): Boolean {
          // Example: Skip splash when entering via deep link or under certain conditions
          // Such as when the app is launched via push notification
          return false
      }
  }
  ```

  ```java Java theme={null}
  import android.app.Application;
  import io.adrop.ads.Adrop;
  import io.adrop.ads.splash.AdropSplashAd;
  import io.adrop.ads.splash.AdropSplashAdListener;
  import io.adrop.ads.model.AdropErrorCode;

  public class MyApplication extends Application {
      private AdropSplashAd splashAd;

      @Override
      public void onCreate() {
          super.onCreate();

          // Initialize SDK
          Adrop.INSTANCE.initialize(this, false, new String[]{});

          // Configure splash ad
          splashAd = new AdropSplashAd(this, ad -> checkShouldSkipSplash());

          splashAd.setSplashAdListener(new AdropSplashAdListener() {
              @Override
              public void onAdReceived(AdropSplashAd ad) {
                  System.out.println("Splash ad received successfully");
              }

              @Override
              public void onAdFailedToReceive(AdropSplashAd ad, AdropErrorCode errorCode) {
                  System.out.println("Failed to receive splash ad: " + errorCode);
              }

              @Override
              public void onAdImpression(AdropSplashAd ad) {
                  System.out.println("Splash ad impression");
              }

              @Override
              public void onAdClose(AdropSplashAd ad, boolean impressed) {
                  System.out.println("Splash ad closed - impressed: " + impressed);
              }
          });
      }

      private boolean checkShouldSkipSplash() {
          // Determine whether to skip splash ad
          return false;
      }
  }
  ```
</CodeGroup>

### AdropSplashAd Properties

| Property      | Type      | Description                                |
| ------------- | --------- | ------------------------------------------ |
| `unitId`      | `String`  | Ad unit ID (read-only)                     |
| `creativeId`  | `String`  | Ad creative ID (read-only)                 |
| `isClosed`    | `Boolean` | Whether splash ad is closed (read-only)    |
| `isDestroyed` | `Boolean` | Whether splash ad is destroyed (read-only) |

### AdropSplashAd Methods

| Method      | Description                                                                                      |
| ----------- | ------------------------------------------------------------------------------------------------ |
| `close()`   | Immediately closes splash ad and navigates to next screen                                        |
| `destroy()` | Releases resources and unregisters lifecycle callbacks. Call when splash ad is no longer needed. |

### shouldSkip Callback

Use the `shouldSkip` callback in the `AdropSplashAd` constructor to skip splash ads under certain conditions.

```kotlin theme={null}
val splashAd = AdropSplashAd(application) { splashAd ->
    // Skip splash when app is launched via push notification
    val isPushNotification = intent?.extras?.containsKey("push_notification") == true

    // Skip splash when entering via deep link
    val hasDeepLink = intent?.data != null

    isPushNotification || hasDeepLink
}
```

<Note>
  When `shouldSkip` returns `true`, the splash ad is immediately closed and navigates to the next screen.
</Note>

### Configure Splash Display Duration (Optional)

To change the default display duration (2 seconds), create `res/values/integers.xml` file and configure it.

```xml title="res/values/integers.xml" theme={null}
<resources>
    <!-- Ad request timeout (milliseconds, 500~3000) -->
    <integer name="adrop_splash_ad_request_timeout">1000</integer>

    <!-- Ad display duration (milliseconds, 500~3000) -->
    <integer name="adrop_splash_ad_max_timeout">2000</integer>
</resources>
```

<Note>
  The configurable range is 500ms to 3000ms. Values outside this range are automatically corrected.
</Note>

### Skip Splash on Push Notification Deep Link (Optional)

You can configure to skip splash ads when the app is launched via push notification with a deep link.

```xml title="res/values/bools.xml" theme={null}
<resources>
    <!-- Skip splash on push notification deep link -->
    <bool name="adrop_splash_ad_skip_push_notification_clicked">true</bool>
</resources>
```

***

## Method 2: Using AdropSplashAdView (Custom Splash)

Use this when you want to configure a custom splash screen yourself. Create your own splash Activity and place `AdropSplashAdView`.

### Step 1: Create Layout

```xml title="activity_splash.xml" theme={null}
<?xml version="1.0" encoding="utf-8"?>
<RelativeLayout
    xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:background="#ffffff"
    android:padding="24dp">

    <!-- App logo -->
    <ImageView
        android:id="@+id/logo"
        android:layout_width="288dp"
        android:layout_height="288dp"
        android:layout_centerInParent="true"
        android:src="@drawable/splash_logo"
        android:scaleType="fitXY"/>

    <!-- Splash ad container -->
    <FrameLayout
        android:id="@+id/splash_ad_container"
        android:layout_width="match_parent"
        android:layout_height="270dp"
        android:layout_alignParentBottom="true"/>

</RelativeLayout>
```

### Step 2: Implement SplashActivity

<CodeGroup>
  ```kotlin Kotlin theme={null}
  import android.content.Intent
  import android.os.Bundle
  import android.widget.FrameLayout
  import androidx.appcompat.app.AppCompatActivity
  import io.adrop.ads.splash.AdropSplashAdView
  import io.adrop.ads.splash.AdropSplashAdViewListener
  import io.adrop.ads.model.AdropErrorCode

  class SplashActivity : AppCompatActivity() {
      private lateinit var splashAdView: AdropSplashAdView

      override fun onCreate(savedInstanceState: Bundle?) {
          super.onCreate(savedInstanceState)
          setContentView(R.layout.activity_splash)

          // Initialize splash ad view
          splashAdView = AdropSplashAdView(
              context = this,
              unitId = "YOUR_SPLASH_UNIT_ID",
              adRequestTimeout = 1000L  // Ad request timeout (milliseconds)
          )

          // Set listener
          splashAdView.listener = object : AdropSplashAdViewListener {
              override fun onAdReceived(ad: AdropSplashAdView) {
                  println("Splash ad received successfully")
              }

              override fun onAdFailedToReceive(ad: AdropSplashAdView, errorCode: AdropErrorCode) {
                  println("Failed to receive splash ad: $errorCode")
              }

              override fun onAdImpression(ad: AdropSplashAdView) {
                  println("Splash ad impression")
              }

              override fun onAdClose(ad: AdropSplashAdView, impressed: Boolean) {
                  println("Splash ad closed - impressed: $impressed")
                  goToMainActivity()
              }
          }

          // Load and display ad
          findViewById<FrameLayout>(R.id.splash_ad_container).addView(splashAdView)
          splashAdView.load()
      }

      private fun goToMainActivity() {
          startActivity(Intent(this, MainActivity::class.java))
          finish()
      }
  }
  ```

  ```java Java theme={null}
  import android.content.Intent;
  import android.os.Bundle;
  import android.widget.FrameLayout;
  import androidx.appcompat.app.AppCompatActivity;
  import io.adrop.ads.splash.AdropSplashAdView;
  import io.adrop.ads.splash.AdropSplashAdViewListener;
  import io.adrop.ads.model.AdropErrorCode;

  public class SplashActivity extends AppCompatActivity {
      private AdropSplashAdView splashAdView;

      @Override
      protected void onCreate(Bundle savedInstanceState) {
          super.onCreate(savedInstanceState);
          setContentView(R.layout.activity_splash);

          // Initialize splash ad view
          splashAdView = new AdropSplashAdView(
              this,
              "YOUR_SPLASH_UNIT_ID",
              1000L  // Ad request timeout (milliseconds)
          );

          // Set listener
          splashAdView.setListener(new AdropSplashAdViewListener() {
              @Override
              public void onAdReceived(AdropSplashAdView ad) {
                  System.out.println("Splash ad received successfully");
              }

              @Override
              public void onAdFailedToReceive(AdropSplashAdView ad, AdropErrorCode errorCode) {
                  System.out.println("Failed to receive splash ad: " + errorCode);
              }

              @Override
              public void onAdImpression(AdropSplashAdView ad) {
                  System.out.println("Splash ad impression");
              }

              @Override
              public void onAdClose(AdropSplashAdView ad, boolean impressed) {
                  System.out.println("Splash ad closed - impressed: " + impressed);
                  goToMainActivity();
              }
          });

          // Load and display ad
          FrameLayout container = findViewById(R.id.splash_ad_container);
          container.addView(splashAdView);
          splashAdView.load();
      }

      private void goToMainActivity() {
          startActivity(new Intent(this, MainActivity.class));
          finish();
      }
  }
  ```
</CodeGroup>

### Step 3: Configure AndroidManifest.xml

```xml title="AndroidManifest.xml" theme={null}
<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <application>
        <!-- Custom Splash Activity -->
        <activity
            android:name=".SplashActivity"
            android:theme="@style/Theme.App.Splash"
            android:exported="true">
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>

        <!-- Main Activity -->
        <activity
            android:name=".MainActivity"
            android:exported="false" />
    </application>
</manifest>
```

### AdropSplashAdView Properties

| Property     | Type      | Description                             |
| ------------ | --------- | --------------------------------------- |
| `unitId`     | `String`  | Ad unit ID (read-only)                  |
| `creativeId` | `String`  | Ad creative ID (read-only)              |
| `isClosed`   | `Boolean` | Whether splash ad is closed (read-only) |
| `txId`       | `String`  | Transaction ID (read-only)              |
| `campaignId` | `String`  | Campaign ID (read-only)                 |

### AdropSplashAdView Methods

| Method      | Description                                                                                              |
| ----------- | -------------------------------------------------------------------------------------------------------- |
| `load()`    | Loads and displays the ad                                                                                |
| `destroy()` | Releases resources (timers, visibility tracker, listener). Call when splash ad view is no longer needed. |

***

## Listeners

### AdropSplashAdListener

Listener for when using `AdropSplashAd`.

| Method                               | Required     | Description                             |
| ------------------------------------ | ------------ | --------------------------------------- |
| `onAdReceived(ad)`                   | Optional     | Called when ad is received successfully |
| `onAdFailedToReceive(ad, errorCode)` | Optional     | Called when ad fails to load            |
| `onAdImpression(ad)`                 | Optional     | Called when ad impression is recorded   |
| `onAdClose(ad, impressed)`           | **Required** | Called when splash ad closes            |

### AdropSplashAdViewListener

Listener for when using `AdropSplashAdView`.

| Method                               | Required     | Description                                                      |
| ------------------------------------ | ------------ | ---------------------------------------------------------------- |
| `onAdReceived(ad)`                   | Optional     | Called when ad is received successfully                          |
| `onAdFailedToReceive(ad, errorCode)` | Optional     | Called when ad fails to load                                     |
| `onAdImpression(ad)`                 | Optional     | Called when ad impression is recorded                            |
| `onAdClose(ad, impressed)`           | **Required** | Called when splash ad closes. Must handle main screen transition |

<Warning>
  When using `AdropSplashAdView`, you must implement the `onAdClose` method to handle the transition to the main screen.
</Warning>

***

## impressed Parameter

The `impressed` parameter in `onAdClose(ad, impressed)` indicates whether the ad was actually displayed.

```kotlin theme={null}
override fun onAdClose(ad: AdropSplashAdView, impressed: Boolean) {
    if (impressed) {
        println("Ad was displayed to user")
        // Post-impression logic
    } else {
        println("Ad was not displayed (load failure or skip)")
        // Non-impression handling logic
    }

    // Navigate to main screen
    goToMainActivity()
}
```

### Cases When impressed is false

* Ad load failure
* Network error
* User skipped before viewing ad
* Insufficient ad inventory

***

## Best Practices

### 1. Set Appropriate Timers

Splash ads should not be displayed too short or too long.

```xml theme={null}
<!-- Recommended settings -->
<integer name="adrop_splash_ad_request_timeout">1000</integer>  <!-- 1 second -->
<integer name="adrop_splash_ad_max_timeout">2000</integer>       <!-- 2 seconds -->
```

### 2. Optimize Logo Image

Prepare your app logo in appropriate sizes to minimize loading time.

```
drawable-mdpi/splash_logo.png    (192px × 192px)
drawable-hdpi/splash_logo.png    (288px × 288px)
drawable-xhdpi/splash_logo.png   (384px × 384px)
drawable-xxhdpi/splash_logo.png  (576px × 576px)
drawable-xxxhdpi/splash_logo.png (768px × 768px)
```

### 3. Handle Failures

Ensure the app starts normally even when ad loading fails.

```kotlin theme={null}
override fun onAdFailedToReceive(ad: AdropSplashAdView, errorCode: AdropErrorCode) {
    println("Ad load failed: $errorCode")
    // Navigate to main screen even on failure
    goToMainActivity()
}
```

### 4. Distinguish Test Environment

Distinguish between development and production environments for testing.

```kotlin theme={null}
val splashUnitId = if (BuildConfig.DEBUG) {
    "PUBLIC_TEST_UNIT_ID_SPLASH"
} else {
    "YOUR_PRODUCTION_SPLASH_UNIT_ID"
}

// Initialize SDK
Adrop.initialize(application, production = !BuildConfig.DEBUG)
```

### 5. Prevent Memory Leaks

Clean up listeners when Activity is destroyed.

```kotlin theme={null}
override fun onDestroy() {
    splashAdView.destroy()
    super.onDestroy()
}
```

***

## Testing

### Test Unit ID

Use the test unit ID during development.

```kotlin theme={null}
// Test unit ID
val testUnitId = "PUBLIC_TEST_UNIT_ID_SPLASH"
```

<Warning>
  Be sure to use the actual unit ID created in the Adrop console for production deployment. Deploying with test unit IDs will not generate ad revenue.
</Warning>

### Debugging

Check ad events with logs.

```kotlin theme={null}
splashAdView.listener = object : AdropSplashAdViewListener {
    override fun onAdReceived(ad: AdropSplashAdView) {
        Log.d("AdropSplash", "Ad received successfully")
        Log.d("AdropSplash", "  - unitId: ${ad.unitId}")
        Log.d("AdropSplash", "  - creativeId: ${ad.creativeId}")
    }

    override fun onAdFailedToReceive(ad: AdropSplashAdView, errorCode: AdropErrorCode) {
        Log.e("AdropSplash", "Ad receive failed: $errorCode")
        Log.e("AdropSplash", "  - Check network status")
        Log.e("AdropSplash", "  - Verify unit ID: ${ad.unitId}")
    }

    override fun onAdImpression(ad: AdropSplashAdView) {
        Log.d("AdropSplash", "Ad impression")
        Log.d("AdropSplash", "  - txId: ${ad.txId}")
        Log.d("AdropSplash", "  - campaignId: ${ad.campaignId}")
    }

    override fun onAdClose(ad: AdropSplashAdView, impressed: Boolean) {
        Log.d("AdropSplash", "Ad closed")
        Log.d("AdropSplash", "  - impressed: $impressed")
        Log.d("AdropSplash", "  - isClosed: ${ad.isClosed}")
    }
}
```

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Splash screen is not displayed">
    * Verify that `AdropSplashAdActivity` or custom SplashActivity is set as LAUNCHER in AndroidManifest.xml
    * Check `android:exported="true"` setting
    * Verify SDK initialization is complete (Application class)
    * Check that `adrop_service.json` file is in the `assets` folder
  </Accordion>

  <Accordion title="Ad is not loading">
    * Check network connection status
    * Verify the unit ID is correct (strings.xml or code)
    * Verify `production = false` setting in test environment
    * Check `onAdFailedToReceive` error code
    * Verify `adrop_service.json` file content is correct
  </Accordion>

  <Accordion title="Not transitioning to main screen">
    * Verify `adrop_splash_ad_next_activity` setting is correct (full package path)
    * Check `onAdClose` implementation when using `AdropSplashAdView`
    * Verify Activity's full qualified name (e.g., com.myapp.MainActivity)
  </Accordion>

  <Accordion title="Custom layout is not applied">
    * Verify filename is exactly `activity_adrop_splash_ad.xml`
    * Check that an ImageView with `android:id="@+id/adrop_splash_ad_image"` ID exists
    * Clean build and re-run the app (Build > Clean Project > Rebuild Project)
  </Accordion>

  <Accordion title="System splash not visible on devices below Android 12">
    This is normal. The system splash screen is not supported on devices below Android 12, and `AdropSplashAdActivity` is displayed directly.
  </Accordion>
</AccordionGroup>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Interstitial Ads" href="/sdk/android/interstitial">
    Display full-screen ads during screen transitions
  </Card>

  <Card title="Banner Ads" href="/sdk/android/banner">
    Implement banner ads
  </Card>

  <Card title="Native Ads" href="/sdk/android/native">
    Custom design native ads
  </Card>

  <Card title="Rewarded Ads" href="/sdk/android/rewarded">
    Provide user rewards
  </Card>
</CardGroup>