Cobalt Splash Screen

Startup splash screen sequence

There can be up to three splash screens shown when launching web applications on Cobalt:

  • one from the system
  • one from Cobalt
  • one from the web application itself

The system splash screen is often a transition from the application icon on the home screen to a static asset dictated by the platform (which is outside of Cobalt's control). The Cobalt splash screen is shown as soon as Cobalt can render until the web application is loaded. The web application splash screen is the HTML content shown immediately upon loading the web application (this may resemble a typical splash screen, but it really can be whatever the application chooses to show on starting).

Cobalt splash screen priority order

The Cobalt splash screen must be specified as a URL to a document. The document must be either self-contained or all of its references must be local. That means the document should not reference any external CSS, JavaScript, or image files, for example. This simplifies the caching process so that only a single document must be cached without tracing references. All fallback splash screens must refer to local documents. This is so the fallback splash screen can be shown without latency and even when there is no network available. Specifically, the fallback splash screen URL and its references should start with either file:/// or h5vcc-embedded://. Additionally none can be used to specify that no Cobalt splash screen should be constructed; the system splash sequence transitions directly into the application splash sequence once the page is loaded.

The Cobalt splash screen is one of the following, in order of precedence:

  1. Web cached splash screen: If a splash screen specified by a web application is cached from a previous instance of Cobalt, it will be loaded at startup. The key for the cache splash screen is based on host & path of the initial URL with no query or hash. If network connectivity is available at startup, when the initial web application URL is processed, a custom rel="splashscreen" attribute of the link element is used to specify and cache the splashscreen URL for future runs.

  2. Command line fallback splash screen: This is specified as a command line argument --fallback_splash_screen_url via the system and used when cache is unavailable. This is the case when there is no local cache storage, cache has been cleared, or the application is started for the first time.

  3. Build-time fallback splash screen: If a web cached splash screen is unavailable and command line parameters are not passed by the system, a gyp_configuration.gypi fallback splash screen may be used. Porters should set the gypi variable fallback_splash_screen_url to the splash screen URL.

  4. Default splash screen: If no web cached splash screen is available, and command line and gyp_configuration.gypi fallbacks are not set, a default splash screen will be used. This is set in base.gypi via fallback_splash_screen_url% to refer to a black splash screen.

Web-updatability

Since Cobalt parses the link element's rel="splashscreen" attribute for the splash screen URL in the content fetched from the initial URL, an application developer may update the splash screen by changing that attribute in the link element. On the next load of the application, the new splash screen will be cached, and on the subsequent load of the application, the new cached splash screen will be shown.

For example, the document at the initial URL could contain

<link rel="splashscreen" href="https://www.example.com/self-contained.html">

where "https://www.example.com/self-contained.html" is the address of some self-contained splash screen document. The document must not violate the Content Security Policy. The splash screen is treated as a script resource by the CSP.

Caching implementation requirements

In order to cache the application-provided splash screen, Cobalt will attempt to create directories and write files into the directory returned from a call to SbSystemGetPath(kSbSystemPathCacheDirectory, ...). Cobalt will expect the data that it writes into that directory to persist across process instances. Cobalt will also need to read the cached splash screen from the cache directory when starting up.

Application-specific splash screens

On systems that plan to support multiple Cobalt-based applications, an application developer may wish to use the command line arguments for the fallback splash screen to display different Cobalt splash screens for different applications. The logic for passing in these different command line arguments to the Cobalt binary must be handled by the system.

Alternatively, an application developer may use the default black splash screen specified in base.gypi whenever a cached splash screen is not available and rely on the web application to specify an application-specific cached splash screen otherwise.

Provided embedded resource splash screens

For convenience, we currently provide the following splash screens as embedded resources:

  • h5vcc-embedded://black_splash_screen.html - a black splash screen
  • h5vcc-embedded://cobalt_splash_screen.html - a splash screen showing the Cobalt logo