하드웨어 기기에서 앱 실행

Android 앱을 사용자에게 출시하기 전에 항상 실제 기기에서 테스트하세요. 이 페이지에서는 Android 디버그 브리지(ADB) 연결을 통한 테스트 및 디버깅을 위해 개발 환경 및 Android 기기를 설정하는 방법을 설명합니다.

기기를 개발용으로 설정

기기에서 디버깅을 시작하려면 기기를 연결하는 데 USB 케이블을 사용할지 Wi-Fi를 사용할지 결정합니다. 결정한 후 다음 작업을 실행하세요.

  1. 기기에서 설정 앱을 열고 개발자 옵션을 선택한 다음 USB 디버깅을 사용 설정합니다(옵션이 표시되는 경우).

  2. 기기를 감지하도록 시스템을 설정합니다.

    • ChromeOS: 추가 구성이 필요하지 않습니다.
    • macOS: 추가 구성이 필요하지 않습니다.
    • Windows: ADB용 USB 드라이버를 설치합니다(필요한 경우). 설치 가이드와 OEM 드라이버의 링크는 OEM USB 드라이버 설치를 참고하세요.

    • Ubuntu Linux: 다음을 설정합니다.

      • ADB를 사용하려는 각 사용자는 plugdev 그룹에 있어야 합니다. plugdev 그룹에 있지 않다는 오류 메시지가 표시되면 다음 명령어를 사용하여 해당 그룹에 추가합니다.
      sudo usermod -aG plugdev $LOGNAME

      그룹은 로그인 시에만 업데이트되므로 이 변경사항을 적용하려면 로그아웃해야 합니다. 다시 로그인하면 id를 사용하여 plugdev 그룹에 있는지 확인할 수 있습니다.

      • 시스템에는 기기에 적용되는 udev 규칙이 설치되어 있어야 합니다. android-sdk-platform-tools-common 패키지에는 커뮤니티에서 유지하는 Android 기기용 기본 udev 규칙 세트가 포함되어 있습니다. 설치하려면 다음 명령어를 사용하세요.
      apt-get install android-sdk-platform-tools-common

USB를 사용하여 기기에 연결

USB를 사용하여 설정되고 연결되면 Android 스튜디오에서 Run 을 클릭하여 기기에서 앱을 빌드하고 실행합니다.

다음과 같이 adb를 사용하여 명령어를 실행할 수도 있습니다.

  • android_sdk/platform-tools/ 디렉터리의 adb devices 명령어를 실행하여 기기가 연결되어 있는지 확인합니다. 연결된 경우 기기가 나열됩니다.
  • adb 명령어를 -d 플래그와 함께 실행하여 기기를 타겟팅합니다.

Wi-Fi를 사용하여 기기에 연결

Android 11 이상에서는 Android 디버그 브리지(ADB)를 통해 워크스테이션에서 무선으로 앱을 배포하고 디버깅할 수 있도록 지원합니다. 예를 들어 USB를 통해 기기를 물리적으로 연결하거나 드라이버 설치와 같은 일반적인 USB 연결 문제와 씨름하지 않고도 디버깅 가능한 앱을 여러 원격 기기에 배포할 수 있습니다.

무선 디버깅을 사용하려면 페어링 코드를 사용하여 기기와 워크스테이션을 페어링해야 합니다. 시작하려면 다음 단계를 완료하세요.

  1. 워크스테이션과 기기가 동일한 무선 네트워크에 연결되어 있는지 확인합니다.
  2. 기기에서 Android 11 이상을 실행 중이어야 합니다. 자세한 내용은 Android 버전 확인 및 업데이트를 참고하세요.
  3. 최신 버전의 Android 스튜디오가 설치되어 있는지 확인합니다. 여기에서 다운로드하세요.
  4. 워크스테이션에서 최신 버전의 SDK 플랫폼 도구로 업데이트합니다.

기기에 연결하려면 다음 단계를 따르세요.

  1. Android 스튜디오를 열고 실행 구성 메뉴에서 Pair Devices Using Wi-Fi를 선택합니다.
    실행 구성 드롭다운
    그림 1. 실행 구성 메뉴

    그림 2와 같이 Pair devices over Wi-Fi 대화상자가 표시됩니다.
    Pair devices over Wi-Fi 팝업 창의 스크린샷
    그림 2. QR 코드 또는 페어링 코드를 사용하여 기기를 페어링하는 대화상자
  2. 기기에서 개발자 옵션을 사용 설정합니다.
  3. 기기에서 Wi-Fi를 통한 디버깅을 사용 설정합니다.
    무선 디버깅 시스템 설정이 표시된 Pixel 휴대전화의 스크린샷
    그림 3. Google Pixel 휴대전화의 무선 디버깅 설정
  4. 무선 디버깅을 탭하고 기기를 페어링합니다.
    1. QR 코드를 사용하여 기기를 페어링하려면 그림 2와 같이 Pair device with QR code를 선택하고 QR 코드를 스캔합니다.
    2. 페어링 코드를 사용하여 기기를 페어링하려면 Pair new devices over Wi-Fi 대화상자에서 Pair device with pairing code를 선택합니다. 기기에서 페어링 코드를 사용하여 페어링을 선택합니다. 6자리 코드가 표시됩니다. Pair devices over Wi-Fi 창에 기기가 표시되면 기기에 표시된 6자리 코드를 입력하고 Pair를 선택합니다.
      페어링 코드 입력 예 스크린샷
      그림 4. 6자리 페어링 코드 입력의 예
  5. 페어링되면 기기로 앱 배포를 시도할 수 있습니다.

다른 기기를 페어링하거나 워크스테이션에서 이 기기를 삭제하려면 다음 단계를 따르세요.

  1. 기기에서 무선 디버깅으로 이동합니다.
  2. 페어링된 기기 아래에서 워크스테이션 이름을 탭합니다.
  3. 삭제를 선택합니다.

기기 미러링

Android 스튜디오의 Running Devices 창에서 기기를 미러링할 수 있습니다. 기기 화면을 Android 스튜디오로 직접 스트리밍하면 스튜디오 IDE 자체에서 바로 앱 시작하기, 앱과 상호 작용하기, 화면 회전하기, 휴대전화 접기 및 펼치기, 볼륨 변경하기와 같은 일반적인 작업을 실행할 수 있습니다.

기기 미러링은 USB 또는 무선 디버깅이 사용 설정된 컴퓨터에 연결된 기기가 있는 경우 항상 사용할 수 있습니다. Running Devices 창 또는 기기 관리도구(View > Tool Windows > Device Manager)를 사용하여 미러링을 시작하고 중지할 수 있습니다. 설정(Settings > Tools > Device Mirroring)에서 기기 미러링이 활성화되는 시점을 맞춤설정할 수도 있습니다.

실행 중인 기기 UI

오디오 리디렉션

기기 미러링을 사용하면 연결된 실제 기기의 오디오를 컴퓨터 스피커나 헤드폰으로 리디렉션할 수 있습니다. 오디오 리디렉션을 사용하면 헤드폰을 컴퓨터에 연결된 상태로 유지하면서 한 기기에 수동으로 다시 연결하지 않고도 컴퓨터와 연결된 휴대전화를 모두 들을 수 있습니다. 오디오 리디렉션을 사용 설정하려면 File (macOS의 경우 Android Studio) > Settings > Tools > Device Mirroring으로 이동하여 Redirect audio from local devices를 선택합니다. Android 12 이상을 실행하는 Firebase Test Lab 기기의 경우 설정과 관계없이 오디오가 항상 리디렉션됩니다.

알려진 문제

일부 기기는 기기 미러링을 지원하기에 충분한 비트 전송률로 인코딩하지 못할 수 있습니다. 이러한 상황에서는 Running Devices 창의 오류와 다음과 같은 로그가 표시될 수 있습니다.

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

개인정보처리방침

기기 미러링 설정에 따라 Android 스튜디오는 연결 및 페어링된 기기의 기기 미러링을 자동으로 시작할 수 있습니다. 따라서 adb tcpip 명령어로 연결된 기기의 정보가 공개될 수 있습니다. 미러링 정보와 명령어가 암호화되지 않은 채널을 통해 전달되기 때문입니다. 또한 Android 스튜디오는 암호화되지 않은 채널을 사용하여 adb 서버와 통신하므로 미러링 정보를 호스트 머신의 다른 사용자가 가로챌 수 있습니다.

기기 연결 문제 해결

기기가 Android 스튜디오에 연결되지 않으면 다음 단계를 따라 문제를 해결해 보세요.

연결 도우미로 문제 해결

연결 도우미에서는 ADB 연결을 통해 기기를 설정하고 사용할 수 있도록 단계별 안내를 제공합니다.

도우미를 시작하려면 Tools > Troubleshoot Device Connections를 선택합니다.

연결 도우미는 Assistant 패널의 여러 페이지에 걸쳐 안내, 문맥에 맞는 컨트롤, 연결된 기기 목록을 제공합니다. Assistant 패널 하단의 Next 및 Previous 버튼을 사용하여 필요에 따라 페이지 간을 이동합니다.

  • USB를 통해 기기 연결: 연결 도우미에서는 먼저 USB를 통해 기기를 연결하라는 메시지를 표시하고 연결된 기기 검색을 새롭게 시작할 수 있는 Rescan USB devices 버튼을 표시합니다.
  • USB 디버깅 사용 설정: 그런 다음 연결 도우미가 기기 내의 개발자 옵션에서 USB 디버깅을 사용 설정하는 방법을 알려줍니다.
  • ADB 서버 다시 시작: 아직도 기기가 사용 가능한 기기 목록에 표시되지 않으면 연결 도우미의 마지막 페이지에 있는 Restart ADB server 버튼을 사용합니다. ADB 서버를 다시 시작하면 ADB도 기기를 다시 검색합니다. 그래도 기기가 사용 가능한 기기 목록에 표시되지 않으면 다음 섹션의 문제 해결 단계를 시도해 보세요.

USB 연결 문제 해결

연결 도우미가 USB를 통해 기기를 감지하지 못하는 경우 다음 문제 해결 단계에 따라 문제를 해결하세요.

Android 스튜디오가 Android Emulator에 연결되는지 확인

Android 스튜디오와 Android Emulator 간의 연결 문제로 인해 문제가 발생하는지 확인하려면 다음 단계를 따르세요.

  1. 기기 관리도구를 엽니다.
  2. 새 AVD를 만듭니다(아직 없는 경우).
  3. AVD를 사용하여 에뮬레이터를 실행합니다.
  4. 다음 중 한 가지 방법을 사용합니다.
    • Android 스튜디오에서 에뮬레이터에 연결할 수 없으면 최신 SDK 플랫폼 도구를 다운로드하고 다시 시도해 보세요.
    • 에뮬레이터가 시작되면 다음 섹션에 설명된 대로 USB 케이블을 확인합니다.

USB 케이블 확인

USB 케이블의 결함으로 인해 문제가 발생하는지 확인하려면 이 섹션의 단계를 따르세요.

다른 USB 케이블이 있는 경우:

  1. 보조 케이블을 사용하여 기기를 연결합니다.
  2. 이제 연결 도우미가 기기를 감지할 수 있는지 확인합니다.
  3. 기기가 감지되지 않으면 기본 케이블을 사용하여 다시 시도합니다.
  4. 그래도 기기가 감지되지 않으면 기기에 문제가 있다고 가정하고 다음 섹션에 설명된 대로 기기가 개발용으로 설정되어 있는지 확인합니다.

다른 USB 케이블은 없지만 다른 Android 기기가 있는 경우:

  1. 보조 기기를 컴퓨터에 연결합니다.

  2. 연결 도우미가 보조 기기를 감지할 수 있으면 기본 기기에 문제가 있다고 가정하고 기기가 개발용으로 설정되어 있는지 확인합니다.

    보조 기기가 감지되지 않으면 USB 케이블에 문제가 있을 수 있습니다.

기기가 개발용으로 설정되어 있는지 확인

기기의 설정으로 인해 문제가 발생하는지 확인하려면 다음 단계를 따르세요.

  1. 기기를 개발용으로 설정 섹션의 단계를 따릅니다.
  2. 그래도 문제가 해결되지 않으면 기기 OEM의 고객 지원팀에 문의하세요. 고객 지원 담당자에게 기기가 ADB를 사용하여 Android 스튜디오에 연결되지 않는다고 이야기하세요.

무선 연결 문제 해결

기기를 무선으로 연결하는 데 문제가 있다면 다음 문제 해결 단계에 따라 문제를 해결할 수 있습니다.

워크스테이션과 기기가 기본 요건을 충족하는지 확인

무선 디버깅 기본 요건을 충족하려면 다음을 확인하세요.

다른 알려진 문제 확인

다음은 Android 스튜디오의 무선 디버깅과 관련하여 현재 알려진 문제 목록과 해결 방법입니다.

  • Wi-Fi가 연결되지 않음: 회사 Wi-Fi 네트워크와 같은 일부 Wi-Fi 네트워크는 P2P 연결을 차단하고 Wi-Fi를 통해 연결하는 것을 허용하지 않을 수 있습니다. 케이블 또는 다른 Wi-Fi 네트워크로 연결해 보세요.
  • 가끔 Wi-Fi를 통한 adb가 자동으로 사용 중지됨: 이 문제는 기기가 Wi-Fi 네트워크를 전환하거나 네트워크에서 연결 해제되면 발생할 수 있습니다.

RSA 보안 키

Android 4.2.2(API 수준 17) 이상을 실행하는 기기를 컴퓨터에 연결하면 시스템에서는 이 컴퓨터를 통한 디버깅을 허용하는 RSA 키를 수락할지 묻는 대화상자를 표시합니다. 이 보안 메커니즘을 통해 사용자 기기가 보호됩니다. 개발자가 기기를 잠금 해제하고 대화상자를 승인하지 않는 한 USB 디버깅 및 기타 adb 명령어가 실행될 수 없기 때문입니다.