Android 빌드

설치 단계와 이 플러그인의 전체 마크다운 가이드를 포함한 설정 명령어를 복사하세요.

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

What you will learn

Capgo 네이티브 빌드를 통해 앱을 업로드하는 방법을 배웁니다.
Capgo 네이티브 빌드에 대한 인증 정보를 구성하는 방법을 배웁니다.

필수 조건

활성 Google Developer 계정이 필요합니다.
Android Studio가 설치되어 있어야 합니다.
Android Studio로 앱을 성공적으로 빌드할 수 있어야 합니다.

Capgo의 온보딩은 Android 서명 인증서(keystore + Google Play 서비스 계정)를 자동으로 생성하고 구성합니다. 이 절차는 권장하는 방법입니다.

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

Capgo의 인증서를 수동으로 설정하거나 인증서가 어떻게 작동하는지 이해하고 싶은 경우에만 이 아래의 수동 가이드를 사용하세요.

첫 번째 수동 빌드

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

앞으로의 Capgo 빌드에 인증서를 준비합니다.
Play Store 콘솔에 기록을 생성합니다.

Android Studio를 사용하여 앱을 수동으로 빌드합니다.

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

Android Studio 열기

실행 bunx cap open android Android Studio 프로젝트를 열기 위해
클릭 Build -> Generate Signed App Bundles / APKs
선택 Android App Bundle Android Studio에서 Android App Bundle 선택 Next

Keystore 생성

현재, 키 스토어 파일이 누락되어 있습니다. 이 파일은 앱을 서명하는 데 사용되며, Google에게 앱을 개발한 이는 누구인지 알려줍니다. GUI 방법을 사용하여 Android Studio를 통해 생성합니다. 명령 줄을 사용하여도 가능하지만, 이 튜토리얼에서는 다루지 않습니다.

클릭 Create new
키 스토어 경로를 입력하세요

이 저장해야 합니다 - 나중에 사용할 것입니다
키 스토어 비밀번호를 설정하세요

Key Store와 Key Alias에 동일한 암호를 사용하는 것을 추천합니다.

이 저장해야 합니다 - 나중에 사용할 것입니다
양식의 나머지 부분을 채우세요
1. Key Alias를 그대로 유지하세요 (key0)
2. 인증서 세부 정보를 채우세요. 나중에 실제 정보로 채울 것입니다.
Click on OK

수동 빌드 완료

키 스토어의 모든 세부 정보가 정확하게 입력되어 있는지 확인하고 Next
선택하세요 release 빌드 버전을 선택하고 Create
빌드가 성공하면 다음 화면을 볼 수 있습니다
1. 빌드가 성공한 것을 나타내는 팝업입니다.
2. Click on the locate 버튼을 클릭하면 파일 탐색기에서 빌드가 열립니다. 빌드가 파일 탐색기에서 보이게 하세요.
Android Studio에서 빌드가 파일 탐색기에서 보이게 하세요.

Play Store Console에서 앱을 생성하는 방법

Google Play Console로 이동하세요. Google Play Console에서 올바른 개발자 계정을 선택하세요.
Google Play Console에서 올바른 개발자 계정을 선택하는 방법
Google Play Console에서 앱을 생성하세요. Create app
앱 이름과 언어를 선택하세요.
앱 카테고리와 앱이 유료인지 무료인지 선택하세요.
약관과 조건을 수락하세요.

약관과 조건을 읽고 이해한 후에 수락하세요.
클릭 Create

내부 테스트 그룹을 생성 중입니다.

앱을 만들었습니다. 내부 테스트 그룹을 만들 수 있습니다. Play Store에 앱을 실제로 모든 사람에게 공개하지 않기 때문에 내부 테스트 그룹을 만들 필요가 있습니다.

내부 테스트 그룹으로 이동하세요 internal testing 클릭하세요 Test and release -> Testing -> Internal testing
클릭하세요 Testers
Click on Create email list
이메일 목록의 이름을 지정하세요.
테스터의 이메일 주소를 추가하세요.
Enter를 누르세요. Enter and click on Save
Click on Create group
새 목록이 선택되어 있는지 확인하고 클릭하세요. Save

내부 테스트 그룹에 앱을 업로드합니다.

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

내부 테스트 그룹으로 이동하세요. Test and release -> Testing -> Internal testing
버튼을 클릭하세요. Releases Google Play Console 릴리스 버튼
Google Play Console 새로운 릴리스 생성 Create new release
Click on Upload
AAB 파일 선택

Android Studio로 수동으로 빌드한 AAB 파일을 선택하십시오. 이 파일이 Capgo 빌드에 사용할 키스토어와 동일하지 않다면 Capgo 네이티브 빌드는 실패할 것입니다.
AAB 파일 업로드를 기다리십시오
Click on Next
오류 수정

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

전화번호를 인증하지 않았기 때문에입니다. 인증을 마치고 튜토리얼을 계속 진행하겠습니다.
클릭하세요. Save and publish 이 앱을 내부 테스트 그룹에 게시합니다.
게시를 확인하세요.
앱이 게시되어 있는지 확인하세요.
임시 앱 이름을 받으세요.

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

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

로 이동하세요 Test and release -> Testing -> Internal testing
클릭하세요 Testers
클릭하세요 Copy link
휴대폰으로 링크를 보내고 브라우저에서 열어 Accept
Google Play Console 초대받기
앱을 설치하세요
1. Android Studio를 사용하기 전에 앱을 설치한 경우 Android Studio에서 uninstall 버튼
2. Google Play 콘솔에서 install 버튼
3. 앱이 성공적으로 다운로드되었는지 확인하세요
Play Store에서 앱을 찾을 수 없다면, Play Store에서 올바른 계정을 선택했는지 확인하세요.

Capgo Native Build (Android) 설정

Capgo Native Build을 설정하기 위해 준비되었습니다. 축하합니다! 🎉

필수 조건	플래그	설명	필수
Keystore 파일	`--keystore <path>`	__CAPGO_KEEP_0__에 대한 `.jks`/`.keystore` 파일을 사용하여 APK/AAB을 서명합니다.	예
Keystore alias	`--keystore-alias <alias>`	Keystore 내에 있는 키의 별칭입니다.	네
Keystore key password	`--keystore-key-password <password>`	키/스토어 비밀번호가 일치하면 하나만 입력할 수 있습니다.	아래의 주의사항을 참조하세요
Keystore store password	`--keystore-store-password <password>`	Keystore의 비밀번호입니다. 키/스토어 비밀번호가 일치하면 하나만 입력할 수 있습니다.	아래의 주의사항을 참조하세요
Google Play 서비스 계정	`--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, Keystore 암호, Keystore 키 암호, Keystore 별칭

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

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

구글 플레이 서비스 계정을 생성하는 것은 수동적이고 복잡한 과정입니다. 그럼에도 불구하고, 앱을 구글 플레이에 업로드하려면 필수적입니다. 다음 사항을 참고해 주세요:

당신 NEED 개발자 계정의 소유자아니라면 서비스 계정을 설정할 수 없습니다.
구글 클라우드 프로젝트를 새로 생성해야 합니다 (구글 플레이 계정과 별개)

시작해 보세요.

구글 클라우드 콘솔로 이동하세요. 프로젝트 선택자 클릭
프로젝트 선택자
프로젝트가 이미 있으면 선택하세요. 그렇지 않으면 새로운 프로젝트를 생성하세요:

아래의 스크린샷은 예시입니다. 실제 프로젝트 이름을 사용하세요.
1. Google Console에서 New project
2. 프로젝트 이름을 입력하고 Create
3. 올바른 프로젝트가 선택되었는지 확인하세요.
검색 바를 클릭하고 프로젝트를 검색하세요. service accounts 그것을 클릭하세요
Let’s 클릭하세요 Create service account
서비스 계정에 대한 양식을 완성하고 클릭하세요 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
새로 생성된 서비스 계정에 클릭하세요 서비스 계정 목록에서 새로 생성된 서비스 계정을 확인할 수 있습니다. 그것을 클릭하세요.

이 이메일 주소를 나중에 필요할 때 복사하세요.
Google Console의 Keys 탭
Click on Add Key 및 Create new key
Click on JSON 및 Create

클릭하면 Create 새로운 키가 생성되고 JSON 파일이 로컬 머신에 다운로드됩니다.
JSON 파일을 안전한 곳에 저장해야 합니다. 나중에 사용할 것입니다. WILL JSON 파일을 다운로드하세요. JSON 파일은 자동으로 다운로드되어야 합니다. 창을 닫으려면
Google Console 다운로드 키 close Play Store __CAPGO_KEEP_0__ 서비스 계정에 접근 권한을 부여하기

Play Store API 서비스 계정에 접근 권한을 부여하기 위해서는 Play Store Console로 이동해야 합니다.

개발자 계정으로 이동하세요. Google Play 콘솔
정확한 개발자 계정을 선택하세요.
클릭하세요. Users and permissions
클릭하세요. Invite new users
서비스 계정의 이메일 주소를 복사하세요.
개발자 계정으로 이동하세요. Account permissions 권한을 최소한으로 부여하세요:
- In App permissions, 앱에 접근 권한을 부여합니다.
- In Releases, 사용을 활성화합니다. Create, edit, and roll out releases.
- If your workflow uses Play App Signing, enable the related signing permission.
- If you are unsure, use Admin only during setup, then reduce permissions afterward.
Click on Invite user
Confirm the invitation
사용자가 초대되었습니다.

인증서를 저장합니다.

인증서를 저장하고 첫 번째 빌드를 실행할 준비가되었습니다. 인증서를 저장하려면 다음 명령어를 사용하세요:

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)

이미 완료하셨다면 Keystore, Keystore 비밀번호, Keystore 키 비밀번호, Keystore 별칭 그것 구글 플레이 서비스 계정, CI/CD를 위해 필요한 모든 것을 이미 가지고 있습니다. 이 섹션은 CI/CD에 필요한 값을 GitHub Actions 비밀과 환경 변수로 전달하는 방법에 대해만 설명합니다.

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

2) 저장소 비밀 만들기

In GitHub > Repository > Settings > Secrets and variables > Actions, 추가:

비밀 이름	값
`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`

3)GitHub Actions 워크플로우에서 환경 변수를 사용하세요.

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 }}

빌드 실행

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

Run:

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

이제 빌드 프로세스가 시작될 것입니다.

Play 리뷰에 제출

기본적으로 Android 릴리즈 빌드는 Google Play로 업로드되고 Play 콘솔에서 릴리즈를 완료할 때까지 비활성화됩니다. CI 릴리즈에서 Play 릴리즈를 자동으로 제출하려면 --submit-to-store-review with a release build:

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 서비스 계정 설정이 필요합니다 (PLAY_CONFIG_JSON CI 또는 로컬 Android 자격 증명을 저장합니다. --store-release-name Google Play 릴리스 이름으로 사용됩니다. --store-release-notes Play 변경 로그의 기본값이며, 각 --store-release-notes-locale "locale=notes" entry는 해당 지역의 로컬 Play 변경 로그를 작성합니다. Capgo은 Play 릴리스를 completed; Managed Publishing이 Play Console에서 활성화되어 있으면 Google은 승인 후 수동으로 릴리스를 기다릴 수 있습니다.

Android Builds에서 계속

Android Builds CI/CD와 연결하세요. __CAPGO_KEEP_0__ CI/CD Capgo CI/CD 제품 워크플로우에서 CI/CD에 대한 Capgo Capgo 네이티브 빌드 제품 워크플로우에서 Capgo 네이티브 빌드에 대한 Capgo 통합 제품 워크플로우에서 Capgo 통합에 대한 CI/CD 통합 CI/CD 통합에 대한 구현 세부 사항, 및 GitHub 액션 통합에 대한 구현 세부 사항 for the implementation detail in GitHub Actions Integration.