Skip to content

Better splash screens: iOS SVG + continuous native Android splash#159

Open
unlocdavid wants to merge 1 commit into
NativePHP:mainfrom
unlocnl:feature/splashscreen-polish
Open

Better splash screens: iOS SVG + continuous native Android splash#159
unlocdavid wants to merge 1 commit into
NativePHP:mainfrom
unlocnl:feature/splashscreen-polish

Conversation

@unlocdavid

Copy link
Copy Markdown

Full disclosure: This PR is made with Claude Opus

I had some issues with splash screens. On Android the splash was fuzzy in some cases, maybe because of my UI scaling. And the native Android splash and NativePHP splash generated visual noise on boot.

I investigated if SVG would be an option, but it seems to only be reliable for iOS. So this PR adds support for splash.svg and splash-dark.svg only on iOS. If an SVG is found, it takes precedence over PNGs.

On Android 12+ there is a native splash screen of the app icon in a circle on a colored background. After the first loading of the app it jumped to the NativePHP configured PNG splash which waits for PHP etc. boots. This PR adds the option to hold the native splash and don't show the PNG. This solves two problems:

  • No fuzzy splash screens.
  • No jarring jump between splash screens. Especially in a release build, non-first boots can be very fast (yay!) but jumping between the two screens generates a lot of visual noise for the user. Using native in the config eliminates the jump.

Below is the description generated by Claude:


Summary

Two splash-screen improvements:

  • iOS accepts a native vector splash.svg (no rasterizer).
  • Android holds the system splash until the WebView is ready, eliminating the
    unbranded-system-splash → custom-overlay jump, with a new config to choose the style.

Android splash input remains PNG-only (an SVG→VectorDrawable path was explored and dropped as too unreliable).

iOS

  • public/splash.svg (+ optional splash-dark.svg) is written into LaunchImage.imageset
    as a vector asset (preserves-vector-representation). Invalid/missing SVG falls back to
    the existing PNG pipeline.

Android

  • Add androidx.core:core-splashscreen; installSplashScreen() +
    setKeepOnScreenCondition hold the system splash through boot in native style.
  • Generate Theme.AndroidPHP.Splash and point the app theme at it.
  • New android.splash config: style (image default | native), background,
    background_night (env: NATIVEPHP_ANDROID_SPLASH_*).
  • The system splash shows the app launcher icon in both styles. image keeps the
    full-bleed Compose overlay; native relies on the held system splash on API 31+, with
    the overlay as the fallback below 31.
  • Splash style/icon/background are applied at build time, so config changes take
    effect on rebuild (not just install).
  • Post-splash windowBackground tracks the splash color to avoid a white flash on handoff.
  • A @drawable/splash drawable is always guaranteed (shipped placeholder + app-icon/PNG
    fallback) so resource linking never fails.

Config

'splash' => [
    'style' => env('NATIVEPHP_ANDROID_SPLASH_STYLE', 'image'),
    'background' => env('NATIVEPHP_ANDROID_SPLASH_BACKGROUND', '#FFFFFF'),
    'background_night' => env('NATIVEPHP_ANDROID_SPLASH_BACKGROUND_NIGHT', '#000000'),
],

Old configs without this block fall back to image mode with white/black defaults.

Accept splash.svg on iOS as a native vector LaunchImage, and hold
Android's system splash until the WebView is ready to eliminate the
phase-1→phase-2 jump when configured.

iOS:
- Support public/splash.svg (+ splash-dark.svg) as a vector asset
(preserves-vector-representation); falls back to the PNG path.

Android:
- Add androidx.core:core-splashscreen; installSplashScreen() +
setKeepOnScreenCondition hold the system splash in native style.
- Generate Theme.AndroidPHP.Splash and point the app theme at it.
- New android.splash config: style (image|native), background,
background_night.
- System splash shows the app launcher icon in both styles; image
style keeps the full-bleed Compose overlay, native relies on the
held system splash (API 31+, overlay fallback below 31).
- Apply splash style/icon/background at build time so changes take
effect on rebuild, and set the post-splash windowBackground to the
splash color to avoid a white flash on handoff.
- Guarantee an @drawable/splash drawable (placeholder + app-icon/PNG
fallback) so resource linking never fails.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant