Skip to main content
Version: 6.4.2

Offline Cache for media files (File API)

File API allows files (video files, media files etc.) to be stored for offline usage.

All methods

MethodsDescriptionSupported since
listFiles()Return list of files of existing directory2.0.0
saveFile()Download file to selected directory1.0.3
loadFile()Load file from cache1.0.3
loadOrSaveFile()Download and load file from directory1.0.9
deleteFile()Delete file from directory2.0.0
getChecksumFile()Get checksum of a file2.0.0
validateChecksumFile()Validate that file's checksum matches expected value2.0.0
decompressFile()Decompress a compressed file or archive2.1.0
warning

Emulator has certain limitations while handling offline files. Read more here

listFiles()

This method is used to get a list of uids of all files, saved by the current applet.

Javascript example

// List uids of all files
await sos.offline.cache.listFiles().then((fileUids) => {
console.log("Loaded", fileUids);
}).catch((error) => { console.error(error); });

Returns

["video-3", "video-2", "video-1", "image-9", "image-8", "image-7", "image-6", "image-5", "image-4", "image-3", "image-2", "image-13", "image-12", "image-11", "image-10", "image-1"]

saveFile()

Method saveFile() is used to save files from remote a destination into the device internal memory.

Parameters

ParamTypeRequiredDescription
uidstring
Yes
Unique file identifier is used for later file retrieval, must contain a-z,A-Z,0-9 and . characters, slash / is supported since Front-display version 6.0.0
uristring
Yes
URL address to retrieve the file
headersobject
No
Key, value pairs of HTTP headers to send along with the request. Used when the target file is protected by a password or if any other specific headers are needed to access it.
warning

headers has to be a JSON object. If you are passing the value, make sure you use JSON.parse().

warning

uid should have the same file extension (e.g.: mp4, svg, jpg) as the original file.

Javascript example

// Example saving files into internal memory, unique id could be salted md5 hash, uri directs to our CDN
await sos.offline.cache.saveFile('9d66725ba2105f1833731ade5b7f334e.mp4', 'https://cdn.my-cms.com/files/video.mp4', { "Authorization": "Basic Zm9vOmJhcg==" })
.then(() => { console.log('Saved'); })
.catch((error) => { console.error(error); });
info

Local device file path differs from device to device. It can point to file:// or http://localhost etc.

loadFile()

Method loadFile() is used for individual file retrieval from internal memory.

Parameters

ParamTypeRequiredDescription
uidstring
Yes
Unique file identifier is used for later file retrieval, must contain a-z,A-Z,0-9 and . characters
warning

uid should have the same file extension (e.g.: mp4, svg, jpg) as the original file.

Javascript Example

await sos.offline.cache.loadFile('9d66725ba2105f1833731ade5b7f334e.mp4')
.then((file) => { console.log('Loaded', file); })
.catch((error) => { console.error(error); });

// Logs into console
{
filePath: '/real/device/path/to/file/9d66725ba2105f1833731ade5b7f334e.mp4',
}
info

Local device file path differs from device to device. It can point to file:// or http://localhost etc.

Returns

  • SUCCESS: File object
  • FAIL: No file of such uid is available, it throws error into promise

loadOrSaveFile()

Method loadOrSaveFile() is used for individual file retrieval & save in case when file is not saved in local storage yet. To get file from internal memory & save it when not yet exists we prepared loadOrSaveFile() method:

info
  • The file URI has to return the file. If your URI leads to a 303 redirect (e.g. from http to https), the API will not work.
  • Emulator has certain limitations while handling offline files. Read more here

Parameters

ParamTypeRequiredDescription
uidstring
Yes
Unique file identifier is used for later file retrieval, must contain a-z,A-Z,0-9 and . characters
uristring
Yes
URL address where to get the file
headersobject
No
Key, value pairs of HTTP headers to send along with the request. Used when the target file is protected by a password or if any other specific headers are needed to access it.
warning

uid should have the same file extension (e.g.: mp4, svg, jpg) as the original file.

Javascript Example

await sos.offline.cache.loadOrSaveFile('9d66725ba2105f1833731ade5b7f334e.mp4', 'https://cdn.my-cms.com/files/video.mp4', { "Authorization": "Basic Zm9vOmJhcg==" })
.then((file) => { console.log('Loaded or Saved', file); })
.catch((error) => { console.error(error); });

// Logs into console
{
filePath: '/real/device/path/to/file/9d66725ba2105f1833731ade5b7f334e.mp4',
}
info

Local device file path differs from device to device. It can point to file:// or http://localhost etc.

Returns

  • SUCCESS: File object
  • FAIL: No file of such uid is available, it will download it to local storage & then return saved file.

deleteFile()

Method deleteFile() is used for deleting previously saved file from internal memory.

Parameters

ParamTypeRequiredDescription
uidstring
Yes
Unique file identifier is used for later file retrieval, must contain a-z,A-Z,0-9 and . characters

Javascript example

await sos.offline.cache.deleteFile('9d66725ba2105f1833731ade5b7f334e.mp4')
.then(() => { console.log('Deleted'); })
.catch((error) => { console.error(error); });

getChecksumFile()

Method getChecksumFile() is used for getting the checksum of file from internal memory.

Parameters:

ParamTypeRequiredDescription
uidstring
Yes
Unique file identifier is used for later file retrieval, must contain a-z,A-Z,0-9 and . characters
hashTypestring
Yes
Type of checksum has. Currently supported hashType is just md5

Javascript example

await sos.offline.cache.getChecksumFile('9d66725ba2105f1833731ade5b7f334e.mp4', 'md5')
.then((checksum) => { console.log('MD5 checksum is ' + checksum); })
.catch((error) => { console.error(error); });

validateChecksumFile()

Method validateChecksumFile() is used for validating the checksum of the previously saved file in from internal memory.

Parameters:

ParamTypeRequiredDescription
uidstring
Yes
Unique file identifier is used for later file retrieval, must contain a-z,A-Z,0-9 and . characters
hashstring
Yes
Hexa decimal representation of file checksum to be validated against
hashTypestring
Yes
Type of checksum hash. Currently supported hashType is just md5

Javascript example

// validate file checksum against internal memory
await sos.offline.cache.validateChecksumFile(uid, '23dc936691f46d2bbef631f18a02f94f', 'md5')
.then((valid) => { console.log('MD5 checksum is ' + (valid ? 'valid' : 'not valid')); })
.catch((error) => { console.error(error); });

decompressFile() (ZIP)

Method decompressFile() is used to decompress (extract ZIP) file previously saved to internal memory.

Parameters

ParamTypeRequiredDescription
zipUidstring
Yes
Unique file identifier of a previously downloaded ZIP file
destinationUidstring
Yes
Unique directory identifier (prefix of file) to extract ZIP file to
methodstring
Yes
Method of compression algorithm, currently only zip is supported

Javascript example

// validate file checksum against internal memory
await sos.offline.cache.decompressFile(zipUid, destinationDirectoryUid, 'zip')
.then(() => { console.log('ZIP file extracted'); })
.catch((error) => { console.error(error); });
GitHub Example

Errors

Although we are doing our best, following errors may occur when working with the offline cache.

CodeTypeMessage
40105AppletResourceErrorAlready loading file: $$FILE_NAME$$
^^^^Please, check your code for multiple occurrences of addFile/s methods.
40106AppletResourceErrorAlready existing file: $$FILE_NAME$$
^^^^Please, check your code for occurrences of addFile/s methods on lines before this error.
49902FileNotFoundErrorFile was not found $$FILE_ID$$
40901AppletOfflineCacheErrorUid contains invalid characters, allowed: $$ALLOWED_CHARS$$, got $$ACTUAL_UID$$
^^^^Please, check if the used URL is correct.
40902AppletOfflineCacheErrorInvalid headers $$HEADERS$$
50901InternalOfflineCacheErrorCouldn't not read the files from the offline cache.
50902InternalOfflineCacheErrorFile wasn't saved correctly.
50903InternalOfflineCacheErrorReading the file from the offline cache failed.