Play 스토어에 게시하기, 단계별 안내

JumPHP 게임을 Google Play에 올리고 유지하는 전체 안내예요. 무엇을 만들고, 무엇을 보관하고, 휴대폰에서 무엇을 확인하고, Play Console을 처음부터 끝까지 어떻게 다루는지 설명해요. 두 종류의 앱 모두에 해당해요.

나의 Claude는 이 가이드를 알고 있어요(프로젝트의 AGENTS.md와 docs/google-play.md에 있어요). "내 게임을 Google Play에 올려 줘"라고 부탁하세요. 기술적인 일은 Claude가 하고, 선택과 제출은 내 몫이에요(마지막 부분 참고).

0. 시작하기 전에

• Google Play 개발자 계정: play.google.com/console, 한 번만 25달러이고 신원 확인이 있어요. 내 계정이니 Google의 약관에는 내가 동의해요.
• 새 개인 계정은 프로덕션에 게시하기 전에 테스터 12명 이상이 14일 동안 참여하는 비공개 테스트를 거쳐야 해요. 일찍 시작하세요.
• 패키지 이름(io.github.<내 github 계정>.<mon_jeu>): Google Play에서의 앱 식별자예요. 이후에는 절대 바뀌지 않아요. 명령이 처음에 물어봐요.
• Android SDK 라이선스: 내가 처음에 터미널에서 동의해요(SDK는 약 1 GB이고 ~/.jumphp에 저장돼요). Claude는 내가 직접 명령을 실행하라고 안내해요(! bin/jumphp twa …).
• 공개 주소의 개인정보처리방침: 게임이 아무것도 수집하지 않더라도 Google이 요구해요. 짧은 페이지면 충분해요. 게임은 개인 데이터를 수집, 전송, 공유하지 않는다, 계정, 광고, 추적이 없다, 설정과 저장 파일은 기기에 남는다, 연락처 이메일 주소를 적어요. 게임의 사이트 games/mon-jeu/site/privacy.html에 두면 https://play.jumphp.net/mon-jeu/privacy.html에서 제공돼요(또는 공개 저장소의 PRIVACY.md). Google에 주소를 알려 주기 전에 주소를 한 번 열어 보세요. 404 오류가 나면 심사가 막혀요.

1. 키: 먼저 백업하세요

처음 빌드하면 업로드 키가 만들어져요. ~/.jumphp/android/keys/<패키지>.keystore와 비밀번호가 담긴 <패키지>.env예요.

• git에는 절대 넣지 마세요. 메모나 메시지에도 적지 마세요. 두 파일을 다른 곳(비밀번호 관리자, 암호화된 디스크)에 백업하세요. 없으면 다시 빌드할 때 다른 키가 만들어져서 Google Play가 업데이트를 거부해요.
• Google Play 앱 서명(기본값)을 쓰면 Google이 휴대폰에서 앱에 서명하는 자체 키를 보관해요. 내 키는 업로드가 내게서 왔음을 증명할 뿐이에요. 분실하면 Google이 교체해 줄 수 있지만(설정 > 앱 서명) 며칠이 걸려요.
• 따라서 SHA-256 지문이 두 개 있어요. 내 키의 지문(명령이 표시해요)과 Google 키의 지문(첫 업로드 후 Play Console > 설정 > 앱 서명)이에요.

2. 앱 만들기

bin/jumphp twa mon-jeu --url https://jumphp.net/mon-jeu     # 웹 앱
bin/jumphp android mon-jeu                                   # 또는 네이티브 앱

• 빌드할 때마다 버전 번호가 1 올라가요(Google Play는 이미 업로드한 번호를 거부해요. 실패한 시도도 번호를 소모하지만 문제없어요).
• 버전 파일을 바로 커밋하세요. games/mon-jeu/android/twa-manifest.json(웹 앱) 또는 games/mon-jeu/android/app.json(네이티브 앱)이에요. dist/는 절대 커밋하지 마세요.
• 아이콘 아래의 이름: game.yaml의 pwa: {short_name: …}(12자까지 전부 보여요). 아이콘: assets/icon.png.

3. 웹 앱만: 사이트가 앱을 보증해요

사이트가 앱을 선언해야만 Android가 페이지를 전체 화면으로 열어요. 패키지 이름과 두 지문(내 것과 Google의 것)이 필요해요. 내 지문만 있으면 .apk로 설치한 앱은 동작하지만, Google Play에서 설치한 앱은 주소 표시줄과 함께 열려요(또는 "다음으로 열기" 선택창이 나타나요).

스튜디오의 게임 페이지에서 Android 앱 부분에 입력하세요(또는 Claude가 update_project로 해요). 사이트가 이를 https://jumphp.net/.well-known/assetlinks.json에 게시해요. 내 서버에서는 https://내-도메인/.well-known/assetlinks.json이에요.

4. 실제 휴대폰에서 시험하기

USB 디버깅을 켜고 adb로 실행해요.

adb install -r games/mon-jeu/dist/android/mon-jeu-<version>.apk
adb shell pm get-app-links <패키지>          # 웹 앱: "jumphp.net: verified"
adb exec-out screencap -p > capture.png      # 확인하세요: 게임이 보여야 해요

• 앱이 게임의 타이틀 화면으로 열려야 해요.
• 내 키로 서명한 .apk는 Google Play에서 설치한 같은 앱 위에 설치되지 않아요(INSTALL_FAILED_UPDATE_INCOMPATIBLE). 먼저 삭제하세요(앱의 저장 파일이 사라져요).
• 웹 앱이 열렸다가 바로 닫히고 "다음으로 열기" 선택창이 나타나요: 휴대폰에 Chrome이 두 개 있는 경우예요. 보통 클론 공간 / 보조 공간 / 듀얼 앱(Xiaomi, Samsung…) 때문이에요. JumPHP 앱은 주 프로필의 Chrome을 요청해서 플레이어에게는 문제가 해결돼요. 내 테스트용 휴대폰에서 클론 공간을 지우면 그 안의 모든 앱이 삭제돼요.
• 게임이 Chrome에서 열린다고 해서 앱이 동작한다는 증거는 아니에요. 앱을 직접 시험하세요.

5. Play Console, 처음 할 때

대시보드의 "앱 설정하기" 목록(X/11)에 남은 일이 표시돼요. "검토를 위해 제출"은 빠진 것이 있으면 회색으로 비활성화돼요.

1. 앱 만들기: 이름, 기본 언어, 게임, 무료, 선언 항목.
2. 앱 콘텐츠(정책 > 앱 콘텐츠)의 각 선언:
   • 개인정보처리방침: 0단계의 공개 주소.
   • 광고: 광고 없음(JumPHP는 광고를 추가하지 않아요).
   • 앱 액세스: 별도 접근 권한 없이 모두 이용 가능(계정 없음).
   • 타겟층: 게임이 만들어진 연령대예요. 13세 미만 연령대를 선택하면 앱이 가족 프로그램에 들어가요(더 엄격한 규칙, 낮은 노출). 정말 어린이를 위한 게임일 때만 선택하세요.
   • 콘텐츠 등급(IARC 설문): 카테고리는 게임이에요. 내 게임에 맞게 솔직하게 답하세요(만화나 판타지 폭력, 유혈, 공포, 도박, 플레이어가 만든 콘텐츠, 플레이어 간 소통, 위치, 구매).
   • 데이터 보안: 계정과 통계가 없는 JumPHP 게임은 어떤 데이터도 수집하거나 공유하지 않아요(저장 파일은 기기에 남아요. 게임이 웹 서비스를 호출한다면 선언하세요).
   • 광고 ID: 사용하지 않음.
   • 정부 앱, 금융 기능, 건강: 해당 없음.
3. Play 스토어 설정(성장 > 스토어 입점 정보 > 설정): 카테고리(아케이드, 액션, 퍼즐…)와 연락처 이메일 주소. 둘 다 필수예요. 없으면 "Your app cannot be published yet"가 나와요. 이메일 주소는 공개돼요.
4. 기본 스토어 등록정보: 제목(30자), 짧은 설명(80자), 전체 설명(4000자), 512 × 512 PNG 아이콘(bin/jumphp build가 만들어요: dist/web/icon-512.png), 1024 × 500 이미지, 휴대폰 스크린샷 2장 이상(bin/jumphp shot mon-jeu를 정수 배로 확대하거나 휴대폰에서 촬영). 이후 버전에서 다시 만들 수 있도록 이미지는 게임 안(games/mon-jeu/store/)에 보관하세요.
5. 테스트: 테스트 및 출시 > 테스트 > 내부 테스트(새 계정은 테스터 12명이 필요한 비공개 테스트) > 릴리스 만들기 > .aab > 출시 노트 > 저장 > 검토 > 출시 시작. 테스터는 이메일 주소 목록이에요. 각자 그 Google 계정으로 로그인한 상태에서 초대 링크를 열고 테스터 되기를 눌러요.
6. 웹 앱: 이 첫 업로드 후 Google 키의 지문을 추가하고(3단계), 테스트 링크로 설치해 전체 화면을 확인하세요.
7. 프로덕션: 프로덕션 > 국가/지역 > 추가, 선택, 저장(국가가 없는 릴리스는 거부돼요). 그다음 릴리스 만들기 > .aab > 노트 > 다음 > 저장.
8. 게시 개요 > 검토를 위해 제출을 누르고 확인하세요. 심사에는 몇 시간에서 7일이 걸려요. 콘솔과 계정 이메일로 앱이 온라인에 올라갔는지 알려 줘요.

6. 출시 노트

언어별로 한 블록씩, 태그는 각자 한 줄에 써요.

<fr-FR>
Première version.
</fr-FR>
<en-US>
First release.
</en-US>

7. 이후 버전

• 웹 앱: 게임은 사이트와 함께 업데이트돼요(푸시하면 게시돼요). 새 앱은 불필요해요. 이름, 아이콘, 색, 시작 주소, 패키지가 바뀔 때만 새 앱이 필요해요. bin/jumphp twa mon-jeu.
• 네이티브 앱: 게임이 바뀔 때마다 새 앱이에요. bin/jumphp android mon-jeu --version-name 1.1.

그다음에는 버전 파일을 커밋하고, .apk를 휴대폰에서 시험한 뒤, Play Console > 같은 트랙 > 릴리스 만들기 > 새 .aab > 노트 > 검토를 위해 제출을 해요. 선언 항목은 그대로 유효해요. 다만 게임이 선언한 내용(온라인 게임, 구매, 데이터)을 바꾸는 경우에는 먼저 업데이트하세요.

8. 겪었던 함정들

나의 Claude가 나 없이는 하지 않는 일

• Android SDK 라이선스나 Google의 약관에 동의하기, 또는 답변을 알려 주지 않고 등급 설문에 답하기
• 타겟층 선택(게임이 "어린이용"이라고 하면 규칙과 노출이 바뀌어요)
• 그 제출에 대한 내 동의 없이 프로덕션에 제출하기
• 내 휴대폰의 클론 공간을 지우거나 앱을 삭제하기(데이터가 사라져요)
• 키, 비밀번호, dist/를 git에 넣기