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.

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 se conectar ao dispositivo, siga estas etapas:

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

   

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

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

   

   Figura 2. Dialog to pair devices using QR code or pairing code.

2. Ative as Opções do desenvolvedor no dispositivo.
3. Ative a depuração por Wi-Fi no dispositivo.

   

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

4. Toque em Depuração por Wi-Fi e faça o pareamento do dispositivo:
   1. Se quiser usar um QR code, selecione Parear o dispositivo com um QR code e leia o QR code mostrado na Figura 2.
   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. Aparecerá um código de seis dígitos. Quando seu dispositivo aparecer na janela Pair devices over Wi-Fi, digite o código de seis dígitos mostrado no dispositivo e selecione Pair.

      

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

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

Se quiser parear um dispositivo diferente ou remover o seu da estação de trabalho:

1. Acesse Depuração por Wi-Fi no dispositivo.
2. Toque no nome da estação de trabalho em Dispositivos pareados.
3. Selecione Esquecer.

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 dispositivo, você pode 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 o som do computador e do smartphone conectado sem precisar se reconectar manualmente a um dispositivo 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, independentemente das configurações, para dispositivos do Firebase Test Lab com Android 12 ou mais recente.

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

Para atender aos pré-requisitos da depuração por Wi-Fi, confira se:

• A estação de trabalho e o dispositivo estão conectados à mesma rede sem fio.
• seu dispositivo tem o Android 11 ou uma versão mais recente. Para mais informações, consulte Verificar e atualizar a versão do Android.
• Você tem a versão mais recente do Android Studio. Você pode fazer o download dele na página principal do Android Studio.
• Você tem a versão mais recente do SDK Platform-Tools na estação de trabalho.

Conferir se há outros problemas conhecidos

Veja a seguir uma lista dos problemas conhecidos atuais da depuração por Wi-Fi no Android Studio e como eles podem ser resolvidos:

• O Wi-Fi não conecta: algumas redes Wi-Fi, como as corporativas, podem bloquear conexões P2P e não permitir que você se conecte ao Wi-Fi. Tente conectar o dispositivo com um cabo ou a outra rede.
• Às vezes, o adb por Wi-Fi é desativado automaticamente: isso pode acontecer se o dispositivo alternar entre redes Wi-Fi ou se desconectar da rede.

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.