안드로이드 빌드

복사하기

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

학습할 내용

Capgo Native Build를 통해 앱을 업로드하는 방법을 배웁니다.
Capgo Native Build를 위한 인증 정보를 설정하는 방법을 배웁니다.

준비물

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

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

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

Capgo의 온보딩을 사용하지 않고 자체적으로 인증서를 설정하거나 인증서가 어떻게 작동하는지 이해하고 싶은 경우에만 이 아래의 수동 온보딩을 진행하세요.

첫 번째 수동 빌드

Capgo를 사용하기 전에 먼저 Capgo를 설정하고, 수동으로 Android 빌드를 진행해야 합니다. 수동 빌드를 진행하는 이유는 다음과 같습니다:

You will prepare the credentials for the later Capgo build
Play Store 콘솔에 기록을 만들 것입니다.

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

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

Android Studio를 열어주세요.

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

Keystore를 생성하는 방법

현재, Keystore 파일이 없습니다. 이 파일은 앱을 서명하는 데 사용되며, Google이 이 앱을 개발한 사람임을 알리기 위해 사용됩니다. Keystore를 생성하기 위해, Android Studio에서 제공하는 GUI 방법을 사용하겠습니다. 명령줄에서 이 작업을 수행하는 방법도 있습니다. 그러나 이 튜토리얼에서 다루지 않습니다.

클릭 Create new
Key Store 경로 입력

보관해야 합니다 - 나중에 사용됩니다 __CAPGO_KEEP_0__
__CAPGO_KEEP_0__

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

이 __CAPGO_KEEP_0__ 이것은 나중에 사용될 것입니다.
폼의 나머지 부분을 채우세요.
1. 키 별칭을 그대로 유지하세요 (key0)
2. 인증서 정보를 입력하세요. 저는 가짜 정보로 입력했지만, 실제 정보로 입력해야 합니다.
클릭하세요 OK

수동 빌드 완료

키 스토어의 모든 세부 정보가 정확하게 입력되었는지 확인하고 클릭하세요 Next
릴리스 빌드 버전을 선택하고 클릭하세요 release Android Studio에서 릴리스 빌드 버전을 선택하세요 Create
After the build succeeds, you should see the following screen
1. __CAPGO_KEEP_1__
2. __CAPGO_KEEP_2__ locate __CAPGO_KEEP_3__
__CAPGO_KEEP_4__

__CAPGO_KEEP_6__

__CAPGO_KEEP_8__ __CAPGO_KEEP_9__
__CAPGO_KEEP_10__
클릭 Create app
앱 이름과 언어를 선택하세요
앱 카테고리와 앱이 유료인지 무료인지 선택하세요
약관과 조건을 수락하세요

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

내부 테스트 그룹 만들기

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

가장 internal testing 클릭 Test and release -> Testing -> Internal testing
클릭 Testers
클릭 Create email list
이메일 목록 이름
테스터의 이메일 주소 추가
클릭 Enter 엔터를 누르고 Save
클릭하세요. Create group
새 목록이 선택되어 있는지 확인하고 클릭하세요. Save

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

내부 테스트 그룹을 만들었습니다. 이제 내부 테스트 그룹에 앱을 업로드할 수 있습니다.

가장 Test and release -> Testing -> Internal testing
클릭하세요. Releases 버튼
클릭 Create new release
클릭 Upload
AAB 파일을 선택하세요

Android Studio에서 수동으로 빌드한 AAB 파일을 선택하십시오. 만약 이 파일이 Capgo 빌드에 사용할_keystore와 동일하지 않다면, Capgo 네이티브 빌드는 실패할 것입니다.
AAB 파일이 업로드될 때까지 기다리세요
클릭 Next
오류를 수정하세요

개인적으로, 이 단계에서 나는 이 오류를 보입니다

이는 아직 휴대폰 번호를 확인하지 않았기 때문입니다. 휴대폰 번호를 확인하고 튜토리얼을 계속 진행하겠습니다.
클릭하세요 Save and publish 이것은 내부 테스트 그룹에 앱을 게시합니다.
게시를 확인하세요
앱이 게시되어 있는지 확인하세요
임시 앱 이름을 가져오세요

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

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

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

Capgo 안드로이드 네이티브 빌드 설정

Capgo 안드로이드 네이티브 빌드 설정을 시작하기 위해 준비되었습니다. 축하합니다! 🎉

필수 조건	플래그	설명	필수
Keystore 파일	`--keystore <path>`	Keystore 파일 경로 `.jks`/`.keystore` APK/AAB을 서명하는 데 사용되는 파일.	예
Keystore의 내부 키의 별칭.	`--keystore-alias <alias>`	예	키의 비밀번호. 키/스토어 비밀번호가 일치하면 하나만 제공할 수 있습니다.
아래의 주의사항을 참조하세요.	`--keystore-key-password <password>`	Keystore의 비밀번호. 키/스토어 비밀번호가 일치하면 하나만 제공할 수 있습니다.	아래의 주의사항을 참조하세요.
Google Play 서비스 계정.	`--keystore-store-password <password>`	__CAPGO_KEEP_0__	__CAPGO_KEEP_0__
__CAPGO_KEEP_0__	`--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를 생성하는 방법을 따라야 합니다.

Google Play 서비스 계정

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

당신 context 필요 당신소유자
의

Developer Account

입니다. 그렇지 않으면 서비스 계정을 설정할 수 없습니다. 구글 클라우드 콘솔
프로젝트 선택자 클릭
프로젝트가 이미 있는 경우 선택하거나 새로운 프로젝트를 생성하세요:

아래의 스크린샷은 예시입니다. 실제 프로젝트 이름을 사용하세요.
1. 클릭 New project
2. 프로젝트 이름을 입력하고 클릭 Create
3. 올바른 프로젝트인지 확인하세요
검색 바를 클릭하고 service accounts 를 클릭하세요
를 클릭하세요 Create service account
서비스 계정 양식을 입력하고 Done
1. 를 클릭하세요 Capgo Native Build Service Account
2. 서비스 계정 이름을 capgo-native-build-service-acc
3. 서비스 계정 ID를 Allows Capgo Native Build to build and submit the app to the Play Store
Google Console에서 서비스 계정 양식을 입력하세요. 생성된 서비스 계정을 클릭하세요. 생성된 서비스 계정이 목록에 나타나면 클릭하세요.

이 이메일 주소를 복사하여 나중에 필요할 때 사용하세요.
Google Console에서 Keys 탭
키 Add Key 키 Create new key
키 JSON 그리고 Create

클릭하면 Create 새 키가 생성되고 JSON 파일이 로컬 머신에 다운로드됩니다.
JSON 파일을 안전한 곳에 저장해야 합니다. 그것은 WILL 나중에 사용됩니다.
JSON 파일 다운로드 JSON 파일은 자동으로 다운로드되어야 합니다. 창을 닫으려면 close Google Console에서 키 다운로드

Granting Play Store API access to the service account

새로 생성된 서비스 계정은 아직 Play Store API에 접근할 수 없습니다. 접근을 허용하려면 Google Play 콘솔로 이동하세요.

가장 Google Play 콘솔
정확한 개발자 계정을 선택하세요
클릭하여 Users and permissions
클릭하여 Invite new users
서비스 계정의 이메일 주소를 복사하세요
Android 앱 빌더 Account permissions Go to
- 그리고 최소 권한이 필요한 권한을 부여하십시오: App permissionsIn
- , 앱에 대한 접근 권한을 부여하십시오. ReleasesIn Create, edit, and roll out releases.
- , 사용자에게 앱을 활성화하십시오.
- If your workflow uses Play App Signing, enable the related signing permission. Admin If you are unsure, use
Google Play Console에서 권한 부여 Invite user
초대 확인
사용자가 초대받았는지 확인하세요

인증서 저장 중입니다

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

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

2) 저장소 비밀을 생성하세요

그리고 GitHub > Repository > Settings > Secrets and variables > Actions, 추가:

비밀 이름	값
`CAPGO_TOKEN`	Your Capgo API 토큰
`APP_ID`	Your Capgo 앱 ID (예시: `com.example.app`)
`ANDROID_KEYSTORE_FILE`	내용 `keystore_base64.txt`
`KEYSTORE_KEY_ALIAS`	Keystore alias from Keystore, Keystore 비밀번호, Keystore 키 비밀번호, Keystore alias
`KEYSTORE_KEY_PASSWORD`	Keystore 키 비밀번호
`KEYSTORE_STORE_PASSWORD`	Keystore store password
`PLAY_CONFIG_JSON`	Content of `play_config_base64.txt`

3) Use env vars in your GitHub Actions workflow

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

빌드를 실행합니다.

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

실행:

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

이것이 빌드 프로세스를 시작합니다.

Play 릴리스를 검토하기 위해 제출합니다.

기본적으로 Android 릴리스 빌드는 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 \
  --android-track production \
  --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 version_name. --store-release-notes Google Play --store-release-notes-locale "locale=notes" entry writes a localized Play changelog for that locale. Capgo sends the Play release as completed 로컬 Play 변경 로그를 작성합니다. __CAPGO_KEEP_0__은 Play 릴리스를 전송합니다. --android-release-status관리 게시를 Play 콘솔에서 활성화한 경우, Google은 승인 후에도 수동으로 게시를 기다릴 수 있습니다.

Android 빌드에서 계속

관리 게시를 사용하는 경우 Android 빌드 CI/CD를 자동화하기 위해 연결하세요. Capgo CI/CD 제품 워크플로우에서 Capgo CI/CD를 사용하세요. Capgo 네이티브 빌드 제품 워크플로우에서 Capgo 네이티브 빌드를 사용하세요. Capgo 통합 제품 워크플로우에서 Capgo 통합을 사용하세요. CI/CD 통합 제품 워크플로우에서 CI/CD 통합을 사용하세요. GitHub 액션 통합 제품 워크플로우에서 GitHub 액션 통합을 사용하세요.