• Home
• Felgo
• DownloadableResource

DownloadableResource

The DownloadableResource item allows to download additional assets from the Internet. More...

• List of all members, including inherited members

Properties

• available : bool
• extractAsPackage : bool
• headerParameters : var
• progress : int
• secret : string
• source : url
• status : enumeration
• statusText : string
• storageLocation : enumeration
• storageLocationDisplayName : string
• storageName : string
• storagePath : url

Signals

• downloadFinished(error)
• downloadProgressChanged(progress)
• downloadStarted()
• extractionProgressChanged(progress)

Methods

• void cancel()
• void download()
• url getExtractedFileUrl(string relativePath)
• void remove()

Detailed Description

DownloadableResource allows downloading app and game assets on demand during runtime. That way not all resources must be included in the app binary and therefore result in smaller downloads from the app stores.

The most popular use cases for downloadable packages are:

• You want to keep your app store binary as small as possible for the first download, to increase the download numbers of your app or game with a smaller download size.
• You want to download additional content packages after in-app purchases.
• Keep your initial app size below the store limits:
  • On Google Play, your initial apk size must be below 100MB, after that you need to use Android expansion files. To avoid that, you can just use DownloadableResource and download the additional files at a later time.
  • On iOS, your initial binary size limit is 150MB for mobile network downloads. If your binary is bigger, the user can only download your app over WiFi. Downloading additional resources later also helps you to avoid this limit.
  • With the Felgo DownloadableResource component, you can create a cross-platform solution to work with downloadable resources, that works for both iOS AND Android. It even works on Desktop too, with a single source code for all platforms! This way, you do not need to deal with Android expansion files and can create a working solution for all platforms instead.

DownloadableResource can load files from any HTTP(S) web addresses. You can add a secret to protect and restricts downloads to your app or game only. You can download single files or entire .zip-archives, which are automatically extracted for further usage.

The item downloads and extracts to a standard path or custom location. You can then use downloaded resources from within your app or game as you do with local resources.

Supported Resource Types

The DownloadableResource item currently supports all kinds of files that you use with Felgo components. Examples are:

• Images and sprites displayed with the visual components
• Videos shown with the Video and AlphaVideo components
• Sound files played with the BackgroundMusic and GameSoundEffect components
• Particle effects used with the GameParticle component
• Entire QML files loaded with the Loader component

Assets downloaded with DownloadableResource are persisted between app starts, so they are cached for offline usage as well.

Storage Location

You can set the path where to download and extract the files to with the storageLocation property. Depending on your usecase, you can choose one of the available FileUtils standard paths. You can alternatively set the full path with the storagePath property.

The default value of storageLocation is FileUtils.AppDataLocation, which is a default location for your app's private files that are then available for as long as the app is installed on a device.

To set the file name of the resulting file, use the storageName property.

The following table lists the platform-specific paths for FileUtils.AppDataLocation:

How to Create Downloadable Packages

To download multiple files at once, create an archive files with .zip file ending. You can use any data compression application that supports the zip archive file type.

The item supports subfolders within the zip archive to structure downloadable resources.

Example Usage

To just download a single file from a web server, use the following example code:

 import Felgo

 App {
   DownloadableResource {
     id: resource1

     extractAsPackage: false // false for single files
     source: "https://felgo.com/web-assets/girl.jpg"
   }
 }

Likewise, you can download and extract a .zip package like the following (note the extractAsPackage):

 import Felgo

 App {
   DownloadableResource {
     id: resource1

     extractAsPackage: true // true for zip archives
     source: "https://felgo.com/web-assets/girl.zip"
   }
 }

To start the actual download, call the download() method.

To check the status of a package, use the status property. The convenience property available is true after the status changes to DownloadableResource.Available.

If you download single files (i.e. extractAsPackage is false), storagePath contains the full URL to the downloaded file.

Placeholder Image and "Available" Property

Use the available property to display a placeholder image while downloading:

 AppImage {
   source: resource1.available ? resource1.storagePath : "local-image.png"
 }

If you extract packages, you can retrieve the path to an extracted file using getExtractedFileUrl(). The parameter is a relative path to a file within a downloaded and extracted .zip package. This returns the full URL to the file which you can use anywhere within your app or game (i.e. the source property of an AppImage).

In the following example, extracted-image.png is a file within the downloaded .zip archive. local-image.png is a local file at the same path as the QML file.

 AppImage {
   source: resource1.available ? resource1.getExtractedFileUrl("extracted-image.png") : "local-image.png"
 }

You can also use sub-folders within extracted .zip archives. getExtractedFileUrl() supports relative paths to nested files:

 AppImage {
   source: resource1.available ? resource1.getExtractedFileUrl("content/images/extracted-image.png") : "local-image.png"
 }

Additionally you can split up resources over multiple download packages. The extraction path of each package is registered with FileUtils using FileUtils::addSearchPath(). This allows FileUtils::getMultiPathUrl() to find files from any downloaded package. For example, if you have a file called "image.png" that is part of one of multiple download packages, you can display the image like the following:

 AppImage {
   source: FileUtils.getMultiPathUrl("image.png")
 }

If the file is not found in any extracted package, a fallback file with the same name can be loaded from other search paths.

Open downloaded files

You can open files you have downloaded with an external application using FileUtils::openFile(). If you download single files, you can directly use storagePath with this method.

The following example downloads a PDF file and then opens it with the default installed PDF viewer:

 import Felgo
 import QtQuick

 App {
   id: app

   DownloadableResource {
     source: "http://www.orimi.com/pdf-test.pdf"
     storageLocation: FileUtils.DocumentsLocation
     storageName: "pdf-test.pdf"
     extractAsPackage: false

     Component.onCompleted: {
       if(status === DownloadableResource.UnAvailable) {
         download()
       } else {
         openDownloadedFile()
       }
     }

     onStatusChanged: openDownloadedFile()

     function openDownloadedFile() {
       if(status === DownloadableResource.Available) {
         FileUtils.openFile(storagePath)
       }
     }
   }
 }

You can also open files extracted from .zip packages. For this, you can use getExtractedFileUrl() to open extracted files like in the following example:

 FileUtils.openFile(resource1.getExtractedFileUrl("extracted-file.pdf"))

Using a Secret to Protect Your Downloads

Sometimes you want to protect your resources from downloads outside your app. For this usecase the DownloadableResource item provides the secret property. If the secret property is set, the item appends HTTP GET parameters to your provided source. This looks like the following:

 https://example.com/resource1.zip?token=3fcdb553d1abd6e57d5d4496c5f86eb690fbd319&timestamp=1524706331

The token consists of the following checksum:

 shasum( appid + ":" + secret + ":" + timestamp )

• The appid is the identifier given in your config.json file.
• The secret is this property.
• The timestamp is the current timestamp in UTC time zone in seconds since January 1, 1970.

Your server-side implementation should check the token against the following criteria:

• The age of the timestamp, for example deny the request if it is older than 5 minutes.
• Match the given token with a token generated on server side. Use the given timestamp, stored secret and known app identifier.

If the token meets all criteria, you can return the requested zip file. Otherwise return a HTTP 401 status code.

Notes on Multi-Threading

The download and extraction process is performed asynchronously in the background.

Downloading and extracting large files may take a while depending on the file size. It is good practice to display a progress bar during the download. You can do so with the progress property. You can check individual progress with the downloadProgressChanged and extractionProgressChanged signals.

It is thread-save to call download() and then listen to the available property. See more in Example Usage.

Advanced Usage

DownloadableResource offers advanced properties, functions and signals. Use these to control the download and extraction process.

You can set a standard location for download with the storageLocation property. Use one of the FileUtils storage location constants. Choose a name a name for the downloaded or extracted file or folder with storageName. To set the complete path manually, use the storagePath property. This overrides both storageLocation and storageName.

You can supply additional HTTP headers using headerParameters.

Use status and progress to query the current status of the download and extraction progress. You can cancel an ongoing operation using cancel().

This QML example app uses all the available features of DownloadableResource:

 import Felgo
 import QtQuick
 import QtQuick.Controls

 App {
   id: app

   //all enum values to be able to select in a dialog
   readonly property var allStandardPaths: [
     FileUtils.DocumentsLocation,
     FileUtils.DownloadLocation,
     FileUtils.CacheLocation,
     FileUtils.DesktopLocation,
     FileUtils.FontsLocation,
     FileUtils.ApplicationsLocation,
     FileUtils.MusicLocation,
     FileUtils.MoviesLocation,
     FileUtils.PicturesLocation,
     FileUtils.TempLocation,
     FileUtils.HomeLocation,
     FileUtils.DataLocation,
     FileUtils.GenericDataLocation,
     FileUtils.RuntimeLocation,
     FileUtils.ConfigLocation,
     FileUtils.GenericCacheLocation,
     FileUtils.GenericConfigLocation,
     FileUtils.AppDataLocation,
     FileUtils.AppConfigLocation,
     FileUtils.AppLocalDataLocation
   ]

   DownloadableResource {
     id: dl

     //shorthand property if status is busy
     property bool busy: status === DownloadableResource.Downloading || status === DownloadableResource.Extracting

     //download and extract .zip
     source: "https://www.dropbox.com/s/z2dxyn2847stnq3/multiResolutionImage.zip?dl=1"

     //set storage folder from standard path
     storageLocation: FileUtils.DownloadLocation

     //set file/folder name for storage
     storageName: "multiResolutionImage"

     //additional HTTP headers
     headerParameters: ({
                          "X-Custom-Header": "header-value1",
                          "X-Custom-Header2": "header-value2"
                        })

     //show progress in bar
     onProgressChanged: progressBar.value = progress
   }

   AppPage {
     anchors.fill: parent
     anchors.topMargin: Theme.statusBarHeight

     ProgressBar {
       id: progressBar
       anchors.left: parent.left
       anchors.right: parent.right
       anchors.top: parent.top
       height: dp(32)

       minimumValue: 0
       maximumValue: 100
     }

     AppListView {
       anchors.fill: parent
       anchors.topMargin: progressBar.height

       //model defines the UI items
       model: [
         {
           text: "Available: " + dl.available,
           enabled: false
         }, {
           text: "Status: " + dl.statusText,
           enabled: false
         }, {
           text: "Source:",
           detailText: dl.source,
           action: "source"
         }, {
           text: "Extract as package?",
           action: "extract",
           checked: dl.extractAsPackage
         }, {
           text: "Storage location: " + dl.storageLocationDisplayName,
           action: "storageLocation",
           enabled: !dl.busy
         }, {
           text: "Storage name: " + dl.storageName,
           action: "storageName",
           enabled: !dl.busy
         }, {
           text: "Storage path:",
           detailText: dl.storagePath,
           action: "storagePath",
           enabled: !dl.busy
         }, {
           text: "Remove",
           action: "remove",
           enabled: dl.available
         }, {
           text: "Start download",
           action: "download",
           enabled: !dl.busy && !dl.available
         }, {
           text: "Cancel",
           action: "cancel",
           enabled: dl.busy
         }, {
           text: "Full URL of image in package:",
           detailText: dl.available ? dl.getExtractedFileUrl("+hd/testContentScaling.png") : "(unavailable)",
           enabled: dl.available,
           action: "showImage"
         }

       ]

       //delegate defines the list item + interaction
       delegate: SimpleRow {
         style.backgroundColor: enabled ? "white" : "#ddd"

         iconSource: modelData.action === "extract" ? IconType.check : ""
         icon.color: modelData.checked ? "black" : "#40000000"

         onSelected: {
           switch(modelData.action) {
           case "extract":
             dl.extractAsPackage = !dl.extractAsPackage
             break;
           case "remove":
             dl.remove()
             break;
           case "download":
             dl.download()
             break;
           case "cancel":
             if(dl.busy) {
               dl.cancel()
             }
             break;
           case "source":
             InputDialog.inputTextSingleLine(app, "Enter URL:", "https://", function(accepted, text) {
               if(accepted) dl.source = text
             }, true)
             break;
           case "storagePath":
             InputDialog.inputTextSingleLine(app, "Enter file path:", "/", function(accepted, text) {
               if(accepted) dl.storagePath = text
             }, true)
             break;
           case "storageName":
             InputDialog.inputTextSingleLine(app, "Enter file name:", "", function(accepted, text) {
               if(accepted) dl.storageName = text
             }, true)
             break;
           case "storageLocation":
             selectDialog.open()
             break;
           case "showImage":
             var url = dl.getExtractedFileUrl("+hd/testContentScaling.png")
             if(url) {
               dialogImage.source = url
               imgDialog.open()
             }
             break;
           }
         }
       }
     }
   }

   // dialog to select one of the standard path enum values
   Dialog {
     id: selectDialog
     contentHeight: itemList.height
     title: "Select storage location"

     positiveAction: false
     onCanceled: close()

     AppListView {
       id: itemList

       width: parent.width
       height: dp(48) * 6 // max. 6 items

       model: allStandardPaths.map(FileUtils.storageLocationDisplayName)
       delegate: SimpleRow {
         text: modelData

         onSelected: {
           dl.storageLocation = allStandardPaths[index];
           selectDialog.close();
         }
       }
     }
   }

   // dialog to show an image from inside the downloaded package
   Dialog {
     id: imgDialog
     contentHeight: dialogImage.height
     title: "Image"

     positiveAction: false
     onCanceled: close()

     AppImage {
       id: dialogImage

       width: parent.width
       height: dp(120)
       fillMode: Image.PreserveAspectFit
     }
   }
 }

See also FileUtils.

Property Documentation

 AppImage {
   source: resource1.available ? dl.getExtractedFileUrl("package-image.png") : "local-image.png"
 }

 DownloadableResource {
   source: "https://example.com/package1.zip"

   headerParameters: ({
     "Accept-Language": "en-us",
     "Authorization": "Basic abcdefghi",
   })
 }

Signal Documentation

Method Documentation