Android 빌드

Build and submit Android apps to Google Play Store using Capgo’s dedicated infrastructure.

학습할 내용

• Capgo Native Build를 위한 자격 증명을 구성하는 방법을 배웁니다.
• You will learn how to configure the credentials for Capgo Native Build

__CAPGO_KEEP_0__

• 구글 개발자 계정이 활성화되어 있어야 합니다.
• Android Studio가 설치되어 있어야 합니다.
• Android Studio로 앱을 빌드할 수 있어야 합니다.

주의

이 튜토리얼에서 사용할 앱은 다음과 같습니다: https://github.com/Cap-go/capgo-native-build-tutorial-app

권장: 자동 온보딩

이 모든 것을 수동으로 할 필요가 없습니다. Capgo의 온보딩은 Android signing credentials (keystore + Google Play service account)가 자동으로 생성되고 구성됩니다. — 이는 권장 경로입니다:

bunx @capgo/cli@latest build init --platform android

아래의 수동 가이드는 자체적으로 인증 정보를 설정하거나 Capgo의 내부 동작을 정확히 이해하고 싶은 사람들을 위한 것입니다.

첫 번째 수동 빌드

Capgo을 사용하여 앱을 빌드하기 전에, 우리는 먼저 Capgo을 설정하고, 수동으로 Android 빌드를 먼저 해야 합니다. 수동 빌드를 먼저 하는 것은 몇 가지 이점이 있습니다:

• Capgo의 후속 빌드에 대한 인증 정보를 준비합니다.
• __CAPGO_KEEP_0__의 후속 빌드에 대한 Play Store Console 기록을 생성합니다.

Android Studio를 사용하여 앱을 수동으로 빌드하기

Capgo을 사용하여 앱을 빌드하기 전에, 우리는 Android Studio를 사용하여 앱을 수동으로 빌드해야 합니다.

1. Android Studio를 열기

   실행 bunx cap open android __CAPGO_KEEP_0__

2. Android Studio를 열어 주세요. Build -> Generate Signed App Bundles / APKs

3. 선택하세요. Android App Bundle Android Studio에서 Android App Bundle을 선택하세요. Next

현재 키 스토어 파일이 없습니다. 이 파일은 앱을 서명하는 데 사용되며, Google에게 앱을 개발한 사람임을 알려줍니다.

명령 줄을 사용하여도 가능하지만, 이 튜토리얼에서는 다루지 않습니다.

1. Android Studio에서 새로운 키 스토어를 생성하세요. Create new

2. Fill in the Key Store path

   주의

   이 저장되어야 합니다 - 나중에 사용됩니다

3. 키 스토어 비밀번호를 설정하세요

   주의

   키 스토어와 키 앨리어스의 비밀번호를 동일하게 사용하는 것을 추천합니다.

   주의

   이것은 나중에 사용할 것입니다. __CAPGO_KEEP_0__ 양식의 나머지 부분을 채우세요.

4. 키 별칭을 그대로 유지하세요 (key0)

   1. 인증서 세부 사항을 채우십시오. 가짜 정보로 채웠지만, 실제 정보로 채우십시오.
   2. 안드로이드 스튜디오 양식의 나머지 부분을 채우세요.

   

5. 안드로이드 스튜디오에 OK를 클릭하세요. OK

수동 빌드 완료

1. 모든 키 스토어 정보가 정확하게 입력되어 있는지 확인하고 클릭하세요. Next

2. 선택하세요. release Android Studio에서 릴리즈 빌드 버전을 선택하세요. Create

3. Android Studio에서 빌드가 성공했을 때

   1. 버튼을 클릭하세요 - 이 버튼을 클릭하면 파일 탐색기를 열고 빌드가 보일 수 있어야 합니다.
   2. 파일 탐색기에 빌드가 보이는지 확인하세요. locate Android Studio에서 파일 탐색기에 빌드가 보이는지 확인하세요.

4. Select the

Play Store 콘솔에서 앱을 만듭니다.

1. Go to Google Play 콘솔

2. 개발자 계정을 선택하세요.

3. Click on Create app

4. 앱 이름과 언어를 선택하세요.

5. 앱 카테고리와 앱이 유료인지 무료인지 선택하세요.

6. 이용 약관을 수락합니다.

   주의

   이용 약관을 읽고 이해한 후에 수락해 주세요.

7. 클릭 Create

내부 테스트 그룹 만들기

앱을 만들었으니 내부 테스트 그룹을 만들 수 있습니다. 플레이 스토어에 앱을 모두 공개하지 않기 때문에 내부 테스트 그룹을 만들 필요가 있습니다.

주의

내부 테스트는 실제 출시 전에 플레이 배포 빌드를 빠르게_smoke-test 할 수 있는 가장 빠른 방법입니다.

개발자 계정이 2023년 11월 13일 이후에 생성된 개인 계정인 경우, 내부 테스트는 생산 액세스에 대한 폐쇄 테스트 요구 사항을 대체하지 않습니다. 최소 12명의 옵티드 인 테스터가 14일 연속으로 폐쇄 테스트에 참여해야 하며, 생산 액세스에 대한 폐쇄 테스트를 위해 14일 연속으로 최소 12명의 옵티드 인 테스터가 참여해야 합니다.

1. 내부 테스트로 이동하세요 internal testing Google Play Console 내부 테스트 클릭 Test and release -> Testing -> Internal testing

   

2. Google Play Console 이메일 목록 만들기 클릭 Testers

3. 이메일 목록 이름 Create email list

4. 이름

5. 테스터의 이메일 주소를 추가하세요

6. Enter Enter 그리고 Save

7. 클릭하세요 Create group

8. 새 목록이 선택되어 있는지 확인하고 저장을 클릭하세요 Save

내부 테스트 그룹에 앱 업로드

내부 테스트 그룹을 생성한 후, 내부 테스트 그룹에 앱을 업로드할 수 있습니다.

1. Go to Test and release -> Testing -> Internal testing

2. Click on the Releases 내부 테스트 릴리즈 버튼

3. 새 릴리즈 만들기 Create new release

4. 업로드 Upload

5. AAB 파일 선택

   주의

   Android Studio를 사용하여 수동으로 AAB 파일을 빌드했는지 확인하세요. 이 파일이 Capgo 빌드에 사용할 키스토어와 동일하지 않으면 Capgo 네이티브 빌드는 실패합니다.

6. AAB 파일 업로드를 기다려주세요

7. 클릭 Next

8. 오류를 고치세요

   개인적으로 이 단계에서 나는 오류를 보는데요

   

   이유는 아직 휴대폰 번호를 인증하지 않았기 때문입니다. 인증을 마치고 튜토리얼을 계속 진행하겠습니다.

9. 클릭 Save and publish 이 앱을 내부 테스트 그룹에 게시합니다.

10. 게시를 확인하세요

11. 앱이 게시되었습니다

12. 임시 앱 이름을 가져오세요

내부 테스트 그룹에 대한 초대장을 수락하세요

내부 테스트 그룹에 앱을 업로드한 후에 내부 테스트 그룹에 대한 초대장을 수락할 수 있습니다

1. 이동하세요 Test and release -> Testing -> Internal testing

2. Click on Testers

3. Click on Copy link

4. 휴대폰으로 링크를 보내고 브라우저에서 열어 Accept

5. 초대가 수락되었는지 확인하고 "Play Store에서 다운로드"를 클릭하세요

6. 앱을 설치하세요

   1. 앱을 이미 안드로이드 스튜디오를 사용하여 설치한 경우 uninstall 버튼을 클릭하세요
   2. 클릭하여 install 버튼
   3. __CAPGO_KEEP_0__ Native Build (Android) 설정

   주의

   Play Store에서 앱을 찾을 수 없다면 Play Store에서 올바른 계정을 선택했는지 확인하세요.

Capgo Native Build (Android) 설정

이제 Capgo Native Build의 설정을 시작할 준비가되었습니다. 축하합니다! 🎉

필요 조건	플래그	설명	필수
Keystore 파일	--keystore <path>	APK/AAB을 서명하는 데 사용되는 파일의 경로. .jks/.keystore Yes	Keystore 별칭
Keystore 내의 키의 별칭 이름.	--keystore-alias <alias>	Yes	Keystore 키 패스워드
Keystore file path	--keystore-key-password <password>	__CAPGO_KEEP_0__ 비밀번호.	아래의 주의사항을 참조하세요.
Keystore 저장소 비밀번호.	--keystore-store-password <password>	Keystore 비밀번호. 키/저장소 비밀번호가 일치하면 하나만 제공할 수 있습니다.	아래의 주의사항을 참조하세요.
Play Store 서비스 계정.	--play-config <path>	Play Store 업로드를 위한 JSON 서비스 계정 파일.	예

bunx @capgo/cli@latest build credentials save --platform android \
  --keystore ./path/to/keystore.jks \
  --keystore-alias "your-alias" \
  --keystore-key-password "key-password" \
  --keystore-store-password "store-password" \
  --play-config ./play-store-service-account.json

주의사항.

키와 저장소 암호가 동일한 경우, 하나만 제공하십시오. --keystore-key-password 또는 --keystore-store-password.

Keystore, Keystore 암호, Keystore 키 암호, Keystore 별칭

만약에 수동 빌드 지침을 따랐다면, Keystore가 이미 생성되어야 합니다. 만약 지침을 따르지 않았다면, Keystore를 생성하기 위해 지침을 따르십시오. Google Play 서비스 계정Google Play 서비스 계정

Google Play 서비스 계정을 생성하는 것은 수동적이고 복잡한 과정입니다. 그러나 Google Play에 앱을 업로드하려면 필수적입니다. 다음 사항을 기억하십시오:

필수입니다.

• You NEED __CAPGO_KEEP_0__의 주인으로 Developer Account를 만들면 __CAPGO_KEEP_0__의 주인으로 Developer Account를 만들지 않으면 서비스 계정 설정을 할 수 없습니다.Capacitor를 사용하기 위해 Google Cloud Project를 만들 필요가 있습니다.
• Capacitor를 사용하기 위해 Google Cloud Project를 만들 필요가 있습니다.

Let’s begin.

1. Capacitor를 사용하기 위해 Google Cloud Console로 이동하세요. Capacitor를 사용하기 위해 Google Cloud Console로 이동하세요.

2. Capacitor를 사용하기 위해 Google Cloud Console에서 프로젝트 선택자 클릭하세요.

3. Capacitor를 사용하기 위해 Google Cloud Console에서 프로젝트 선택자 클릭하세요. 만약 프로젝트가 이미 있으면 선택하세요. 그렇지 않으면 새로운 프로젝트를 생성하세요.

   Capacitor를 사용하기 위해 Google Cloud Console에서 프로젝트 선택자 클릭하세요. 만약 프로젝트가 이미 있으면 선택하세요. 그렇지 않으면 새로운 프로젝트를 생성하세요.

   The screenshots below are illustrative - use a name appropriate for your project.

   1. 위의 스크린샷은 예시입니다. 프로젝트 이름을 적절히 설정하세요. New project
   2. 프로젝트 이름을 입력하고 "Create" 버튼을 클릭하세요. Create
   3. 올바른 프로젝트가 선택되어 있는지 확인하세요.

4. 검색바를 클릭하고 "Google Console"을 검색하세요. service accounts 검색 결과에서 "Google Console"을 클릭하세요.

5. Google Console에서 "Create Service Account" 버튼을 클릭하세요. Create service account

6. 서비스 계정에 대한 양식을 채우고 클릭하세요. Done

   1. 이름을 설정할 때는 Capgo Native Build Service Account
   2. 서비스 계정 ID에 대해는 capgo-native-build-service-acc
   3. 설명에 대해서는 채우지 않아도 되지만 Allows Capgo Native Build to build and submit the app to the Play Store

   

7. 새로 생성된 서비스 계정을 클릭하세요. 서비스 계정 목록에서 새로 생성된 서비스 계정을 확인할 수 있습니다. 클릭하세요.

   주의

   이 이메일 주소를 복사하세요. 나중에 필요하니까요.

8. 클릭하세요. Keys 탭

9. __CAPGO_KEEP_0__ Add Key __CAPGO_KEEP_1__ Create new key

10. __CAPGO_KEEP_2__ JSON __CAPGO_KEEP_3__ Create

    주의

    Google Console에서 __CAPGO_KEEP_4__를 클릭하면 새로운 키가 생성되고 JSON 파일이 로컬 머신에 다운로드됩니다. Create JSON 파일을 안전한 곳에 저장해야 합니다.

    __CAPGO_KEEP_5__ WILL 미래에 사용될 것입니다.

11. JSON 파일 다운로드 JSON 파일은 자동으로 다운로드되어야 합니다. 다운로드가 실패한 경우에는 close 닫기

Play Store API 서비스 계정에 대한 접근 허용

Play Store API 서비스 계정에 대한 접근 허용을 위해 새로 생성된 서비스 계정은 아직 Play Store API에 접근할 수 없습니다. Play Store Console로 이동하여

1. Play Store Console로 이동 Play Store Console에서 올바른 개발자 계정을 선택
2. Play Store Console에서 올바른 개발자 계정을 선택
3. 클릭 Users and permissions
4. 클릭 Invite new users
5. __CAPGO_KEEP_0__ 이메일 주소를 복사하세요
6. 로 이동 Account permissions 최소 권한이 필요한 권한을 부여하세요:
   • __CAPGO_KEEP_1__에서 앱에 대한 액세스 권한을 부여하세요 App permissions__CAPGO_KEEP_1__에서 앱을 활성화하세요
   • __CAPGO_KEEP_2__에서 앱에 대한 액세스 권한을 부여하세요 Releases__CAPGO_KEEP_2__에서 앱을 활성화하세요 Create, edit, and roll out releases.
   • If your workflow uses Play App Signing, enable the related signing permission.
   • If you are unsure, use __CAPGO_KEEP_0__ only during setup, then reduce permissions afterward. Admin Google Play Console __CAPGO_KEEP_1__ grant permissions
7. Google Play Console __CAPGO_KEEP_3__ invite user Invite user
8. Google Play Console __CAPGO_KEEP_5__ confirm invitation
9. Google Play Console __CAPGO_KEEP_7__ confirm that the user has been invited

__CAPGO_KEEP_8__ credentials

You are now ready to save the credentials and run your first build. You can save the credentials using the following command:

bunx @capgo/cli@latest build credentials save --platform android \
  --keystore ./path/to/keystore.jks \
  --keystore-alias "your-alias" \
  --keystore-key-password "key-password" \
  --keystore-store-password "store-password" \
  --play-config ./play-store-service-account.json

CI/CD 설정 (GitHub Actions)

If you already completed Keystore, keystore password, keystore key password, keystore alias 및 Google Play 서비스 계정, you already have everything needed for CI/CD. This section only covers how to pass those values as GitHub Actions secrets and environment variables.

1) Credential 파일을 단일 줄 base64로 변환

# Android keystore (.jks or .keystore)
base64 -i ./path/to/keystore.jks | tr -d '\n' > keystore_base64.txt

# Google Play service account JSON
base64 -i ./play-store-service-account.json | tr -d '\n' > play_config_base64.txt

팁

GitHub는 단일 줄 값이어야 합니다. tr -d '\n' base64 출력에서 줄 바꿈을 제거합니다.

2) 저장소 비밀번호 생성

In GitHub > Repository > Settings > Secrets and variables > Actions, add:

,	비밀 이름
CAPGO_TOKEN	Capgo API 토큰
APP_ID	Capgo 앱 ID (예시: com.example.app)
ANDROID_KEYSTORE_FILE	콘텐츠 keystore_base64.txt
KEYSTORE_KEY_ALIAS	키 스토어 별칭 키 스토어(키 스토어 비밀번호, 키 스토어 키 비밀번호, 키 스토어 별칭)
KEYSTORE_KEY_PASSWORD	키 스토어 키 비밀번호
KEYSTORE_STORE_PASSWORD	키 스토어 저장소 비밀번호
PLAY_CONFIG_JSON	콘텐츠 play_config_base64.txt

메모

키와 저장소 비밀번호가 같다면, 하나만 제공할 수 있습니다. KEYSTORE_KEY_PASSWORD or KEYSTORE_STORE_PASSWORD.

3) GitHub 환경 변수를 사용하세요.

github/workflows/android-build.yml

name: Android Cloud Build

on:
  workflow_dispatch:
  push:
    branches: [main]

jobs:
  android-build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: oven-sh/setup-bun@v2
        with:
          bun-version: latest
      - name: Request Android build with Capgo
        run: bunx @capgo/cli@latest build request ${{ secrets.APP_ID }} --platform android
        env:
          CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
          ANDROID_KEYSTORE_FILE: ${{ secrets.ANDROID_KEYSTORE_FILE }}
          KEYSTORE_KEY_ALIAS: ${{ secrets.KEYSTORE_KEY_ALIAS }}
          KEYSTORE_KEY_PASSWORD: ${{ secrets.KEYSTORE_KEY_PASSWORD }}
          KEYSTORE_STORE_PASSWORD: ${{ secrets.KEYSTORE_STORE_PASSWORD }}
          PLAY_CONFIG_JSON: ${{ secrets.PLAY_CONFIG_JSON }}

팁

이 설정으로 CI는 환경 변수만을 통해 자격 증명을 전송합니다. 서명 파일을 커밋하거나 워크플로우 아티팩트로 업로드할 필요가 없습니다.

빌드 실행

축하합니다! 첫 번째 빌드를 실행할 준비가 되었습니다.

실행:

bunx @capgo/cli@latest build request com.example.app --platform android

이것이 빌드 프로세스를 시작할 것입니다 🍾🥂

Play 리뷰에 제출하기

기본적으로 안드로이드 릴리즈 빌드는 Google Play로 업로드되고, Play 콘솔에서 릴리즈를 완료할 때까지 비활성화 상태로 남아 있습니다. CI 릴리즈에서 Play 릴리즈를 자동으로 제출하려면, 다음을 실행하세요: --submit-to-store-review 릴리즈 빌드와 함께:

npx @capgo/cli@latest build request com.example.app \
  --platform android \
  --build-mode release \
  --submit-to-store-review \
  --store-release-name "1.2.3" \
  --store-release-notes "General improvements" \
  --store-release-notes-locale "en-US=General improvements" \
  --store-release-notes-locale "nl-NL=Algemene verbeteringen" \
  --store-release-notes-locale "fr-FR=Ameliorations generales"

이것은 일반 업로드 경로와 동일한 Google Play 서비스 계정 설정이 필요합니다 (CI 또는 로컬로 저장된 안드로이드 자격 증명).PLAY_CONFIG_JSON Google Play 릴리즈 이름으로 사용됩니다. --store-release-name Play 변경 내역의 기본값이며, 각 --store-release-notes 각 --store-release-notes-locale "locale=notes" 해당 지역의 Play 변경 로그를 지역화 한 Capgo가 작성합니다. completed; Play 콘솔에서 관리 된 게시를 활성화 한 경우, Google은 승인 후에도 수동으로 게시를 기다릴 수 있습니다.

Android Builds에서 계속 진행하세요

Android Builds를 사용하여 CI/CD 자동화 계획을 만드는 경우, __CAPGO_KEEP_0__ CI/CD와 연결하세요. CI/CD 자동화 계획을 만드는 경우, __CAPGO_KEEP_0__ CI/CD와 연결하세요. Android Builds를 사용하여 CI/CD 자동화 계획을 만드는 경우, __CAPGO_KEEP_0__ CI/CD의 제품 워크플로우에서 __CAPGO_KEEP_0__ CI/CD와 연결하세요. CI/CD 자동화 계획을 만드는 경우, Capgo CI/CD의 제품 워크플로우에서 Capgo CI/CD와 연결하세요. Android Builds를 사용하여 CI/CD 자동화 계획을 만드는 경우, Capgo Native Builds의 제품 워크플로우에서 Capgo Native Builds와 연결하세요. CI/CD 자동화 계획을 만드는 경우, Capgo Native Builds의 제품 워크플로우에서 Capgo Native Builds와 연결하세요. Android Builds를 사용하여 CI/CD 자동화 계획을 만드는 경우, Capgo Integrations의 제품 워크플로우에서 Capgo Integrations와 연결하세요. CI/CD 자동화 계획을 만드는 경우, Capgo Integrations의 제품 워크플로우에서 Capgo Integrations와 연결하세요. 제품 워크플로우에서 Capgo 통합에 대해 CI/CD 통합 CI/CD 통합에 대한 구현 세부 정보, 그리고 GitHub 액션 통합 GitHub 액션 통합에 대한 구현 세부 정보