onDemandResources.*

Type Library
Revision Release 2024.3703
Keywords on-demand resources, onDemandResources
Platforms tvOS, iOS
See also Apple TV and tvOS (guide)

Overview

The onDemandResources plugin provides an interface for Apple's on-demand resources, applicable to tvOS.

Usage of on-demand resources can be essential for developing tvOS games and apps since there is a limit of 200 MB for the app bundle.

Essentially, on-demand resources allow you to split your app into parts and download specific assets/resources when you require them. This technique can also be utilized to minimize the app's initial download size and reduce the footprint size in the device's storage.

Tags

When using on-demand resources, you should separate parts of your app into downloadable packages and reference them with tags. Each tag can point to an individual resource (file) or a group of resources (folder). By default, these resources will be excluded from the app bundle and will be available only after the app is downloaded.

See the instructions below regarding configuration of on-demand resources/tags.

Important

  • Resources must be available before you attempt to use them. This is accomplished via onDemandResources.request() which can both check the availability of resources or download them. If the desired resources are not available, you should request their download and wait for a successful callback response before attempting to use them.

  • Once resources are successfully requested and downloaded, they can be safely accessed until the application is terminated.

  • Even though you can typically use on-demand resources as if they exist in your app's bundle, they are not physically there. Use system.pathForFile() to retrieve the actual path, or alternatively the convenience function onDemandResources.path(). This may be necessary when, for example, an on-demand resource is a text file (not an image) and io.open() is required to open the file and read its contents (guide).

Gotchas

Project Settings

To use this plugin, add an entry into the plugins table of build.settings. When added, the build server will integrate the plugin during the build phase.

settings =
{
    plugins =
    {
        ["plugin.onDemandResources"] =
        {
            publisherId = "com.coronalabs"
        },
    },      
}

Important

To configure on-demand resources, include the onDemandResources table within the tvos and/or ios table of build.settings. This table should consist of a series of entries (tables) which define the packages for on-demand resources. Each of these tables must include a required tag key (string) and a required resource key (string) which can reference either a specific file or a folder containing multiple resources.

In addition, you can include an optional type key equal to either of these values:

  • "install" — These resources will be downloaded immediately when the app is downloaded from the App Store. This is useful for resources which may be required immediately when the app is first launched. In contrast to assets which are simply pre-bundled within your project folder for persistent availability, on-demand resources tagged with "install" may still be evicted from local storage at some point.

  • "prefetch" — These resources will begin to download in the background immediately after the app is downloaded from the App Store.

settings =
{
    tvos =
    {
        onDemandResources =
        {
            { tag="introMusic", resource="intro.mp4", type="prefetch" },
            { tag="imgTutorial", resource="img/tutorial", type="install" },
            { tag="imgL1", resource="img/level1" },
        },
    },
    iphone = 
    {
        onDemandResources =
        {
            { tag="introMusic", resource="intro.mp4", type="prefetch" },
            { tag="imgTutorial", resource="img/tutorial", type="install" },
            { tag="imgL1", resource="img/level1" },
        },
    },

}

Functions

Events

onDemandResourcesEvent