Splash Screen Customization

Control splash mode, background, and layered animations entirely through config.json.

Three Modes

Set splash.mode in config.json to choose how the splash behaves.

mode	Behaviour
`"builtin"` (default)	SDK-rendered splash — customize background and layer animations via config only
`"custom"`	SDK hides its UI. Your app provides its own launch screen and receives SDK init completion via `SdkInitState.onReady`
`"none"`	No splash — proceeds directly to main. SDK initialization runs in the background

builtin Mode — Layer Engine

Minimal Config (backward-compatible)

{
  "splash": {
    "backgroundColor": "#FFFFFF",
    "darkBackgroundColor": "#000000",
    "minDurationMs": 1500
  }
}

Existing configs work unchanged — splash_logo is shown centered with no animation.

Background Image

Set backgroundImage to display a full-bleed image instead of a solid color.

{
  "splash": {
    "backgroundImage": {
      "light": "splash_bg_light.png",
      "dark":  "splash_bg_dark.png"
    },
    "minDurationMs": 1500
  }
}

Place images in assets/ (Android) or Asset Catalog / bundle (iOS).
Either light or dark alone is fine — the missing side falls back to the other.
When backgroundImage is set, backgroundColor is ignored.

Layer Engine (`layers[]`)

Display multiple images with staggered entrance animations.

{
  "splash": {
    "mode": "builtin",
    "backgroundImage": {
      "light": "splash_bg_light.png",
      "dark":  "splash_bg_dark.png"
    },
    "layers": [
      {
        "image": "splash_character.png",
        "scaleType": "fill",
        "appearAtMs": 0,
        "anim": "fade",
        "durationMs": 500
      },
      {
        "image": { "light": "splash_logo_light.png", "dark": "splash_logo_dark.png" },
        "scaleType": "fill",
        "appearAtMs": 700,
        "anim": "fadeUp",
        "durationMs": 500,
        "endsSplash": true
      }
    ],
    "minDurationMs": 2000
  }
}

Layer Field Reference

Field	Type	Default	Description
`image`	`string \| { light, dark }`	—	Image filename — plain string or per-mode object
`scaleType`	`"fill" \| "fit" \| "center"`	`"fill"`	How the image fills its full-screen frame
`appearAtMs`	`number`	`0`	Delay after splash start before this layer appears (ms)
`anim`	`"fade" \| "fadeUp" \| "fadeDown" \| "scale" \| "none"`	`"fade"`	Entrance animation
`durationMs`	`number`	`400`	Animation duration (ms)
`endsSplash`	`boolean`	`false`	When `true`, the splash exit gate opens once this layer's animation completes

`scaleType` Details

Value	Android	iOS	Use case
`"fill"` (default)	`CENTER_CROP`	`.scaleAspectFill`	Full-bleed canvas matching the background
`"fit"`	`FIT_CENTER`	`.scaleAspectFit`	Small icons/logos — whole image visible, letterbox
`"center"`	`CENTER`	`.center`	Original size, centered, no scale

Design layers on the same canvas as the background (e.g. 1080×2400). With scaleType: "fill", both background and layers crop identically on every device aspect ratio, so they align perfectly.

Exit Timing

The splash dismisses when all three conditions are met — whichever is latest:

The endsSplash: true layer's animation completes (appearAtMs + durationMs)
minDurationMs has elapsed
SDK initialization (license check + remote config) is complete

If no layer has endsSplash: true, condition 1 is skipped.

When Android's animatorDurationScale is 0 or iOS Reduce Motion is enabled, layer animations are skipped and the final state is applied instantly. No code changes needed. WCAG 2.1 §2.3.3 compliant automatically.

White Flash Prevention (`carryOverBackground`)

Prevents the brief white background flash that appears between splash exit and the first web page paint.

Enabled by default — simply set backgroundColor and it works automatically. Opt out only when needed.

{
  "splash": {
    "backgroundColor": "#1A1A2E",
    "carryOverBackground": false
  }
}

carryOverBackground only applies in mode: "builtin". In custom and none modes the app manages its own background.

custom Mode

The SDK draws no splash UI. Your app provides its own launch screen.

{
  "splash": { "mode": "custom" }
}

Listen for SDK init completion via SdkInitState:

Android (Kotlin):

class MyCustomSplashActivity : SplashActivity() {
    override fun onSplashStart() {
        showMySplash()
        SdkInitState.onReady { isLicensed ->
            hideMySplash()
            onCustomTaskDone()   // signal SplashActivity to proceed
        }
    }
}

iOS (Swift):

SdkInitState.shared.onReady { isLicensed in
    DispatchQueue.main.async {
        self.hideMySplash()
        self.proceedToMain()
    }
}

You must call onCustomTaskDone() (Android) or your own proceed logic (iOS) — otherwise the app will stay on the splash screen indefinitely.

none Mode

No splash screen. The app goes directly to main; SDK initialization runs in the background.

{
  "splash": { "mode": "none" }
}

minDurationMs is ignored in none mode.

Design Guide

Full-Bleed Canvas Layout

Authoring layers on the same canvas as the background ensures perfect alignment on every device.

Canvas: 1080 × 2400 (Android) / 1290 × 2796 (iPhone 15 Pro)
┌─────────────────────┐
│   ↑ top crop zone   │  may be cropped on taller screens
│                     │
│  ★ key content here │  ← keep within center 60–70%
│  (character, logo)  │
│                     │
│   ↓ bot crop zone   │  may be cropped on taller screens
└─────────────────────┘

Both background and layers crop the same way under scaleType: "fill", so elements in the safe center zone remain visible on all devices.

Recommended File Formats

Platform	Format
Android	`.png` / `.webp` (inside `assets/`)
iOS	Asset Catalog (`.imageset`) or bundle `.png`

Complete config.json Example

{
  "splash": {
    "mode": "builtin",
    "backgroundColor": "#FFFFFF",
    "darkBackgroundColor": "#000000",
    "backgroundImage": {
      "light": "splash_bg_light.png",
      "dark":  "splash_bg_dark.png"
    },
    "layers": [
      {
        "image": "splash_character.png",
        "scaleType": "fill",
        "appearAtMs": 0,
        "anim": "fade",
        "durationMs": 500
      },
      {
        "image": {
          "light": "splash_logo_dark.png",
          "dark":  "splash_logo_light.png"
        },
        "scaleType": "fill",
        "appearAtMs": 700,
        "anim": "fadeUp",
        "durationMs": 500,
        "endsSplash": true
      }
    ],
    "minDurationMs": 2000,
    "carryOverBackground": true
  }
}