Starting in CommCare 2.24, a new system has been integrated to make image sizing for apps being deployed on multiple devices easier and more predictable. In the past, many users have experienced issues with the same images appearing as different sizes on different devices. Activating this system will fix that problem, by making the size at which an image appears in CommCare consistent with the size of the image file you provide, on all devices.
Is this feature right for me?
Before getting started, it is important to understand what this feature will and will not do to your images in CommCare. This feature is specifically intended for projects that are using more than one kind of mobile device, and want to keep image sizes consistent across all of those mobile devices. If you are looking for CommCare to try to automatically resize your images, please see the Auto-Resize Images feature instead.
If you are still unsure, consider the following to determine if this setting will be useful for your project:
- This feature will NOT be useful to you if: Your image is appearing larger or smaller than you would like it to on a single device, and you want CommCare to size it up/down for you to fix that. If this is the problem you are experiencing, the best course of action is likely to change the size of the original image file that you are providing to CommCare. If you are looking for CommCare to size your image up/down based upon available screen space, try the auto-resize feature mentioned above.
- This feature WILL be useful to you if: Your app is being deployed on multiple devices, and you are experiencing inconsistency with your image sizes across those different devices. In this case, users often find that the same image will show up at different sizes on those different devices, meaning that on SOME devices, an image is either too big or too small.
How to Enable this Feature
STEP 1: Selecting a Device
Determine the highest resolution device that your app is likely to be run on (highest resolution basically means the best quality screen, and will generally correspond to the newest/nicest/best device available, so that is a fine way to determine which device to use). If you are not yet certain what device your project will be using, just use the highest resolution / best device you have. The most important thing is just that you use the same device for all of the following steps.
STEP 2: Downloading the CommCare Developer Toolkit App
Download the CommCare Toolkit app from the Google Play Store (note that this is not the CommCare app, it's a separate Android app that runs on its own).
STEP 3: Sizing your images
Open the Developer Toolkit App and select “Size Your Images”.
You will see a sample image whose size you can adjust on the screen. As you adjust the size of the image, the app will update you on the exact dimensions (in pixels) of the image that you are currently viewing, so that you can adjust the size of your image file to match. Use this tool to help you decide what size to make each of your own image files.
Often, you will be looking to resize an existing image, without changing its original aspect ratio. To help you do this, you can use the “Aspect Ratio Lock” button and enter the original dimensions of the image file there.
STEP 4: Determining your device density
Go back to the home screen of the toolkit app, and then select “About My Device”.
Take note of the value listed next to “Screen Density”; you will need this in the next step.
STEP 5: Activating this feature for your app
Once you have finished sizing and uploading your image files, select the gear icon in the top left corner by your application name to proceed to the Application Settings page.
Then select the 'Advanced Settings' tab.
Once on the advanced tab, select the menu options on the right hand side (the three stacked lines). Checking the "Android Settings" option from this menu will open various settings for you to configure.
Find the setting entitled "Image Compatibility on Multiple Devices" and select the value in the dropdown menu that most closely matches the value you obtained for "Screen Density" in the previous step.
Make a new build of your app in order for this settings change to take effect.
That’s it. Updating this setting provides CommCare with the information it needs to keep your image sizes consistent across all devices. You do NOT need to repeat this process on other devices, even if your app is going to be deployed on multiple devices; doing it on one device suffices.