Executar apps em um dispositivo de hardware

Sempre teste seu app Android em um dispositivo real antes de liberá-lo para os usuários. Esta página descreve como configurar seu ambiente de desenvolvimento e dispositivo Android para testes e depuração usando uma conexão do Android Debug Bridge (ADB).

Observação: use o Android Emulator para testar seu app em diferentes versões da plataforma Android e em diferentes tamanhos de tela. Considere usar o Firebase Test Lab para executar seu app em uma grande variedade de dispositivos reais hospedados em uma infraestrutura baseada na nuvem.

Configurar um dispositivo para desenvolvimento

Antes de começar a depuração no dispositivo, decida se você quer se conectar a ele usando um cabo USB ou Wi-Fi. Em seguida, faça o seguinte:

1. No dispositivo, abra o app Configurações, selecione Opções do desenvolvedor e ative a Depuração USB, se aplicável.

   Observação: se você não encontrar as Opções do desenvolvedor, siga as instruções para ativar as opções do desenvolvedor (em inglês).

2. Configure seu sistema para detectar o dispositivo.

   • Chrome OS: nenhuma outra configuração é necessária.
   • macOS: nenhuma outra configuração é necessária.
   • Windows: instale um driver USB para o ADB, se aplicável. Para ter um guia de instalação e links para drivers OEM, consulte Instalar drivers USB OEM.

   • Ubuntu Linux: configure o seguinte:

     • Todos os usuários que querem usar o ADB precisam estar no grupo plugdev. Se você receber uma mensagem de erro informando que não está no grupo plugdev, entre nele usando o comando a seguir:

     sudo usermod -aG plugdev $LOGNAME
     

     Os grupos são atualizados apenas no login. Portanto, você precisa sair para que essa mudança entre em vigor. Ao fazer login novamente, você pode usar id para verificar se está no grupo plugdev.

     • O sistema precisa ter regras udev instaladas que incluam o dispositivo. O pacote android-sdk-platform-tools-common contém um conjunto padrão de regras udev mantido pela comunidade para dispositivos Android. Para instalá-lo, use o seguinte comando:

     apt-get install android-sdk-platform-tools-common
     

Conectar ao dispositivo por USB

Quando estiver configurado e conectado por USB, clique em Run no Android Studio para criar e executar o app no dispositivo.

Também é possível usar adb para emitir comandos da seguinte maneira:

• Verifique se o dispositivo está conectado executando o comando adb devices a partir do diretório android_sdk/platform-tools/. Se estiver, você encontrará o dispositivo listado.
• Emita um comando adb com a sinalização -d para direcioná-lo ao dispositivo.

Conectar ao dispositivo por Wi-Fi

O Android 11 e versões mais recentes oferece suporte à implantação e depuração do app por Wi-Fi pela estação de trabalho usando o Android Debug Bridge (ADB). Por exemplo, é possível implantar o app depurável em vários dispositivos remotos sem conectar fisicamente o dispositivo via USB e resolver problemas comuns de conexão USB, como a instalação do driver.

O Android 17, junto com o adb 37.0.0, apresenta o adb Wi-Fi 2.0, que resolve muitos dos problemas de usabilidade da versão anterior. Principalmente, o dispositivo se conecta automaticamente à estação de trabalho quando ele se conecta a uma rede confiável de depuração por Wi-Fi.

Para usar a depuração por Wi-Fi, é necessário parear seu dispositivo com a estação de trabalho usando um código de pareamento. Para começar, siga estas etapas:

1. Confira se a estação de trabalho e o dispositivo estão conectados à mesma rede Wi-Fi.
2. Confira se o dispositivo está executando o Android 11 ou uma versão mais recente. Para mais informações, consulte Verificar e atualizar a versão do Android.
3. Confira se você tem a versão mais recente do Android Studio instalada. Faça o download aqui.
4. Na sua estação de trabalho, instale a versão mais recente do SDK Platform-Tools.

Para parear com seu dispositivo, siga estas etapas:

Observação: basta parear o dispositivo com a estação de trabalho uma vez. O dispositivo vai permanecer pareado com a estação de trabalho até que você o remova ou revogue as autorizações de depuração adb no dispositivo. O dispositivo e a estação de trabalho se conectam automaticamente quando estão na mesma rede.

1. Ative as Opções do desenvolvedor no dispositivo.

2. No dispositivo, toque em Depuração por Wi-Fi.

   

   Figura 1. O aviso Depuração por Wi-Fi em um smartphone Google Pixel.

3. Permita a depuração por Wi-Fi na sua rede. Clicar na caixa de seleção Sempre permitir nesta rede torna a rede uma rede de depuração sem fio confiável. O dispositivo sempre vai permitir a depuração por Wi-Fi nesta rede assim que ele se conectar a ela.

   

   Figura 2. A configuração Depuração por Wi-Fi em um smartphone Google Pixel.

4. Abra o Android Studio e selecione Pair Devices Using Wi-Fi no menu suspenso de configurações de execução.

   

   Figura 3. Menu de configurações de execução.

   
   

5. A caixa de diálogo Pair devices over Wi-Fi aparece, conforme mostrado na Figura 4.

   

   Figura 4. Dialog to pair devices over Wi-Fi.

   Você também pode parear o dispositivo no Gerenciador de dispositivos. Por exemplo, My Pixel.

   

   Figura 5. Gerenciador de dispositivos com um dispositivo disponível para pareamento por Wi-Fi.

   
   

6. Clique em Pair no dispositivo que você quer parear. A caixa de diálogo de pareamento de dispositivos aparece.

   1. Se quiser usar um QR code, selecione Parear o dispositivo com um QR code e leia o QR code.

      

      Figura 6. Dialog to pair device using QR code.

   2. Para usar um código de pareamento, selecione Parear o dispositivo com um código de pareamento na caixa de diálogo Parear novos dispositivos por Wi-Fi. No dispositivo, selecione Parear usando o código de pareamento. Um código de seis dígitos vai aparecer. Quando o dispositivo aparecer na janela Pair devices over Wi-Fi, digite o código de seis dígitos mostrado no dispositivo e selecione Pair .

      

      Figura 7. Exemplo de entrada do código PIN de seis dígitos.

7. Após o pareamento, você pode tentar implantar o app no dispositivo.

Para remover o pareamento da estação de trabalho, acesse Depuração por Wi-Fi no dispositivo. Toque no nome da estação de trabalho em Dispositivos pareados e selecione Esquecer. Como alternativa, clique em Revogar autorizações de depuração do adb na página de configurações do dispositivo para remover o pareamento da estação de trabalho e de todas as outras estações pareadas anteriormente.

Espelhamento de dispositivos

É possível espelhar seu dispositivo físico na janela Running Devices do Android Studio. Ao fazer streaming da tela do dispositivo diretamente para o Android Studio, você pode usar o próprio ambiente de desenvolvimento integrado do Studio para executar ações comuns, como iniciar apps e interagir com eles, girar a tela, dobrar e desdobrar o smartphone e ajustar o volume.

O espelhamento de dispositivos está sempre disponível quando há dispositivos conectados ao computador com a depuração USB ou por Wi-Fi ativada. Você pode iniciar e parar o espelhamento usando a janela Running Devices ou o Device Manager (View > Tool Windows > Device Manager). Também é possível personalizar quando o espelhamento do dispositivo é ativado nas configurações (Settings > Tools > Device Mirroring).

Observação: se você estiver usando determinados dispositivos (como o Xiaomi Redmi K40, o Poco F3 ou o Mi 11X) com o Android 12, será necessário ativar as configurações USB debugging e USB debugging (Security settings) e reiniciar o dispositivo para ativar o espelhamento.

Redirecionar áudio

Ao usar o espelhamento de dispositivos, é possível redirecionar o áudio de dispositivos físicos conectados para os alto-falantes ou fones de ouvido do computador. Com o redirecionamento de áudio, mantenha os fones de ouvido conectados ao computador e ouça os dois dispositivos sem precisar se reconectar manualmente a um e depois a outro. Para ativar o redirecionamento de áudio, acesse File (Android Studio no macOS) > Settings > Tools > Device Mirroring e selecione Redirect audio from local devices. O áudio é sempre redirecionado, independente das configurações, para dispositivos do Firebase Test Lab que executam o Android 12 ou versões mais recentes.

Problemas conhecidos

Alguns dispositivos podem não ser capazes de fazer a codificação com uma taxa de bits suficiente para oferecer suporte ao espelhamento de dispositivos. Nessas situações, um erro pode aparecer na janela Running Devices, bem como registros semelhantes aos seguintes.

2023-06-01 15:32:22,675 [  56094]   WARN - ScreenSharingAgent Samsung SM-A045F API 33 - Too many video encoder errors:
2023-06-01 15:32:22,676 [  56095]   WARN - ScreenSharingAgent Samsung SM-A045F API 33 - encoder: c2.android.vp8.encoder
2023-06-01 15:32:22,676 [  56095]   WARN - ScreenSharingAgent Samsung SM-A045F API 33 - mime type: video/x-vnd.on2.vp8
2023-06-01 15:32:22,676 [  56095]   WARN - ScreenSharingAgent Samsung SM-A045F API 33 - max resolution: 640x640
2023-06-01 15:32:22,676 [  56095]   WARN - ScreenSharingAgent Samsung SM-A045F API 33 - min resolution: 2x2
2023-06-01 15:32:22,676 [  56095]   WARN - ScreenSharingAgent Samsung SM-A045F API 33 - alignment: 2x2
2023-06-01 15:32:22,676 [  56095]   WARN - ScreenSharingAgent Samsung SM-A045F API 33 - max frame rate: 960
2023-06-01 15:32:22,676 [  56095]   WARN - ScreenSharingAgent Samsung SM-A045F API 33 - max frame rate for 288x640: 960
2023-06-01 15:32:22,870 [  56289]   WARN - ScreenSharingAgent Samsung SM-A045F API 33 - max bitrate: 20000000
2023-06-01 15:32:22,871 [  56290]   WARN - ScreenSharingAgent Samsung SM-A045F API 33 - terminated with code 1

Aviso de privacidade

Com base nas configurações de espelhamento de dispositivo, o Android Studio pode iniciar o espelhamento automaticamente para qualquer dispositivo conectado e pareado. Isso pode resultar na divulgação de informações para dispositivos conectados com o comando adb tcpip, porque as informações e os comandos de espelhamento são transmitidos por um canal não criptografado. Além disso, o Android Studio usa um canal não criptografado para se comunicar com o servidor adb. Assim, as informações de espelhamento podem ser interceptadas por outros usuários na máquina host.

Resolver problemas de conexão do dispositivo

Se o dispositivo não se conectar ao Android Studio, tente o seguinte para resolver o problema.

Resolver problemas do Connection Assistant

O Connection Assistant fornece instruções detalhadas para ajudar você a configurar e usar um dispositivo pela conexão adb.

Para iniciar o assistente, selecione Tools > Troubleshoot Device Connections.

O Connection Assistant oferece instruções, controles em contexto e uma lista de dispositivos conectados em uma série de páginas no painel Assistant. Use os botões Next e Previous na parte de baixo do painel Assistant para trabalhar nas páginas conforme necessário:

• Conecte o dispositivo via USB: o Connection Assistant primeiro solicita que você conecte seu dispositivo por USB e fornece um botão Rescan USB devices que você pode usar para iniciar uma nova busca de dispositivos conectados.
• Ative a depuração USB: o Connection Assistant informa como ativar a depuração USB nas opções do desenvolvedor no dispositivo.
• Reinicie o servidor ADB: se o dispositivo ainda não aparecer na lista de dispositivos disponíveis, use o botão Restart ADB server na última página do Connection Assistant. Reiniciar o servidor ADB também faz com que o ADB busque novamente os dispositivos. Se o dispositivo ainda não aparecer na lista de dispositivos disponíveis, siga as etapas de solução de problemas na seção a seguir.

Resolver problemas de conexão USB

Se o Connection Assistant não detectar o dispositivo por USB, tente seguir estas etapas de solução de problemas:

Verificar se o Android Studio se conecta ao Android Emulator

Para verificar se o problema está ou não sendo causado pela conexão entre o Android Studio e o Android Emulator, siga estas etapas:

1. Abra o Gerenciador de dispositivos.
2. Crie um novo AVD se você ainda não tiver um.
3. Execute o emulador usando seu AVD.
4. Realize uma das seguintes ações:
   • Se o Android Studio não conseguir se conectar ao emulador, faça o download do SDK Platform Tools mais recente e tente de novo.
   • Se o emulador for iniciado sem problemas, verifique o cabo USB conforme descrito na seção a seguir.

Verificar o cabo USB

Para verificar se o problema está sendo causado por um cabo USB defeituoso, siga as etapas nesta seção.

Se você tiver outro cabo USB:

1. Conecte o dispositivo usando o cabo secundário.
2. Verifique se o Connection Assistant agora consegue detectar o dispositivo.
3. Se o dispositivo não for detectado, tente o cabo principal novamente.
4. Se o dispositivo ainda não for detectado, presuma que o problema está no dispositivo e verifique se ele está configurado para desenvolvimento, conforme descrito na seção a seguir.

Se você não tiver outro cabo USB, mas tiver outro dispositivo Android:

1. Conecte o dispositivo secundário ao computador.

2. Se o Connection Assistant detectar o dispositivo secundário, presuma que o problema está no dispositivo principal e verifique se ele está configurado para desenvolvimento.

   Se o dispositivo secundário não for detectado, o problema pode estar no cabo USB.

Verificar se o dispositivo está configurado para desenvolvimento

Para verificar se o problema está sendo causado por configurações no dispositivo, siga estas etapas:

1. Siga as etapas na seção Configurar um dispositivo para desenvolvimento.
2. Se isso não resolver o problema, entre em contato com o suporte ao cliente do OEM do dispositivo para receber ajuda. Diga ao representante de suporte ao cliente que o dispositivo não se conecta ao Android Studio usando o ADB.

Resolver problemas de conexão sem fio

Se você estiver com problemas para conectar o dispositivo sem usar fios, tente seguir as etapas de solução de problemas abaixo:

Conferir se a estação de trabalho e o dispositivo atendem aos pré-requisitos

Confira se a estação de trabalho e o dispositivo atendem aos pré-requisitos.

Consulte o guia de solução de problemas do adb

Siga o guia de solução de problemas do adb.

Chave de segurança RSA

Ao conectar um dispositivo com Android 4.2.2 (API de nível 17) ou versão mais recente ao computador, o sistema mostrará uma caixa de diálogo perguntando se você aceita uma Chave RSA que permite a depuração por esse computador. Esse mecanismo de segurança protege dispositivos de usuários porque a depuração USB e outros comandos do adb não podem ser executados, a menos que você consiga desbloquear o dispositivo e confirmar a caixa de diálogo.