Running Your Android Application on an Android Device

Go Up to Android Mobile Application Development

After you prepare your development system for Android development, enable USB debugging in your Android device and configure your system to detect your Android device, you can run a multi-device application on a connected Android device.

1. Connect your Android device to your development system using your device's USB cable.

   You should see your Android device listed under Portable Devices in the Device Manager (available from the Control Panel).

   For more information, see Configuring Your System to Detect Your Android Device.

2. In RAD Studio, select either File > New > Multi-Device Application - Delphi or File > New > Multi-Device Application - C++Builder.
3. In the Project Manager, activate (double-click) the Android target platform.
4. Enable the Android SDK for your device:
   1. In the Project Manager, right-click the Android node and select Properties.
   2. In Platform Properties, click the down-arrow in the SDK (Software Development Kit) field and select either:
      • Your installed Android SDK version, if it is displayed
      • Add New
        1. In the Add a New SDK dialog box, click the down-arrow in the Select an SDK version field and select your installed Android SDK.
        2. Complete the fields in the Create a New Android SDK wizard. Most of the fields are completed automatically by the wizard.
5. Enable your Android device as the target platform: In the Android target platform in the Project Manager, open the Target node and double-click your Android device.

   When your Android device is correctly installed, the SDK version number appears after the Android target name; for example:

   Android - Android SDK 22.0.1

   Tips: If your device is not shown, try these steps:

   1. In the IDE, right-click the Target node and select Refresh.
   2. In the Control Panel, open the Device Manager:
      1. Verify that your Android device is listed, typically under Portable Devices.
      2. If your device is not listed, right-click any node and select Scan for hardware changes.
      3. If necessary, use the Android SDK Manager to uninstall and then reinstall the device driver for your Android device. Select Start | All Programs | Embarcadero RAD Studio Sydney | Android Tools.
         
         

   The following image shows a populated Android Target node displaying the Nexus 10 device:

   

6. If you selected the Application Store platform configuration on the Configuration node of the Project Manager, you must have a signing certificate configured for the Application Store platform configuration on the Provisioning page. The Development platform configuration does not require a signing certificate.
7. Run your application:
   • Run with debugging (Run > Run or F9)
   • Run without debugging (Run > Run Without Debugging or Shift+Ctrl+F9).

RAD Studio builds your application for Android and runs your application on the selected Android device. If your Android device screen is locked, unlock it to access your application.

The View Selected at Runtime Depends on the Target Device

In developing an Android app, you can specify views in the Form Designer if you want to target different devices.

When your application is run on an Android device, the runtime will query the device to determine the size and pixel density of the display. Then the runtime looks at the available views in your application to determine the view that is the closest match. This view is selected and resized to match the exact size specified by the device.

To see the algorithm used in selecting views and the range of sizes that match each Android view, see Using FireMonkey Views.

For details about FireMonkey views, see:

• View Selector (Form Designer)
• Using FireMonkey Views

Running Your Application with Clean Data and Cache Folders

When you run an application on an Android device, RAD Studio installs your application on your device using the package name that you defined in the Version Info options page to uniquely identify your application. By default, the package name is com.embarcadero.$(ModuleName), where $(ModuleName) is the name of your project, such as "Project1".

If you run your application on a device that already contains a previously-installed application with the same package name as the application that you want to run, the Run command reinstalls your application, but updates only the application executable; your application's data and cache folders are not updated. This preserving of the data and cache folders can be a problem during development, when you need to debug/deploy successive iterations of your app.

You can configure RAD Studio so that the Run Without Debugging and Run actions completely uninstall any previously-installed version of your application, including the data and cache folders. To do this, before installing the newer version, use the following steps:

1. Select Run > Parameters.
2. Enter "-cleaninstall" in the Parameters field:

   

3. Click OK to save your changes.

Troubleshooting

Unable to install <APK file>. Failure [INSTALL_FAILED_CONTAINER_ERROR]

Select Project > Options > Version Info and change the value of "installLocation" to auto.

See What does this mean: Failure [INSTALL_FAILED_CONTAINER_ERROR]? for more information and alternative solutions.

Stuck at "Uninstalling" on the Run Dialog Box

You might need to enable USB debugging specifically for your computer if you are running Android 4.2.2 or later and when you click Run or Run Without Debug, RAD Studio does not go beyond the following screen:

You might also need to enable the general USB debugging setting in your device. If this is the case, your device should show a dialog box asking you to allow USB debugging:

Click OK to allow USB debugging.

If you accidentally click Cancel, disconnect your device from your PC and then reconnect it to make the dialog box reappear on your device.

Workaround for Android 4.0/Kindle Fire Message: "Application does not support this device"

When you try to run an Android app on a device running Android 4.0.x (including some Amazon Kindle Fire devices), you might see this message:

 Application does not support this device

To workaround this issue:

1. In the IDE, open the Deployment Manager (Project > Deployment), and locate the following entry:
   

   Local Name: libnative-activity.so

   Remote Path: library\lib\armeabi\

2. Uncheck the entry to prevent deployment of this file.

Android Console App Must Provide a Pause at Startup

When you run an Android console app, the app might run to completion before the debugger can start. To avoid this issue, we suggest that you add a sleep command at the beginning of your code. For example:

sleep(3000)

The sleep number (specified in milliseconds) that works for your app is dependent on your target device's overall performance; that is, slow hardware requires more waiting time.

Cannot Deploy Android Apps if File Name Contains Unicode

An Android app might not start on the device if the deployment contains a file with Unicode characters. For example, if you add a file named 'test試験.txt' to an Android deployment, only a black screen appears and the app closes. This happens because a file with Unicode characters in the file name is ignored and is not added to the Android .apk file. The app fails because of the incomplete deployment.

Manually Uninstall an Android Application

To manually uninstall an Android application:

1. Go to the settings menu on your device: Settings > Apps or Application manager (this may differ depending on your device).
2. Touch the application that you want to uninstall.
3. Touch uninstall.

Debugging Does Not Start or Breakpoints Are Ignored

You may experience that in some specific situations the debugging does not always start or your breakpoints are ignored. The reason may be that the value of the installLocation parameter in the application manifest file is set to preferExternal. You can change this parameter in the IDE in Project > Options > Version Info. Set it to auto and make sure that there is sufficient free space on the internal storage (otherwise the application installs on the external storage).

Debugging Does Not Detect When App Exits

It may appear that the debugger is unable to detect that your application has exited, but this is normal. Every Android application runs in its own Linux process which will continue running until it is no longer needed and the system needs to reclaim its memory (for more information, see https://developer.android.com/guide/topics/processes/process-lifecycle.html). Because the application's process keeps running, it may appear that the debugger itself has hung, when in fact the debugger is continuing to debug the process which is still running. To end this process in the debugger, click Terminate.

See Also

• Configuring Your System to Detect Your Android Device
• Enabling USB Debugging on an Android Device
• Running and Debugging Your Android Application On a Remote Android Device