안드로이드 빌드

Google Play Store에 앱을 제출하기 위해 Capgo의 전용 인프라를 사용하여 안드로이드 앱을 빌드하고 제출하세요.

학습할 내용

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

필수 조건

• 활성 Google Developer 계정이 필요합니다.
• 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 클릭 Next

애플리케이션 키스토어를 생성하는 방법

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

1. 클릭하세요 Create new

2. 키 스토어 경로를 입력하세요

   주의

   이 이것은 저장해야 할 것입니다 - 나중에 사용됩니다

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

   주의

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

   이것은 저장해야 할 것입니다.

   - 나중에 사용할 것입니다. 폼을 완성하세요 Key Alias를 그대로 유지하세요 (key0)

4. __CAPGO_KEEP_0__

   1. __CAPGO_KEEP_1__
   2. 인증서 정보를 입력하세요. 저는 가짜 정보로 입력했지만, 실제 정보로 입력하세요.

   

5. 클릭하세요 OK

수동 빌드 완료

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

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

3. 수동 빌드 완료 섹션

   1. 이 팝업은 빌드가 성공했다는 것을 나타냅니다.
   2. 버튼을 클릭하세요 - 이 버튼을 클릭하면 파일 탐색기를 열고 빌드를 확인할 수 있습니다. locate 파일 탐색기에 빌드가 보이도록 확인하세요

4. 안드로이드 스튜디오에서 파일 탐색기에 빌드가 보이도록 확인하세요

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

1. 개발자 계정을 선택하세요 Google Play 콘솔에서 개발자 계정을 선택하세요

2. Android Studio에서 빌드가 성공했는지 확인하세요

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 파일을 선택하세요

   주의

   AAB 파일을 Android Studio에서 수동으로 빌드했는지 확인하세요. 만약 이 파일이 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 __CAPGO_KEEP_0__
   2. Google Play 콘솔에서 앱을 제거하세요. install "버튼을 클릭하세요.
   3. 앱을 열고 다운로드가 성공적으로 완료되었는지 확인하세요.

   주의

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

Configuring Capgo Native Build (Android)

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

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

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

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

Google Play 서비스 계정

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

• 당신 context HTML text fragment from a longer Capgo UI string (parent key `you_definition`). Page/area: Capgo marketing website. Role: Long marketing or legal paragraph. Seen in: page disclaimer.astro, page return.astro. Message key `you_definition` (You Definition). 필요합니다앞서
• 개발자 계정의

context

1. HTML text fragment from a longer Capgo UI string (parent key `you_definition`). Page/area: Capgo marketing website. Role: Long marketing or legal paragraph. Seen in: page disclaimer.astro, page return.astro. Message key `you_definition` (You Definition). 구글 클라우드 콘솔

2. 프로젝트 선택자 클릭

3. 프로젝트가 이미 있으면 선택하십시오. 없으면 새로운 프로젝트를 생성하십시오:

   주의

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

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

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

5. 를 클릭하세요 Create service account

6. 서비스 계정의 양식을 입력하고 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

   

7. Google Console에서 서비스 계정의 양식을 입력하세요 생성된 서비스 계정을 클릭하세요 생성된 서비스 계정이 목록에 나타나야 합니다. 클릭하세요.

   주의

   이 이메일 주소를 복사하여 나중에 필요할 때 사용하세요.

8. 구글 콘솔에서 Keys 탭

9. 키 Add Key 구글 콘솔에서 키 추가하고 새로운 키 생성 Create new key

10. 키 JSON 키 Create

    주의

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

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

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

Granting Play Store API access to the service account

서비스 계정이 아직 Play Store API에 접근할 수 없습니다. Play Store 콘솔로 이동하여 접근 권한을 부여하세요.

1. 가장 먼저 하세요 Google Play 콘솔
2. 개발자 계정을 선택하세요
3. 클릭하세요 Users and permissions
4. 클릭하세요 Invite new users
5. 서비스 계정 이메일 주소를 복사하세요
6. Android 앱을 위한 Capgo 빌더 Account permissions Go to
   • Android 앱을 위한 Capgo 빌더 App permissionsAndroid 앱을 위한 Capgo 빌더
   • In ReleasesAndroid 앱을 위한 Capgo 빌더 Create, edit, and roll out releases.
   • In
   • Android 앱을 위한 Capgo 빌더 Admin If your workflow uses Play App Signing, enable the related signing permission.
7. only during setup, then reduce permissions afterward. 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 저장소 비밀번호
PLAY_CONFIG_JSON	내용 play_config_base64.txt

주의

키와 저장소 비밀번호가 같다면, 하나만 제공할 수 있습니다. KEYSTORE_KEY_PASSWORD 또는 KEYSTORE_STORE_PASSWORD.

3) Use env vars in your GitHub Actions workflow

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

팁

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

빌드를 실행합니다.

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

실행:

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"

주의

안드로이드에서 --submit-to-store-review 기본값으로 프로덕션 트랙과 함께 release_status: completed 트랙을 설정하지 않을 때 --android-track internal (또는 alpha / beta) — 또는 PLAY_STORE_TRACK CI에서 — 완료된 릴리스를 비프로덕션 트랙에 유지하기 위해 --android-release-status / PLAY_STORE_RELEASE_STATUS 이 경우 다른 상태가 필요할 때 completed.

이것은 일반 업로드 경로와 동일한 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" 로컬화된 Play 변경 로그를 작성합니다. Capgo은 Play 릴리스를 전송합니다. completed 관리 게시가 Play 콘솔에서 활성화되어 있으면, Google은 승인 후 수동으로 게시를 기다릴 수 있습니다. --android-release-statusAndroid 빌드에서 계속

Android 빌드에서 계속하기

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