Android Builds

설치 단계와 이 플러그인의 전체 마크다운 가이드를 포함한 설정 프롬프트 복사

Google Play Store에 Android 앱을 빌드하고 제출하기 위해 Capgo의 전용 인프라를 사용합니다.

학습할 내용

Capgo Native Build를 통해 앱을 업로드하는 방법을 배웁니다.
Capgo Native Build를 위한 자격 증명을 구성하는 방법을 배웁니다.

기본 조건

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

Capgo의 온보딩은 자동으로 Android signing credentials (keystore + Google Play service account)를 생성하고 구성합니다. — 이는 권장 경로입니다.

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

Capgo의 내부 동작을 정확히 이해하거나, 자체적으로 인증 정보를 설정하고 싶은 경우에만 아래의 수동 가이드를 참조하세요.

첫 번째 수동 빌드

Capgo으로 앱을 빌드하기 전에, 먼저 Capgo을 설정하고, 수동으로 안드로이드 빌드를 해보세요. 수동 빌드를 하는 이유는 다음과 같습니다:

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

안드로이드 스튜디오를 사용한 앱 수동 빌드

Capgo으로 앱을 빌드하기 전에, 안드로이드 스튜디오를 사용한 앱 수동 빌드를 먼저 해보세요.

안드로이드 스튜디오를 열어보세요

실행 bunx cap open android __CAPGO_KEEP_0__을 열어 Android Studio 프로젝트를 열어보세요.
__CAPGO_KEEP_1__을 클릭하여 Build -> Generate Signed App Bundles / APKs
__CAPGO_KEEP_2__을 선택하고 __CAPGO_KEEP_1__을 클릭하여 Android App Bundle Android Studio에서 Android App Bundle을 선택하세요. Next

키스토어 생성 섹션

__CAPGO_KEEP_1__을 클릭하여

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

이 __CAPGO_KEEP_0__을 저장하세요 - 나중에 사용됩니다
__CAPGO_KEEP_0__ 비밀번호를 설정하세요

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

이 __CAPGO_KEEP_0__을 저장해 두세요 - 나중에 사용할 것입니다
양식의 나머지 부분을 채워주세요
1. Key Alias를 그대로 유지하세요 (key0)
2. 인증서 세부 사항을 채워주세요. 나중에 실제 세부 사항으로 채울 것입니다.
클릭하세요 OK

수동 빌드 완료

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

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

가장 Google Play 콘솔
개발자 계정을 선택하세요
클릭하세요 Create app
앱 이름과 언어를 선택하세요
앱 카테고리와 앱이 유료인지 무료인지 선택하세요
약관과 조건을 수락하세요

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

내부 테스트 그룹 만들기

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

폐쇄 테스트로 이동 internal testing 폐쇄 테스트 생성 이메일 목록으로 이동 Test and release -> Testing -> Internal testing
Go to Testers
Google Play Console 내부 테스트 Create email list
이메일 목록 이름을 지정하세요
테스터의 이메일 주소를 추가하세요
Enter를 누르세요 Enter Enter를 누르고 "Save"를 클릭하세요 Save
Google Play Console에서 그룹 만들기 Create group
내부 테스트 그룹에 앱 업로드 Save

앱을 내부 테스트 그룹에 업로드하세요

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

로 이동하세요. Test and release -> Testing -> Internal testing
버튼을 클릭하세요. Releases 내부 테스트 릴리스 버튼
새 릴리스 만들기 Create new release
업로드 Upload
__CAPGO_KEEP_0__

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

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

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

내부 테스트 그룹에 초대받은 것을 수락하세요

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

내부 테스트 그룹에 초대받은 것을 수락하기 위해 이동하세요 Test and release -> Testing -> Internal testing
Click on Testers
Click on Copy link
휴대폰으로 링크를 보내고 브라우저에서 열어 Accept
초대 수락 확인 후 'Play Store에서 다운로드' 버튼 클릭
앱 설치
1. 앱이 이미 Android Studio를 사용하여 설치되어 있다면 uninstall __CAPGO_KEEP_0__ 버튼 클릭
2. Google Play Console에서 앱을 설치하려면 install 버튼을 클릭하세요
3. 앱이 성공적으로 다운로드되었는지 확인하세요
__CAPGO_KEEP_0__ Native Build (Android) 설정

Capgo Native Build (Android) 설정

Now, you are ready to start the setup of Capgo Native Build. 축하합니다! 🎉!

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

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 서비스 계정Google Play 서비스 계정

Google Play로 앱을 업로드하려면 Keystore를 생성해야 합니다. Keystore를 생성하는 것은 수동으로 복잡한 과정이지만, Keystore를 생성해야 합니다. 다음 사항을 참고하십시오.

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

Google Play 서비스 계정 생성은 수동으로 복잡한 과정이지만, Google Play로 앱을 업로드하려면 필수입니다. 다음 사항을 참고하십시오. NEED 개발자 계정의 주인으로 개발자 계정의 주인으로 아니면 서비스 계정 설정을 할 수 없습니다.서비스 계정 설정을 하려면 Google Cloud 프로젝트를 새로 만들 필요가 있습니다 (Google Play 계정과 별도로).
시작해 보세요.

Google Cloud Console로 이동하세요.

프로젝트 선택자 클릭 Google Console 프로젝트 선택자
이미 프로젝트가 있으면 선택하거나, 없으면 새로 만들 수 있습니다.
]} (Note: The last item in the original array was

아래의 스크린샷은 예시입니다. 실제 프로젝트 이름을 사용하세요.
1. 클릭하여 New project
2. 프로젝트 이름을 입력하고 클릭하세요 Create
3. 정확한 프로젝트를 선택했는지 확인하세요
검색바를 클릭하여 service accounts 검색 결과를 클릭하세요
검색바를 클릭하여 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
서비스 계정이 생성된 것을 확인할 수 있습니다. 생성된 서비스 계정을 클릭하세요.

이 이메일 주소를 복사하세요. 나중에 필요하니까요.
클릭하세요. Keys __CAPGO_KEEP_0__
__CAPGO_KEEP_2__ Add Key __CAPGO_KEEP_3__ Create new key
__CAPGO_KEEP_5__ JSON __CAPGO_KEEP_6__ Create

__CAPGO_KEEP_10__ Create __CAPGO_KEEP_11__
JSON 파일을 안전한 곳에 저장해야 합니다. 그것은 나중에 사용됩니다. WILL 나중에 사용됩니다.
JSON 파일 다운로드 JSON 파일은 자동으로 다운로드되어야 합니다. 창을 닫기 위해 클릭할 수 있습니다. close 창을 닫기 위해 클릭하세요.

Play Store API 서비스 계정에 대한 접근 권한을 부여하는 것입니다.

새로 생성된 서비스 계정은 아직 Play Store API에 접근할 수 없습니다. 접근 권한을 부여하려면 Google Play Console로 이동하세요.

Google Play Console로 이동하세요. Play Store Console에서 올바른 개발자 계정을 선택하세요.
Google Play Console
__CAPGO_KEEP_0__을 클릭하세요. Users and permissions
__CAPGO_KEEP_0__을 클릭하세요. Invite new users
서비스 계정의 이메일 주소를 복사하세요.
__CAPGO_KEEP_0__으로 이동하세요. Account permissions 권한을 부여할 때는 최소 권한만 부여하세요.
- __CAPGO_KEEP_1__에서 앱에 대한 접근 권한을 부여하세요. App permissions__CAPGO_KEEP_1__에서 앱에 대한 접근 권한을 부여하세요.
- __CAPGO_KEEP_1__에서 앱에 대한 접근 권한을 부여하세요. Releases, 사용을 활성화하세요 Create, edit, and roll out releases.
- Play App Signing을 사용하는 워크플로우의 경우 관련된 서명 권한을 활성화하세요.
- 확신이 되지 않는다면 Admin 설정 중에만 사용하고 나중에 권한을 줄이세요.
Google Play 콘솔에서 클릭하세요 Invite user
초대 확인
Google Play 콘솔에서 초대받았는지 확인하세요

__CAPGO_KEEP_0__

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

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)

CI/CD 설정을 이미 완료했다면 Keystore, Keystore 비밀번호, Keystore 키 비밀번호, Keystore 별칭 그리고 Google Play 서비스 계정이미 CI/CD에 필요한 모든 것을 가지고 있다면. 이 섹션에서는 CI/CD에 필요한 값을 GitHub Actions 비밀번호와 환경 변수로 전달하는 방법만 설명합니다.

1) 인증 정보 파일을 단일 줄 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`	당신의 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:

Section titled “3) Use env vars in your __CAPGO_KEEP_0__ Actions workflow”

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

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

안드로이드 빌드에서 계속

이러한 경우 안드로이드 빌드를 사용하여 CI/CD 자동화 계획을 위해 연결하세요. Capgo CI/CD 제품 워크플로우에서 Capgo CI/CD Capgo 네이티브 빌드 제품 워크플로우에서 Capgo 네이티브 빌드 Capgo 연동 Capgo 워크플로우에 대한 연동 CI/CD 연동 CI/CD 연동 구현 세부 정보에 대한 GitHub 액션 연동 GitHub 액션 연동 구현 세부 정보에 대한