The development environment

Sideload your app

To sideload your app onto your Chromebook for testing, you must enter Developer mode on your Chrome OS device and enable unknown sources. See the Putting your Chrome OS Device into Developer Mode document for detailed instructions about moving your device into Developer mode. After your device is in Developer mode, you can go to your Chrome settings and select Enable Unknown Sources under the security in app settings.

After enabling Developer mode, you can load an Android app onto your Chrome OS device using one of several methods. For more details, see the Load your app section of the Loading Apps on Chromebooks page.

To ensure that your Android app works well on a variety of Chromebook devices and available form factors, Google recommends that you test your app on the following devices:

  • An ARM-based Chromebook
  • An x86-basedChromebook
  • A device with a touchscreen and one without one
  • A convertible device; that is, one that can change between a laptop and a tablet
  • A device with a stylus

To view the full list of supported devices, see the Chrome OS device support for apps page.

Debug with ADB

You can use the Android debug bridge (ADB) from your development machine to sideload and debug your app while it runs on a Chrome OS device. You can use USB or a network address to connect your device to ADB.

To use ADB, you must start your Chrome OS in Developer Mode so you can sideload Android apps onto your Chromebook.

After starting in developer mode, complete the following setup steps:

  1. Press Control+D to start your device.
  2. Finish the setup process.
  3. Log into your test account.
  4. Accept the Google Play Store terms and service conditions.

Enable ADB debugging

First, check to see if your device supports USB debugging.

To enable debugging:

  1. Click the clock in the bottom-right area of the screen.
  2. Click the gear icon.
  3. Click the Google Play Store section, then Manage Android preferences. This brings up the Android settings. You might want to right-click on the settings icon in the shelf and pin it there to get faster access in the future.
  4. Scroll down and click About device.
  5. Click Build number seven times to move into Developer mode.
  6. Click the arrow in the top-left area of the window to go back to the main Settings screen.
  7. Click the new Developer options item, activate ADB debugging, and then click OK to allow ADB debugging.

You might also want to optionally select these additional Android developer options for Chrome OS:

  • Allow free window resizing by dragging the border - This option lets you resize the app's window. Use it to to see if the app handles window size changes properly and to make sure that resizing is fast and fluid.
  • Debug information - Displays debugging information for Android applications in the window title bar.

Connect to ADB over USB

  1. Determine if your device supports USB debugging
  2. Press Control+Alt+T to start the Chrome OS terminal.
  3. Type shell to get to the bash command shell:

    crosh> shell
    chronos@localhost / $
    
  4. Type the following commands to set up your device:

    $ sudo crossystem dev_enable_udc=1
    $ sudo reboot
    
  5. After rebooting, open the terminal again and run the following command to enable ADB on the Chromebook's USB port:

    $ sudo ectool usbpd <port number> dr_swap
    

    Use this command each time you disconnect and reconnect a USB cable. To ensure your Chromebook is in UFP mode, you can run ectool usbpd <port number>.

  6. Plug in a USB cable to a supported port on your device

  7. Run adb devices from the Android SDK platform tools on your host machine to see your Chromebook listed as an adb supported device

  8. On your Chromebook, click Allow when prompted whether you want to allow the debugger. Your ADB session is established.

Connect to ADB over a network

In order to debug over a network, you must configure the Chrome OS firewall to allow incoming ADB connections:

  1. Press Control+Alt+T to start the Chrome OS terminal.
  2. Type shell to get to the bash command shell:

    crosh> shell
    chronos@localhost / $
    
  3. Type the following commands to set up developer features and enable disk-write access for the firewall settings changes. If you need to enter a sudo password for the chronos user, you can (re)set one by running chromeos-setdevpassword at the VT-2 prompt (Control+Alt+→); you'll need your root password.

    $ sudo crossystem dev_boot_signed_only=0
    $ sudo /usr/libexec/debugd/helpers/dev_features_rootfs_verification
    $ sudo reboot
    
  4. The sudo reboot command restarts your Chromebook. You can press the Tab key to enable autocompletion of file names. You must complete this procedure only once on your Chromebook.

After your device restarts, log in to your test account and type the following command to enable the secure shell and configure the firewall properly:

$ sudo /usr/libexec/debugd/helpers/dev_features_ssh

When the command completes, you can exit out of the shell.

Get the IP address of your Chromebook:

  1. Click the clock in the bottom-right area of the screen.
  2. Click the gear icon.
  3. Click the network type you are connected to (Wi-Fi or Mobile data) then the name of the network.
  4. Take note of the IP Address.

Connect to your Chromebook:

  1. Return to your development machine and use ADB to connect to your Chromebook using its IP address:

    adb connect <ip_address>
    
  2. On your Chromebook, click Allow when prompted whether you want to allow the debugger. Your ADB session is established.

Troubleshooting ADB debugging over a network

Sometimes the ADB device shows that it's offline when everything is connected properly. In this case, complete the following steps to troubleshoot the issue:

  1. Deactivate ADB debugging in Developer options.
  2. In a terminal window, run adb kill-server.
  3. Re-activate the ADB debugging option.
  4. In a terminal window, attempt to run adb connect.
  5. Click Allow when prompted whether you want to allow debugging. Your ADB session is established.