Android 개발

Android 기기에서는 직접 만든 앱을 자유롭게 실행할 수 있습니다. 게임 버전을 빌드해서 Android 기기에 복사하는 과정도 매우 간단합니다. 이 매뉴얼은 게임을 Android용으로 번들링하는 데 필요한 단계를 설명합니다. 개발 중에는 컨텐츠와 코드를 기기에 직접 핫 리로드할 수 있으므로 development app을 통해 게임을 실행하는 방식을 선호하는 경우가 많습니다.

Android 및 Google Play 서명 프로세스

Android는 모든 APK가 기기에 설치되거나 업데이트되기 전에 인증서로 디지털 서명되어 있어야 합니다. Android App Bundles를 사용하는 경우 Play Console에 업로드하기 전에 앱 번들만 서명하면 되며, 나머지는 Play App Signing이 처리합니다. 하지만 Google Play, 다른 앱 스토어 또는 스토어 외부 배포를 위해 앱을 수동으로 서명할 수도 있습니다.

Defold 에디터나 커맨드 라인 도구에서 Android 어플리케이션 번들을 만들 때, 어플리케이션 서명에 사용할 keystore(인증서와 키가 들어 있음)와 keystore password를 제공할 수 있습니다. 제공하지 않으면 Defold가 debug keystore를 생성하고 이를 사용해 어플리케이션 번들을 서명합니다.

keystore 만들기

Android Studio를 사용해 keystore를 만들거나 터미널/명령 프롬프트에서 만들 수 있습니다.

keytool -genkey -v -noprompt -dname "CN=John Smith, OU=Area 51, O=US Air Force, L=Unknown, ST=Nevada, C=US" -keystore mykeystore.keystore -storepass 5Up3r_53cR3t -alias myAlias -keyalg RSA -validity 9125

이 명령은 키와 인증서가 들어 있는 mykeystore.keystore라는 keystore 파일을 만듭니다. 키와 인증서에 대한 액세스는 암호 5Up3r_53cR3t로 보호됩니다. 키와 인증서는 25년(9125일) 동안 유효합니다. 생성된 키와 인증서는 alias myAlias로 식별됩니다.

Android 어플리케이션 번들 만들기

에디터를 사용하면 게임용 독립 어플리케이션 번들을 쉽게 만들 수 있습니다. 번들링하기 전에 game.project 프로젝트 설정 파일에서 앱에 사용할 아이콘, version code 등을 지정할 수 있습니다.

번들링하려면 메뉴에서 Project ▸ Bundle... ▸ Android Application...을 선택합니다.

에디터가 무작위 디버그 인증서를 자동으로 만들게 하려면 Keystore 및 Keystore password 필드를 비워 둡니다.

특정 keystore로 번들을 서명하려면 Keystore와 Keystore password를 지정합니다. Keystore는 .keystore 파일 확장자를 가진 파일이어야 하며, 암호는 .txt 확장자를 가진 텍스트 파일에 저장되어 있어야 합니다. keystore 안의 키가 keystore 자체와 다른 암호를 사용하는 경우 Key password를 지정할 수도 있습니다.

Defold는 APK와 AAB 파일 생성을 모두 지원합니다. Bundle Format 드롭다운에서 APK 또는 AAB를 선택합니다.

어플리케이션 번들 설정을 구성했으면 Create Bundle을 누릅니다. 그러면 컴퓨터에서 번들을 만들 위치를 지정하라는 메시지가 표시됩니다.

빌드 변형

게임을 번들링할 때는 사용할 엔진 유형을 선택해야 합니다. 기본 옵션은 세 가지입니다:

• Debug
• Release
• Headless

이 서로 다른 버전은 Build variants라고도 부릅니다.

Debug

이 유형의 실행 파일은 여러 유용한 디버깅 기능을 포함하고 있으므로 일반적으로 게임 개발 중에 사용됩니다:

• 프로파일러 - 성능 및 사용량 카운터를 수집하는 데 사용됩니다. 프로파일러 사용 방법은 프로파일링 매뉴얼에서 확인하세요.
• 로깅 - 로깅이 활성화되어 있으면 엔진이 시스템 정보, 경고, 오류를 로그에 기록합니다. 엔진은 Lua print() 함수의 로그와 dmLogInfo(), dmLogError() 등을 사용하는 네이티브 익스텐션의 로그도 출력합니다. 이러한 로그를 읽는 방법은 게임 및 시스템 로그 매뉴얼에서 확인하세요.
• 핫 리로드 - 핫 리로드는 게임이 실행 중일 때 개발자가 리소스를 다시 로드할 수 있게 해 주는 강력한 기능입니다. 사용 방법은 핫 리로드 매뉴얼에서 확인하세요.
• 엔진 서비스 - 여러 열린 TCP 포트와 서비스를 통해 게임의 디버그 버전에 연결하고 상호작용할 수 있습니다. 이 서비스에는 위에서 언급한 핫 리로드 기능, 원격 로그 액세스, 프로파일러뿐 아니라 엔진과 원격으로 상호작용하기 위한 다른 서비스도 포함됩니다. 엔진 서비스에 대한 자세한 내용은 개발자 문서에서 확인하세요.

Release

이 변형은 디버깅 기능이 비활성화되어 있습니다. 게임을 앱 스토어에 릴리스하거나 다른 방식으로 플레이어에게 공유할 준비가 되었을 때 이 옵션을 선택해야 합니다. 다음과 같은 여러 이유로 디버깅 기능이 활성화된 게임을 릴리스하는 것은 권장되지 않습니다:

• 디버깅 기능은 바이너리에서 약간의 크기를 차지하며, 릴리스된 게임의 바이너리 크기를 가능한 한 작게 유지하는 것이 모범 사례입니다.
• 디버깅 기능은 CPU 시간도 약간 사용합니다. 사용자가 저사양 하드웨어를 사용하는 경우 게임 성능에 영향을 줄 수 있습니다. 모바일 폰에서는 CPU 사용량 증가가 발열과 배터리 소모에도 영향을 줍니다.
• 디버깅 기능은 보안, 치팅 또는 부정행위 관점에서 플레이어에게 공개되어서는 안 되는 게임 정보를 노출할 수 있습니다.

Headless

이 실행 파일은 그래픽과 사운드 없이 실행됩니다. 즉 CI 서버에서 게임 유닛/스모크 테스트를 실행하거나, 클라우드에서 게임 서버로 사용할 수도 있습니다.

Android 어플리케이션 번들 설치하기

APK 설치하기

.apk 파일은 adb 도구를 사용해 기기에 복사하거나 Google Play developer console을 통해 Google Play에 업로드할 수 있습니다.

adb 커맨드 라인 도구는 Android 기기와 상호작용하는 데 사용하는, 사용하기 쉽고 다용도로 활용할 수 있는 프로그램입니다. Mac, Linux, Windows용 Android SDK Platform-Tools의 일부로 adb를 다운로드하고 설치할 수 있습니다.

Android SDK Platform-Tools는 https://developer.android.com/studio/releases/platform-tools 에서 다운로드하세요. adb 도구는 /platform-tools/ 안에 있습니다. 또는 플랫폼별 패키지를 각 패키지 매니저를 통해 설치할 수 있습니다.

Ubuntu Linux:

$ sudo apt-get install android-tools-adb

Fedora 18/19:

$ sudo yum install android-tools

macOS (Homebrew)

$ brew cask install android-platform-tools

Android 기기를 USB로 컴퓨터에 연결한 다음 다음 명령을 실행하여 adb가 작동하는지 확인할 수 있습니다.

$ adb devices
List of devices attached
31002535c90ef000    device

기기가 표시되지 않으면 Android 기기에서 USB debugging이 활성화되어 있는지 확인하세요. 기기의 Settings를 열고 Developer options(또는 Development)를 찾으세요.

$ adb install Defold\ examples.apk
4826 KB/s (18774344 bytes in 3.798s)
  pkg: /data/local/tmp/my_app.apk
Success

에디터를 사용해 APK 설치하기

Bundle 대화상자의 “Install on connected device” 및 “Launch installed app” 체크박스를 사용해 .apk 파일을 설치하고 실행할 수 있습니다.

이 기능이 작동하려면 ADB가 설치되어 있고 연결된 기기에서 USB debugging이 활성화되어 있어야 합니다. 에디터가 ADB 커맨드 라인 도구의 설치 위치를 감지하지 못하면 Preferences에서 위치를 지정해야 합니다.

AAB 설치하기

.aab 파일은 Google Play developer console을 통해 Google Play에 업로드할 수 있습니다. 또한 Android bundletool을 사용해 .aab 파일에서 .apk 파일을 생성하고 로컬에 설치할 수도 있습니다.

권한

Defold 엔진의 모든 기능이 작동하려면 여러 권한이 필요합니다. 권한은 game.project 프로젝트 설정 파일에 지정된 AndroidManifest.xml에 정의됩니다. Android 권한에 대한 자세한 내용은 공식 문서에서 확인할 수 있습니다. 기본 메니페스트에서는 다음 권한을 요청합니다.

android.permission.INTERNET and android.permission.ACCESS_NETWORK_STATE (Protection level: normal)

어플리케이션이 네트워크 소켓을 열고 네트워크에 대한 정보에 액세스할 수 있게 합니다. 이 권한은 인터넷 액세스에 필요합니다. (Android 공식 문서) 및 (Android 공식 문서).

android.permission.WAKE_LOCK (Protection level: normal)

PowerManager WakeLocks를 사용해 프로세서가 sleep 상태가 되거나 화면이 어두워지는 것을 막을 수 있게 합니다. 이 권한은 푸시 알림을 받는 동안 기기가 잠시 sleep 상태가 되지 않도록 하는 데 필요합니다. (Android 공식 문서)

AndroidX 사용하기

AndroidX는 더 이상 유지보수되지 않는 기존 Android Support Library를 크게 개선한 것입니다. AndroidX 패키지는 기능 동등성과 새 라이브러리를 제공하여 Support Library를 완전히 대체합니다. Asset Portal의 Android 익스텐션 대부분은 AndroidX를 지원합니다. AndroidX를 사용하지 않으려면 어플리케이션 메니페스트에서 Use Android Support Lib를 체크해 기존 Android Support Library를 명시적으로 활성화할 수 있습니다.

FAQ

Q: Android에서 navigation bar와 status bar를 숨길 수 있나요?

A: 예, game.project 파일의 Android 섹션에서 immersive_mode 설정값을 설정하세요. 이렇게 하면 앱이 전체 화면을 사용하고 화면의 모든 터치 이벤트를 캡처할 수 있습니다.

Q: Defold 게임을 기기에 설치할 때 “Failure [INSTALL_PARSE_FAILED_INCONSISTENT_CERTIFICATES]”가 표시되는 이유는 무엇인가요?

A: Android는 새 인증서로 앱을 설치하려고 하는 것을 감지합니다. 디버그 빌드를 번들링할 때는 각 빌드가 임시 인증서로 서명됩니다. 새 버전을 설치하기 전에 이전 앱을 제거하세요:

$ adb uninstall com.defold.examples
Success
$ adb install Defold\ examples.apk
4826 KB/s (18774344 bytes in 3.798s)
      pkg: /data/local/tmp/Defold examples.apk
Success

Q: 특정 익스텐션으로 빌드할 때 AndroidManifest.xml에서 충돌하는 프로퍼티에 대한 오류가 표시되는 이유는 무엇인가요?

A: 두 개 이상의 익스텐션이 같은 프로퍼티 태그를 포함하지만 서로 다른 값을 가진 Android Manifest stub을 제공할 때 발생할 수 있습니다. 예를 들어 Firebase와 AdMob에서 이런 일이 발생한 적이 있습니다. 빌드 오류는 다음과 비슷합니다:

SEVERE: /tmp/job4531953598647135356/upload/AndroidManifest.xml:32:13-58
Error: Attribute property#android.adservices.AD_SERVICES_CONFIG@resource
value=(@xml/ga_ad_services_config) from AndroidManifest.xml:32:13-58 is also
present at AndroidManifest.xml:92:13-59 value=(@xml/gma_ad_services_config).
Suggestion: add 'tools:replace="android:resource"' to <property> element at
AndroidManifest.xml to override.

이 문제와 우회 방법에 대한 자세한 내용은 보고된 Defold 이슈 #9453와 Google 이슈 #327696048에서 읽을 수 있습니다.