Accessing Images

Images can be incorporated into your native app and accessed from app.js file.

Use the file scheme file:///filename.extension to refer to an image in app.js file. Filenames must contain only lowercase a-z, 0-9, or underscore characters.

On Android, Astro will first search for images in the resource directory, if not found it will then search for them in the assets directory.

On iOS, Astro will search for an image in the project's asset catalogs and added directly to the project. The order that it looks for these images is undefined. As a result, it is best to avoid having images with duplicate filenames across your project (except of course where you support multiple resolutions like logo.png and logo@2x.png and logo@3x.png).

Providing Images to the Android App

Images are generally provided to Android apps by placing them in the resource directory: app/src/main/res/drawable. In order to optimize an app for different screen sizes and densities, images should be provided for each screen density which the app supports. Android separates screen densities into buckets and suggests a scaling factor when creating images for each bucket. Here is the general file structure for the resource directory:

+-- app/src/main/
|   +-- res/
|       +-- drawable-xxhdpi/
|           +-- img1.png
|           +-- img2.png
|       +-- drawable-xhdpi/
|           +-- img1.png
|           +-- img2.png
|       +-- drawable-hdpi/
|           +-- img1.png
|           +-- img2.png
|       +-- drawable-mdpi/
|           +-- img1.png
|           +-- img2.png
|       +-- drawable/
|           +-- img1.png
|           +-- img2.png

If there is no appropriate density specific drawable image provided the system will look for a default image in the unqualified drawable/ directory.

Please consult the Android Developers Guide for more information about resources and screen densities.

Raw assets can be packaged in the app in assets directory: app/src/main/assets/.

Providing Images to the iOS App

Images can be bundled into an iOS app in two different ways: Asset Catalogs and directly in the project. An Asset Catalog is the preferred method of bundling images with an iOS app as you can group all resolutions of an image together into an Image Set. You can then reference the images by the name you give the image set. You can find more information here.

The other method to bundle images is to drag them directly into an Xcode project. You can provide up to 3 different resolutions for each image: non-retina, retina, and retina-hd. Non-retina images should be named exactly as you will reference them in code with an extension(eg. logo.png). Retina images should be named with "@2x" appearing just before the extension (eg. logo@2x.png). Retina-hd images should be named with "@3x" appearing just before the extension (eg. logo@3x.png).

In both cases, iOS will load the image with the resolution closest to the device its running on (ie. on an iPhone 6 it will attempt to load an @2x image and then the base image, but on an iPhone 6 Plus it will attempt to load an @3x image and then the base image).

Although the document discusses Icon and Launch Images specifically, the iOS Human Interface Guidelines information applies to images in general and provides a good reference that shows how different image resolutions map to different iPhone versions.

iOS also supports images provided as vector-based PDFs. When you supply an image as a PDF, Xcode will render out the different resolutions that it calculates are needed. This means you only need one asset per image instead of 2 or 3! This session from WWDC 2014 mentions these capabilities. You can also read this good blog post for more details.

Providing Images from the Network

Android supports loading images using http:// and https:// urls. iOS supports loading images using http://, https:// urls and bundled images with the ImageViewPlugin. All other image loading is limited to bundled images.