안드로이드 빌드

Capgo의 전용 인프라를 사용하여 Google Play Store에 Android 앱을 빌드하고 제출하세요.

학습할 내용

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

필수 조건

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

주의

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

첫 번째 수동 빌드

먼저 Capgo으로 앱을 빌드하기 전에, Capgo을 설정하고, 수동으로 Android 빌드를 먼저 해보세요.

• You will prepare the credentials for the later Capgo build
• 앞으로의 __CAPGO_KEEP_0__ 빌드에 필요한 자격 증명을 준비할 것입니다.

Play Store Console에 기록을 생성할 것입니다.

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 App Bundle 선택 Next

Android Studio를 사용하여 앱을 수동으로 빌드하는 방법

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

1. 클릭 Create new

2. 키 스토어 경로 입력

   이

   저장해야 합니다 - 나중에 사용됩니다 키 스토어 비밀번호 설정 Android Studio에서 키 스토어 비밀번호 설정

3. Android Studio에서 키 스토어 비밀번호를 설정하세요.

   주의

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

   주의

   이 __CAPGO_KEEP_0__ - 나중에 사용할 것입니다.

4. 양식의 나머지 부분을 채우세요.

   1. Key Alias를 그대로 유지하세요 (key0)
   2. 인증서 세부 사항을 채우세요. 가짜 세부 사항으로 채웠지만, 실제 세부 사항으로 채우세요.

   

5. 클릭하세요 OK

수동 빌드를 완료하세요

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

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

3. 빌드가 성공하면 다음 화면을 볼 수 있습니다

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

4. 파일 탐색기에 빌드가 보이게 하세요.

Play Store 콘솔에서 앱을 생성하세요.

1. Play Store 콘솔로 이동하세요. Google Play 콘솔

2. Google Play 콘솔에서 올바른 개발자 계정을 선택하세요.

3. Google Play 콘솔에서 앱을 생성하세요. Create app

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

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

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

   주의

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

7. 클릭 Create

내부 테스트 그룹을 생성 중입니다.

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

주의

내부 테스트는 실제 출시 전에 Play-distributed 빌드를 빠르게 smoke-test 할 수 있는 가장 빠른 방법입니다.

개발자 계정이 개인 계정으로 2023년 11월 13일 이후에 생성된 경우, 내부 테스트는 생략 생산 액세스에 대한 폐쇄 테스트 요구 사항을 대체하지 않습니다. 최소 12명의 옵티드 인 테스터가 14일 연속으로 참여한 폐쇄 테스트가 필요합니다.

1. Google Play Console로 이동하세요 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 Google Play Console 릴리스 버튼

3. Google Play Console 새로운 릴리스 생성 Create new release

4. 클릭 Upload

5. AAB 파일을 선택하세요

   주의

   Capgo 빌드에 사용할 키스토어와 동일한 키스토어로 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. 내부 테스트 그룹에 초대 받은 사람

6. 앱을 설치하세요

   1. __CAPGO_KEEP_0__이전으로 앱을 설치한 경우 안드로이드 스튜디오를 사용하여 앱을 설치한 경우 __CAPGO_KEEP_0__을 클릭하세요 uninstall __CAPGO_KEEP_0__버튼
   2. __CAPGO_KEEP_0__버튼 install 구글 플레이 콘솔 앱 설치
   3. 내부 테스트 트랙에서 플레이 스토어에서 앱을 다운로드 성공

   app을 설치하세요

   Play Store에서 앱을 찾을 수 없다면, Play Store에서 올바른 계정을 선택했는지 확인하세요.

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

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

필수 조건	플래그	설명	필수
APK/AAB을 서명하기 위한 키스토어 파일	--keystore <path>	키스토어 파일 경로 .jks/.keystore APK/AAB을 서명하기 위한 파일	예
__CAPGO_KEEP_0__	--keystore-alias <alias>	__CAPGO_KEEP_1__	예
__CAPGO_KEEP_2__	--keystore-key-password <password>	키/스토어 비밀번호가 일치하면 하나만 입력할 수 있습니다.	아래의 주의사항을 참조하세요.
__CAPGO_KEEP_3__	--keystore-store-password <password>	키/스토어 비밀번호가 일치하면 하나만 입력할 수 있습니다.	아래의 주의사항을 참조하세요.
__CAPGO_KEEP_0__	--play-config <path>	Play Store 업로드를 위한 JSON 서비스 계정 파일입니다.	예

bunx @capgo/cli 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 키 암호, Keystore 별칭

만약에 수동 빌드 지침을 따랐다면, Keystore가 이미 생성되어야 합니다. 만약 지침을 따르지 않았다면, 지침을 따르시어 Keystore를 생성하십시오. Google Play 서비스 계정Google Play 서비스 계정

Google Play 서비스 계정

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

• 당신 NEED 개발자 계정의 소유자아니라면 서비스 계정을 설정할 수 없습니다.
• 구글 클라우드 프로젝트를 새로 생성해야 합니다 (구글 플레이 계정과 별도로)

시작해 보세요.

1. 구글 클라우드 콘솔로 이동하세요. 프로젝트 선택기 클릭

2. Google Cloud Console

3. 이미 프로젝트가 있으면 선택하세요. 그렇지 않으면 새로운 프로젝트를 생성하세요:

   주의

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

   1. Google Console에서 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. 새로 생성된 서비스 계정 클릭하세요 서비스 계정 목록에서 새로 생성된 서비스 계정을 확인할 수 있습니다. 클릭하세요.

   주의

   __CAPGO_KEEP_0__ 이메일 주소를 복사해두세요. 나중에 필요합니다.

8. __CAPGO_KEEP_0__ Keys __CAPGO_KEEP_1__ 탭

9. __CAPGO_KEEP_3__ Add Key 및 Create new key

10. __CAPGO_KEEP_5__ JSON 및 Create

    주의

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

    __CAPGO_KEEP_0__ 키에 대한 JSON 파일을 안전한 곳에 저장해야 합니다. 나중에 사용됩니다. WILL JSON 파일을 다운로드하세요 JSON 파일은 자동으로 다운로드되어야 합니다. 창을 닫으려면

11. Google Console 다운로드 키 close __CAPGO_KEEP_0__ 키에 대한 Play Store 서비스 계정에 대한 접근 권한을 부여합니다.

API

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

1. Play Store Console로 이동하세요. Google Play Console
2. 개발자 계정을 선택하세요.
3. Google Play Console Users and permissions
4. Google Play Console에서 사용자 초대 Invite new users
5. Google Play Console에서 서비스 계정의 이메일 주소를 복사하세요.
6. Google Play Console Account permissions 그리고 최소한의 권한만 허용하십시오:
   • Google Play Console에서 App permissions, 앱에 대한 접근 권한을 부여하십시오.
   • Google Play Console에서 Releases, 활성화하십시오. Create, edit, and roll out releases.
   • Play App Signing을 사용하는 워크플로우가 있다면, 관련된 서명 권한을 활성화하십시오.
   • 분명하지 않다면 Admin 설치 중에만 사용하십시오. 그 후 권한을 줄이십시오.
7. Click on Invite user
8. 초대 확인
9. 사용자가 초대받았는지 확인하세요

인증서 저장

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

bunx @capgo/cli 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 비밀번호, Keystore 키 비밀번호, Keystore 별칭 그리고 Google Play 서비스 계정 Cloudflare, Capacitor, GitHub, Capgo, code, API, SDK, CLI, npm, bunCI/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

팁

GitHub 비밀번호는 단일 줄 값이어야 합니다. tr -d '\n' base64 출력에서 줄을 제거합니다.

2) 저장소 비밀번호 만들기

In 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) GitHub Actions 워크플로우에서 환경 변수를 사용하세요.

github/workflows/android-build.yml

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 ${{ 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 build com.example.app --platform android

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