안드로이드 빌드

Capgo을 사용하여 Google Play Store로 Android 앱을 빌드하고 제출하세요.

What you will learn

• You will learn how to upload your app via Capgo Native build
• You will learn how to configure the credentials for Capgo Native Build

필수 조건

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

주의

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

권장: 자동 온보딩

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

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

Capgo의 온보딩을 사용하지 않고, 자체적으로 인증서를 설정하거나, Capgo가 어떻게 작동하는지 이해하고 싶다면, 아래의 수동 온보딩을 참조하세요.

첫 번째 수동 빌드

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

• Capgo를 사용하는 나중에 빌드에 사용할 인증서를 미리 준비할 수 있습니다.
• Play Store 콘솔에 기록을 만들 것입니다.

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

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

1. Android Studio를 열어주세요.

   실행 bunx cap open android Android Studio 프로젝트를 열어주세요.

2. 클릭 Build -> Generate Signed App Bundles / APKs

3. 선택 Android App Bundle Android Studio에서 Android 앱 번들을 선택해주세요. Next

Keystore를 생성하는 방법

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

1. 클릭 Create new

2. Key Store 경로를 입력하세요

   주의

   이것은 저장해야 할 것입니다 앱을 서명하는 데 사용됩니다. 이것은 나중에 사용됩니다.

3. Key Store 비밀번호를 설정하세요

   주의

   Key Store와 Key Alias의 비밀번호를 동일하게 사용하는 것을 추천합니다.

   주의

   이것은 저장되어야 합니다 - 나중에 사용할 것입니다 양식의 나머지 부분을 채우세요

4. Key Alias를 그대로 유지하세요 (key0)

   1. __CAPGO_KEEP_0__
   2. 인증서 정보를 입력하세요. 저는 가짜 정보로 입력했지만, 실제 정보로 입력해야 합니다.

   

5. 클릭하세요 OK

수동 빌드 완료

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

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

3. After the build succeeds, you should see the following screen

   1. __CAPGO_KEEP_1__
   2. __CAPGO_KEEP_2__ locate __CAPGO_KEEP_3__

4. __CAPGO_KEEP_4__

__CAPGO_KEEP_6__

1. __CAPGO_KEEP_8__ __CAPGO_KEEP_9__

2. __CAPGO_KEEP_10__

3. 클릭 Create app

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

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

6. 약관과 조건을 수락하세요

   주의

   약관과 조건을 읽고 수락하기 전에 주의하세요

7. 클릭 Create

내부 테스트 그룹 만들기

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

주의

내부 테스트는 실제 출시 전에 플레이 배포된 빌드를 빠르게 스모크 테스트하는 가장 빠른 방법입니다.

개발자 계정이 2023년 11월 13일 이후에 개인 계정으로 생성된 경우 내부 테스트 대신

1. 생산 액세스에 대한 폐쇄 테스트 요구 사항을 대체하지 않습니다. 최소 12명의 옵티드인 테스터가 14일 연속으로 폐쇄 테스트에 참여해야 합니다. internal testing 가장자리 이동하기로 가세요. Test and release -> Testing -> Internal testing

   

2. 클릭 Testers

3. 클릭 Create email list

4. 이메일 목록 이름

5. 테스터의 이메일 주소 추가

6. 클릭 Enter 엔터를 누르고 Save

7. 클릭하세요. Create group

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

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

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

1. 가장 Test and release -> Testing -> Internal testing

2. 클릭하세요. 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. 클릭 Testers

3. 클릭 Copy link

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

5. 초대장이 수락되었는지 확인하고 "Play Store에서 다운로드" 버튼을 클릭하세요.

6. 앱을 설치하세요.

   1. Android Studio를 사용하여 앱을 설치한 적이 있다면 "버튼"을 클릭하세요. uninstall "버튼"
   2. "버튼"을 클릭하세요. install Google Play 콘솔에서 앱을 설치하세요.
   3. 앱이 성공적으로 다운로드되었는지 확인하세요.

   주의

   앱이 플레이 스토어에 보이지 않으면 플레이 스토어에서 올바른 계정을 선택했는지 확인하세요.

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

Capgo 네이티브 빌드 설정을 시작할 준비가 되었습니다. 축하합니다! 🎉

필수 조건	플래그	설명	필수
Keystore 파일	--keystore <path>	Keystore 파일 경로 .jks/.keystore APK/AAB을 서명하는 데 사용되는 파일.	네
Keystore의 내부 키의 별칭.	--keystore-alias <alias>	네	키/스토어 패스워드가 일치하는 경우에만 제공할 수 있는 키의 패스워드.
아래의 주의사항을 참조하세요.	--keystore-key-password <password>	스토어의 패스워드. 키/스토어 패스워드가 일치하는 경우에만 제공할 수 있는 패스워드.	아래의 주의사항을 참조하세요.
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-key-password 또는 --keystore-store-password.

키스토어, 키스토어 비밀번호, 키스토어 키 비밀번호, 키스토어 별칭

만약에 수동 빌드 지침을 따랐다면 수동 빌드 지침keystore를 이미 생성해야 합니다. keystore를 생성하지 않았다면, 생성 방법을 따라서 keystore를 생성하세요.

Google Play 서비스 계정

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

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

Google Cloud 프로젝트를 새로 생성해야 합니다 (Google Play 계정과 별도로)

1. 시작해 보세요. 이동하세요. 구글 클라우드 콘솔

2. 프로젝트 선택자 클릭

3. 프로젝트가 이미 있는 경우 선택하거나 새로운 프로젝트를 생성하세요:

   주의

   아래의 스크린샷은 예시입니다. 실제 프로젝트 이름을 사용하세요.

   1. 클릭 New project
   2. 프로젝트 이름을 입력하고 클릭 Create
   3. 올바른 프로젝트인지 확인하세요

4. 검색 바를 클릭하고 service accounts 를 클릭하세요

5. 를 클릭하세요 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. Google Console에서 Keys 탭

9. 키 Add Key 탭 Create new key

10. Google Console에서 JSON 그리고 Create

    주의

    클릭하면 Create 새 키가 생성되고 JSON 파일이 로컬 머신으로 다운로드됩니다.

    JSON 파일을 안전한 곳에 저장해야 합니다. 그것은 WILL 나중에 사용됩니다.

11. JSON 파일 다운로드 JSON 파일은 자동으로 다운로드되어야 합니다. 창을 닫으려면 close Google Console에서 키 다운로드

Granting Play Store API access to the service account

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

1. Go to Google Play 콘솔
2. 정확한 개발자 계정을 선택하세요
3. Click on Users and permissions
4. Click on Invite new users
5. 서비스 계정의 이메일 주소를 복사하세요
6. Android 앱을 위한 Capgo 빌더 Account permissions Go to
   • 그리고 최소 권한이 필요한 권한을 부여하십시오: App permissionsIn
   • , 앱에 대한 접근 권한을 부여하십시오. ReleasesIn Create, edit, and roll out releases.
   • , 사용하십시오.
   • 플레이 앱 서명이 사용되는 워크플로우가 있는 경우 관련 서명 권한을 활성화하십시오. Admin 권한을 부여하는 방법에 대해 불확실한 경우
7. Google Play Console에서 권한을 부여하십시오 Invite user
8. 초대 확인
9. 사용자가 초대받았는지 확인하세요

인증서버 저장

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

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

팁

GitHub 비밀번호는 단일 줄 값이어야 합니다. tr -d '\n' 라인 브레이크를 제거하여 base64 출력을 단일 줄로 만듭니다.

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 Keystore, Keystore 비밀번호, Keystore 키 비밀번호, Keystore alias
KEYSTORE_KEY_PASSWORD	Keystore 키 비밀번호
KEYSTORE_STORE_PASSWORD	Keystore store password
PLAY_CONFIG_JSON	Content of play_config_base64.txt

Note

If key and store passwords are the same, you can provide just one of KEYSTORE_KEY_PASSWORD or KEYSTORE_STORE_PASSWORD.

3) Use env vars in your GitHub Actions workflow

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

Copy to clipboard to __CAPGO_KEEP_0__ Actions workflow를 복사하세요. Tip: __CAPGO_KEEP_0__ Actions workflow를 복사한 후에 붙여넣기를 사용하세요. Tip: __CAPGO_KEEP_0__ Actions workflow를 복사한 후에 붙여넣기를 사용하세요.

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

빌드를 실행합니다.

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

실행:

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

주의

안드로이드에서 --submit-to-store-review 기본값은 프로덕션 트래킹과 함께 release_status: completed 트래킹을 설정하지 않을 때 --android-track internal (또는 alpha / beta) — 또는 PLAY_STORE_TRACK CI에서 — 완료된 릴리스를 비프로덕션 트래킹에 유지하기 위해 --android-release-status / PLAY_STORE_RELEASE_STATUS Android 빌드에서 계속하기 completed.

이것은 일반 업로드 경로와 동일한 Google Play 서비스 계정 설정이 필요합니다 (CI 또는 로컬 Android 자격 증명 저장)PLAY_CONFIG_JSON Google Play --store-release-name Play 변경 로그의 기본값이며, 각 로케일의 Play 변경 로그를 지역화하는 데 사용됩니다. version_name. --store-release-notes __CAPGO_KEEP_0__은 Play 릴리스를 전송합니다. --store-release-notes-locale "locale=notes" entry writes a localized Play changelog for that locale. Capgo sends the Play release as completed Android 빌드에서 계속하기 --android-release-statusAndroid 빌드에서 계속하기

관리 게시가 활성화되어 있으면 Google은 승인 후에도 수동으로 게시를 기다릴 수 있습니다.

Android 빌드 Android 빌드 CI/CD 자동화 계획을 수립하기 위해 연결하세요. Capgo CI/CD Capgo CI/CD를 위한 제품 워크플로 Capgo 네이티브 빌드 Capgo 네이티브 빌드를 위한 제품 워크플로 Capgo 통합 Capgo 통합을 위한 제품 워크플로 CI/CD 통합 __CAPGO_KEEP_0__ 액션 통합 GitHub 액션 통합을 위한 구현 세부 정보 for the implementation detail in GitHub Actions Integration.