Android Builds

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

Capgo

__CAPGO_KEEP_0__

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

필수 조건

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

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

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

아래의 수동 walkthrough는 Capgo의 동작을 이해하고자 하거나, 자체적으로 인증서를 설정하는 사람들을 위해 제공됩니다.

수동으로 첫 번째 빌드

Capgo을 사용하여 앱을 빌드하기 전에, 먼저 Capgo을 설정하고, 수동으로 Android 빌드를 수행해야 합니다.

You will prepare the credentials for the later Capgo build
앞으로의 __CAPGO_KEEP_0__ 빌드에 인증서를 준비합니다.

Play Store 콘솔에 기록을 생성합니다.

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

앱을 수동으로 Android Studio로 빌드하는 방법

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

클릭 Create new
키 스토어 경로 입력

이 저장되어야 함 - 나중에 사용됩니다
키 스토어 비밀번호 설정

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

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

수동 빌드 완료

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

플레이 스토어 콘솔에서 앱을 생성하는 방법

가장 먼저 구글 플레이 콘솔
개발자 계정 선택
클릭하면 Create app
__CAPGO_KEEP_0__ 이름과 언어를 선택하세요.
__CAPGO_KEEP_0__ 카테고리와 앱이 유료인지 무료인지 선택하세요.
__CAPGO_KEEP_0__ 이용 약관을 수락하세요.

이용 약관을 읽고 이해한 후에 수락하세요.
__CAPGO_KEEP_0__에 클릭하여 생성하세요. Create

__CAPGO_KEEP_0__은 Cloudflare, Capacitor, GitHub, Capgo, code, API, SDK, CLI, npm, bun과 같은 보호된 토큰을 지원합니다.

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

Go to internal testing Click on Test and release -> Testing -> Internal testing
Click on Testers
클릭 Create email list
이메일 목록 이름
테스터의 이메일 주소 추가
입력 Enter 및 저장 Save
Google Play Console 그룹 만들기 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 이것은 내부 테스트 그룹에 앱을 게시합니다.
게시를 확인하세요
앱이 게시되었는지 확인하세요
임시 앱 이름을 받으세요

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

내부 테스트 그룹에 초대받기 위해 준비가 되었습니다.

Go to Test and release -> Testing -> Internal testing
Click on Testers
Click on Copy link
Send the link to your phone, open it in the browser and click on Accept
Confirm the invitation has been accepted and click on “Play Store에서 다운로드”
앱을 설치하세요
1. Android Studio를 사용하기 전에 앱을 설치한 경우 Google Play Console에서 uninstall 버튼
2. 버튼 install Google Play Console에서 앱을 설치하세요
3. Play Store 내부 테스트 트랙에서 앱을 성공적으로 다운로드했습니다
If you do not see the app in Play Store, make sure you have selected the correct account in Play Store.

Capgo Native Build (Android) 설정

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

필수 조건	플래그	설명	필수
Keystore 파일	`--keystore <path>`	Keystore 파일 경로 `.jks`/`.keystore` APK/AAB에 서명하는 데 사용되는 파일	예
__CAPGO_KEEP_0__	`--keystore-alias <alias>`	__CAPGO_KEEP_1__	__CAPGO_KEEP_2__
__CAPGO_KEEP_0__	`--keystore-key-password <password>`	__CAPGO_KEEP_3__	__CAPGO_KEEP_4__
__CAPGO_KEEP_0__	`--keystore-store-password <password>`	__CAPGO_KEEP_5__	__CAPGO_KEEP_6__
__CAPGO_KEEP_0__	`--play-config <path>`	__CAPGO_KEEP_7__	__CAPGO_KEEP_8__

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

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

당신 필수 서비스 계정을 설정하려면 개발자 계정의소유자
여야 합니다. 그렇지 않으면 서비스 계정을 설정할 수 없습니다.

서비스 계정의 소유자가 아니면 개발자 계정만 생성할 수 있습니다.

서비스 계정의 소유자가 아니면 개발자 계정만 생성할 수 있습니다. 새로운 구글 클라우드 프로젝트를 생성해야 합니다. (구글 플레이 계정과 별도로).
시작해 보세요. 구글 클라우드 콘솔로 이동하세요. 프로젝트 선택자 클릭하세요.
프로젝트가 이미 있으면 선택하세요. 그렇지 않으면 새로운 프로젝트를 생성하세요:

아래의 스크린샷은 예시입니다. 실제 프로젝트 이름을 사용하세요.
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 and Create new key
Click on JSON and Create

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

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

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

Go to Google Play Console
Select 올바른 개발자 계정을 선택하세요.
Click on Users and permissions
Click on Invite new users
서비스 계정의 이메일 주소를 복사하세요.
Go to Account permissions 권한을 최소한으로 부여하세요:
- In App permissions, 앱에 접근 권한을 부여합니다.
- In Releases, Play App Signing을 사용하는 워크플로우가 있다면 관련된 서명 권한을 활성화하세요. Create, edit, and roll out releases.
- If your workflow uses Play App Signing, enable the related signing permission.
- If 사용하는 워크플로우가 Play App Signing을 사용한다면 관련된 서명 권한을 활성화하세요. Admin If 사용하는 워크플로우가 Play App Signing을 사용한다면 관련된 서명 권한을 활성화하세요.
Google Play Console에 앱에 대한 권한을 부여하세요. Invite user
Google Play Console에서 사용자를 초대하세요.
__CAPGO_KEEP_0__ 초대자가 사용자에게 초대되었는지 확인하세요.

__CAPGO_KEEP_0__ 인증서 저장

__CAPGO_KEEP_0__ 인증서를 저장하고 첫 번째 빌드를 실행할 준비가 되었습니다. __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

GitHub CI/CD 설정 (GitHub Actions)

__CAPGO_KEEP_0__ 이미 완료했습니다. Keystore, Keystore 비밀번호, Keystore 키 비밀번호, Keystore 별칭 __CAPGO_KEEP_0__ 구글 플레이 서비스 계정, 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, add:

Secret name	Value
`CAPGO_TOKEN`	Capgo API 인증 토큰
`APP_ID`	Capgo 앱 ID (예시: `com.example.app`)
`ANDROID_KEYSTORE_FILE`	내용 `keystore_base64.txt`
`KEYSTORE_KEY_ALIAS`	Keystore alias Keystore, Keystore 비밀번호, Keystore 키 비밀번호, Keystore alias
`KEYSTORE_KEY_PASSWORD`	Keystore 키 비밀번호
`KEYSTORE_STORE_PASSWORD`	Keystore 저장소 비밀번호
`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 }}

빌드 실행

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

__CAPGO_KEEP_2__:

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

__CAPGO_KEEP_5__ 빌드 프로세스를 시작합니다 🍾🥂

__CAPGO_KEEP_6__ Play 릴리스 제출

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

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; Play 콘솔에서 관리되는 게시가 활성화되어 있으면, Google는 승인 후에도 수동으로 게시를 기다릴 수 있습니다.

Android 빌드에서 계속하기

Android 빌드를 사용하여 CI/CD 자동화 계획을 만든 경우 __CAPGO_KEEP_0__ CI/CD와 연결하세요. Android 빌드 Capgo CI/CD 제품 워크플로우에서 Capgo CI/CD에 대한 Capgo 네이티브 빌드 제품 워크플로우에서 Capgo 네이티브 빌드에 대한 Capgo 통합 제품 워크플로우에서 Capgo 통합에 대한 CI/CD 통합 CI/CD 통합에 대한 구현 세부 사항, 그리고 GitHub 액션 통합 구현 세부 사항에 대한 GitHub 액션 통합.