AssetResolver

This document will serve as a user guide and will explain library installation (in a KSDK app) and API usage.

Library Setup

1. Update the package's package.json file to add the library as a dependency:

   "dependencies": {
       "@amazon-devices/asset-resolver-lib": "*"
   }

2. With these changes, the AssetResolver turbo module can be consumed. To include the class and its types, the following include line should be used:

   import { AssetResolver, AssetType } from '@amazon-devices/asset-resolver-lib'

Asset Resolution

As previously mentioned, AssetResolver turbo module is a wrapper for the AssetResolver Application Framework library. The AssetResolver library provides applications a means of seamless asset resolution whereby assets are ranked according to device system qualifiers.

Applications can contain assets which are files that can be used for things such as images and text. Assets must be located in the application's assets directory, and the following directory structure must be used for AssetResolver API use:

└── assets
    ├── image
    ├── raw
    └── text

These directories will hold asset files for images, raw files, and text-defining files, respectively. These are the supported asset types in the AssetResolver.

For text localization, Asset Resolver expects text asset files to use the puff.json format for defining string and numeric values. PUFF-J files define text resources used in an application and are used by Asset Resolver in its getString() and getNumber() APIs.

Configuration Qualifiers

The AssetResolver's APIs resolve assets based on the system's current configuration qualifiers. These are values which define certain device properties such as locale, UI mode, and so on.

For example, the qualifier locale can take values en-US, es-AR, or es-SP. This qualifier will directly influence which assets are resolved.

└── assets
    ├── image
    ├── raw
    └── text
        ├── en
        │   └── strings.puff.json
        ├── en-US
        │   └── strings.puff.json
        ├── es
        │   └── strings.puff.json
        ├── es-AR
        │   └── strings.puff.json
        └── strings.puff.json

In the above asset directory structure, the file strings.puff.json is defined in multiple directories: one for each locale and one in text to act as a default. Depending on the current system configuration qualifiers, the AssetResolver will resolve text based on the most appropriate match; if there is none, the default file will be used.

NOTE: when an application supports a locale (such as en-GB), it must also define support for that locale's default qualifier (in this case en).

NOTE: defining a default asset file is recommended as it ensures there is always an asset matched in case asset resolution fails.

If the system configuration qualifier for locale is es-AR, then the file assets/text/es-AR/strings.puff.json will be chosen when using the AssetResolver APIs. If multiple locales contain the same text assets, symbolic links to a single asset file may be used to save device storage space.

NOTE: only locale is supported as a configuration qualifier to resolve assets around.

Access Control

The AssetResolver APIs are not access-controlled. AssetResolver APIs only execute within an application's subset of the device's filesystem. Moreover, other applications cannot explicitly resolve assets from another application, ensuring app-to-app isolation.

Usage

The AssetResolver is an application library that allows retrieval of assets from packages. These assets are resolved based on various system qualifiers such as locale, day/night mode, UI mode, etc. Assets can be text-based, images, or raw files.

The AssetResolver turbo module provides various APIs which packages may use to retrieve asset values as well as paths which will be demonstrated below.

AssetConfiguration type

Certain APIs take in an AssetConfiguration object. This object is used to specify which qualifiers should be used when resolving assets. Currently locale is supported.

getString()

In order to retrieve an internationalized string value, the getString() API should be used. This API takes in the identifier of the string being queried and an optional configuration object which specifies which qualifiers should be used in asset resolution.

On failure, this API will throw an Error whose message indicates the error condition.

const stringResult = AssetResolver.getString("welcome-string");

console.log("string value: {}", stringResult.value);
console.log("string direction: {}", stringResult.dir);

const config = { locale: "fr-CA" };
const stringConfigResult = AssetResolver.getString("welcome-string", config);

console.log("string value: {}", stringConfigResult.value);
console.log("string direction: {}", stringConfigResult.dir);

getNumber()

In order to retrieve an internationalized number value, the getNumber() API should be used. Similar to getString(), this takes in a string which is the identifier for the number value being queried. Furthermore, the API also takes in an optional configuration object which specifies which qualifiers should be used in asset resolution.

This API similarly throws an Error if there is an issue in execution.

const numberResult = AssetResolver.getNumber("numeral");

console.log("number value: {}", numberResult);

const config = { locale: "en-US" };
const numberConfigResult = AssetResolver.getNumber("numeral", config);

console.log("number value: {}", numberConfigResult);