SplashScreenManager allows you to override control of the app’s native splash screen lifecycle, so you can force it to remain visible until it is explicitly hidden.
Splash screens can be either static or animated. Both cases are achieved with .png images.
Assets
Splash screen assets are picked up by the native animation service on app launch. In order to configure them to be picked up, splash screen frame(s) need to be compressed into a .zip file along with a descriptor file.Images
Mandatory Naming Conventions All splash screen images must follow this exact naming format:- Format:
loopXXXXX.png- Where XXXXX is a 5-digit number starting from 00000
- Numbers must be zero-padded
Common mistakes to avoid
- image0.png (incorrect naming)
- loop1.png (missing zero padding)
- loop_00001.png (incorrect underscore)
- LOOP00001.png (incorrect capitalization)
- Use .png image(s)
- Single .png image for a static splash screen
- Multiple .png images for an animated splash screen
- Imag naming must follow the specified naming convention
- Put your image(s) in a folder named _loop
- Even if you only have one image, it needs to be put into _loop
- To play the animation once and then hold on its final frame, split the frames across two folders instead. See Play once and hold the last frame.
- Supported image resolutions
- Multimodal profile: 960x480
- TV profile: 1920x1080
Example
Descriptor file
A descriptor file is needed to give the animation service some information about the native splash screen. Data such as image dimensions, fps, and settings for the splash screen can be specified here. This descriptor file will be compressed with your image folder or folders into a .zip for the animation service to pick up. To create a descriptor file, create a new .txt file and follow the instructions below:- Name your descriptor file desc.txt
- First line should be image width, image height and desired fps separated by spaces
- Each line after the first describes one part of the animation, in the form
TYPE COUNT PAUSE FOLDER:TYPE:ckeeps the assets after it is done looping.pplays the part once and then continues to the next part.COUNT: for acpart,0loops infinitely until terminated. See the following warning before using any other value.PAUSE: fps delay until next command (not relevant for splash screen)FOLDER: name of the folder holding that part’s images
Loop continuously
The following example sets the width to 480, the height to 128, and the fps to 30. The singlec 0 0 _loop part loops the frames in _loop until the splash screen is dismissed.
Play once and hold the last frame
To play the animation exactly once and then hold on its final frame, split your images across two folders and give the descriptor two parts:_animholds the animation frames_holdholds a single image, which is a copy of the final frame of_anim
p 1 0 _animplays the frames in _anim once, then continues to the next partc 0 0 _holddisplays the single frame in _hold and holds it
usePreventHideSplashScreen() and useHideSplashScreenCallback() to control when that happens, as shown in Usage.
Use the same image naming convention inside both folders. The following example shows the folder layout.
SplashScreenImages.zip
- From your Terminal, navigate to the directory where your image folder or folders and desc.txt are located
- Run
zip SplashScreenImages.zip _loop/* desc.txtto createSplashScreenImages.zip
zip from the command line on the two individual items to avoid this issue.
Example
Example: play once and hold the last frame
For the two-part descriptor, list the folders in playback order so that _anim is added to the archive before _hold:Placement in Package
- If it does not exist, create directory:
- Place
SplashScreenImages.zipinside
Example
Usage
The following example shows the typical usage of the splash screen manager. The code usesKitchenSinkApp as a place holder component name. When implementing your splash screen, replace this with the appropriate component name.
Reference
Methods
preventAutoHideAsync()
Replaced by theusePreventHideSplashScreen() hook.
hideAsync(moduleName) is explicitly invoked.
For Vega SDK app developers, the moduleName parameter maps to the name field in your app’s app.json file.
Users of this API are recommended to call it in global scope. Calling this in a React component or hook could lead to bugs if it causes this API to be called after the splash screen is already dismissed.
hideAsync()
Replaced by theuseHideSplashScreenCallback() hook.
moduleName parameter maps to the name field in your app’s app.json file.
usePreventHideSplashScreen()
useHideSplashScreenCallback()
useEffect hook.
