내가 너무 바빠서 다 답은 못하고
구글 등록후 각자의 cli ai에게 먹여서 토스에 등록하는 지침서만 남김.

혹시 cli가 뭔지 모르면 각자의 ai에게 물어보면 됨.
웹방식은 안되는가? 에 대한 답을 ai가 줌.

웹 방식도 됩니다. 다만 할 수 있는 범위가 다릅니다.

웹 AI(ChatGPT, Claude 웹 등): 이 문서를 붙여 넣으면 단계별 안내자 역할은 그대로 합니다. 지금 무엇을 누르고 어떤 값을 넣을지, 반려되면 왜인지 알려 줍니다. 하지만 콘솔 클릭, 빌드 명령, .ait 검사는 직접 못 하니 사람이 손으로 하게 됩니다.
브라우저를 직접 조작하는 웹 AI(ChatGPT 에이전트 모드, 브라우저 확장형 AI 등): 콘솔 화면 작업까지 맡길 수 있습니다. 대신 파일을 빌드하고 검사하는 5단계는 PC 의 터미널이 필요해서, 그 부분은 사람이 하거나 CLI 와 나눠서 해야 합니다.
CLI AI: 빌드와 검사를 직접 하고, 브라우저 연결(CDP 등)까지 해 두면 콘솔 작업도 합니다. 가장 많이 맡길 수 있습니다.

정리: 문서는 어느 쪽에서나 통하고, 누가 손을 움직이느냐만 달라집니다. 웹 AI 로 쓰실 거면 런북 맨 위에 「너는 실행하지 말고 사람에게 한 단계씩 안내만 해라」 한 줄을 붙여 주시면 됩니다.

여기서부터 지침서임. 구글에 등록된 게임을 앱인토스에 올릴때 당연히 토스 가이드를 읽으라고 하면 되긴 할텐데 내가 여러개 등록하면서 시켰던거 한번에 정리하라고 했으니 이거를 cli ai에 같이 먹여보시오.

앱정보 등록해서 승인 되기까지 2-3일 걸림.
그 후에 프로모션 달고 출시해야 혜택탭에 노출이 되는데 이 프로모션을 테스트하고 출시하는 과정이 조금 헷갈림. 프로모션을 등록하고 테스트 코드를 단 게임을 먼저 업로드해서 테스트판을 개발자가 테스트해서 프로모션이 정상 작동하면 본버전을 다시 빌드해서 올려서 출시해야함. 대충 그 과정을 넣으라고 했음.

몇번 해보면 감이 올것임.

-------아래 복사----

런북: 구글 플레이 등급(IARC)으로 앱인토스에 「게임」 등록하기

이 문서는 CLI AI 에이전트(Claude Code, Codex 등)에게 그대로 주는 실행 지시서다.
에이전트는 위에서부터 단계별로 진행하고, 각 단계의 확인을 통과해야 다음으로 넘어간다.
🧑 사람 표시는 에이전트가 직접 못 하는 일이다 — 사용자에게 정확히 무엇을 해 달라고 요청하고 멈춘다.
⛔ 멈춤 표시는 되돌릴 수 없는 작업이다 — 값을 보여 주고 사용자의 명시적 승인을 받은 뒤에만 실행한다.

0. 에이전트 규칙 (항상 지킬 것)

되돌릴 수 없는 작업 전에는 반드시 멈추고 승인받는다. (앱 생성, 앱 유형 선택, appName, 무료/유료, 검토 요청, 출시, 프로모션 등록)
검토 요청·출시는 사용자가 「올려/검토해/출시해」라고 말했을 때만. 업로드·테스트 푸시까지는 해도 된다.
「했다」가 아니라 「확인했다」로 보고한다. 클릭·명령이 성공했다고 끝내지 말고, 화면 값이나 API 응답으로 결과를 다시 읽어 확인한 뒤 보고한다.
콘솔 화면 문구·단추 이름은 앱·시기마다 다를 수 있다(예: 「버전 등록」 vs 「버전 등록하기」). 못 찾으면 화면 텍스트를 덤프해서 실제 이름을 확인한다. 추측으로 아무 단추나 누르지 않는다.
실패 메시지가 조용한 화면이 많다 — 클릭 직후 토스트([role=alert], [role=status])를 읽는다.
비밀번호·인증번호·서명은 에이전트가 만들거나 추측하지 않는다 → 🧑 사람.
게임 화면·스크린샷은 그 게임의 실제 화면만 쓴다. 다른 게임 것을 재사용하지 않는다.

브라우저 조작이 필요한 경우

구글 플레이 콘솔·앱인토스 콘솔은 웹 화면이다. 에이전트가 브라우저를 조작할 수 있으면(로그인된 크롬에 CDP/Playwright 로 연결) 직접 하고, 아니면 사용자에게 단계별로 안내한다.

로그인·2단계 인증은 🧑 사람.
콘솔이 내부 API(fetch, credentials:'include')를 쓰는 경우 화면 클릭보다 API 읽기가 확인용으로 안정적이다.

1. 사전 점검

확인	방법	통과 기준
웹 게임이 폰에서 돈다	헤드리스로 390×844, 375×667 캡처	잘림·겹침·확대 없음
앱인토스 사업자 계정	`🧑 사람` 에게 확인	콘솔 로그인 가능
대표자 서명(인감) 이미지	`🧑 사람` 에게 PNG 요청	파일 경로 확보
구글 플레이 개발자 계정	`🧑 사람` 에게 확인	콘솔 로그인 가능

2. 구글 플레이: IARC 인증 ID 받기

플레이 콘솔에 앱이 없으면 만든다. ⛔ 멈춤 — 패키지명(번들 업로드 후 변경 불가), 무료/유료(무료로 만들면 유료로 못 바꿈) 를 사용자에게 확인.
번들(AAB)을 아무 트랙에나 하나 올린다.
앱 콘텐츠 → 콘텐츠 등급 → 새 설문지 시작

카테고리: 이메일 + 「게임」 + IARC 약관 동의 → 다음
섹션을 위에서부터 하나씩 답한다(답해야 다음 섹션이 열린다). 「예」를 고르면 하위 체크박스·빈도 질문이 그 자리에 끼어든다.
디지털 재화 문항: 일반 인앱결제만 있으면 하위 체크박스 중 「디지털 상품 구매 가능」 하나만. 「실제 통화용 디지털 상품 거래/판매」는 체크하지 않는다(한국 게등위 등급 거부).
설문이 모두 「완료됨」인데 「다음」이 회색이면 → 「저장」을 먼저 누른다.
요약 → 제출

결과 화면의 「IARC 인증 ID」(UUID), 등급, 등급 받은 날짜를 기록한다.
확인


# 한국 플레이에서 실제로 보이는지 (토스 심사자가 한국에서 연다)

curl -s -o /dev/null -w "%{http_code}\n" "https://t.co/R5XgSBlO46<패키지명>&gl=kr"

200 → 다음 단계로.
404 이고 다른 나라는 200 → 콘텐츠 등급 화면을 본다. 「한국에 앱을 게시하기 전 추가 검토가 필요합니다」면 게등위 심사 대기. 🧑 사람: 등록 이메일의 게등위 통지 확인·응답. 설문을 다시 내지 않는다(재산정되며 대기가 리셋될 수 있음). 200 이 될 때까지 하루 한 번 위 curl 로 확인하고 기다린다.

3. 앱인토스: 게임 앱 만들기

⛔ 멈춤 — 아래 값을 표로 보여 주고 승인받은 뒤 만든다. 미니앱은 삭제가 안 된다.

항목	규칙

| 한국어 앱 이름 | 10자 이내, 한글 필수, 특수문자는 `:` `·` `?` 만(쉼표 불가). 나중에 수정 가능 |
| appName | 영문 슬러그, 수정 불가. 빌드 설정 파일의 appName 과 반드시 동일 |
| 유형 | 게임(나중에 못 바꿈. 비게임으로 만들면 카테고리에 「게임」이 없다) |
| 설명 | AI 「정책 확인」 통과해야 「만들기」가 켜짐 |
확인: 앱 목록에 생겼는지, 유형이 게임인지 다시 읽는다.

4. 앱인토스: 앱 정보 + 게임 등급분류 정보

| 항목 | 값 / 규칙 |

|---|---|

누른 직후 토스트를 읽는다. 아무 일도 없으면 빠진 항목(특히 카테고리·내용정보)이 있다.
결과는 수정 화면 맨 위 「반려사유」 박스 또는 앱 상태 API 로 확인.

확인: 앱 정보 상태가 승인으로 바뀌었는지 다시 읽는다. (승인 전엔 인앱 광고·결제 메뉴가 잠겨 있다)

5. 빌드

# SDK 를 그때의 최신으로
npm view @apps-in-toss/web-framework version
npm i @apps-in-toss/web-framework@latest # 캐시 권한 오류면: --cache <임시폴더>
ls node_modules/.bin/esbuild  # npm i 가 다른 도구를 지웠는지 확인(쓰는 경우)

ait build 는 웹 빌드를 다시 돌리지 않고 dist 를 그대로 재포장한다. 그러므로:

# 웹 빌드(또는 복사 스크립트) → 관문 → 포장 을 한 줄로 묶어, 앞이 실패하면 포장하지 않는다
npm run build:web && node gate.mjs && npx ait build

gate.mjs 에 최소한 넣을 검사:

dist 가 원본보다 최신인가(원본 파일 수정 시각 < dist 수정 시각)
게임 진입 파일·필수 스크립트가 dist 에 있는가
출시용 빌드에 테스트 광고 ID·테스트 코드가 없는가
빌드 설정의 appName 이 3단계 값과 같은가
포장 후 확인

unzip -Z1 <앱>.ait | head  # sources/ 구조 확인
for f in $(unzip -Z1 <앱>.ait | grep -E '\.(js|html)$'); do
unzip -p <앱>.ait "$f" | grep -l "ait-ad-test" >/dev/null && echo "테스트 광고 ID 남음: $f"
done

수정했는데 폰에 옛 화면이 뜨는 걸 막으려면 JS·CSS 주소에 빌드마다 바뀌는 ?v= 를 붙인다(영상 주소는 건드리지 않는다 — 사파리 자동재생 자격이 사라짐).
화면 구석에 작은 빌드 라벨(버전)을 박아 두면 「옛 판을 보고 있다」 혼선을 막는다.

6. 업로드 → 테스트

콘솔 「앱 출시」 → 「버전 등록(하기)」 → .ait 선택 → 메모 → 등록하기.

4097 = 같은 번들이 이미 올라감(앞 업로드 성공). 4031 = API 키 범위 문제(「전체 앱」 키 필요).

번들 목록 API/화면에서 새 버전이 「빌드 중」→ 생성됨으로 바뀔 때까지 확인.
그 버전 행의 「테스트」 → 멤버에게 테스트 푸시.
🧑 사람: 폰에서 가장 최근 푸시를 열어 달라고 요청(테스트 링크는 그 번들에 고정).
확인: 번들의 테스트 여부가 「테스트됨」으로 바뀌었는지 다시 읽는다. 안 바뀌면 검토 요청 단추가 꺼져 있다.

7. 검토 요청 → 출시

⛔ 멈춤 — 사용자가 「검토/출시」를 명시했을 때만.

버전 행 「검토 요청」 → 출시 노트 입력 → 요청.
승인 감시: 번들 상태를 몇 분 간격으로 읽는다. 반려면 사유를 그대로 보고하고 멈춘다.
승인되면 「출시하기」(사용자가 출시까지 허락한 경우).
확인: 번들이 출시됨(deployed)으로 바뀌었는지 다시 읽는다.

8. (선택) 광고

광고 그룹은 앱 정보 승인 뒤 생성 가능(번들 승인 기다릴 필요 없음).
생성 폼 맨 아래 「위 내용을 확인했어요」 체크 → 등록하기. 같은 이름이 있으면 조용히 실패하고 이름만 선점된다 → 다른 이름으로.
코드에는 상세 URL 의 https://t.co/rIJWG2zu2n.… 값을 넣는다. 개발 중엔 테스트 ID, 출시 번들엔 라이브 ID 만. 「라이브가 비면 테스트 ID」 같은 대체 코드도 남기지 않는다(번들 검토 반려 사유).
배너는 게임을 덮지 말고 제 칸을 따로 둔다. 소재마다 높이가 달라지니 ResizeObserver 로 따라간다.
일부 안드로이드는 전면·배너를 동시에 로드하면 전면 이벤트가 안 온다 → 순차 로드.

9. (선택) 프로모션(토스포인트 미션)

⛔ 멈춤 — 금액·조건·이름을 표로 보여 주고 승인받는다.

등록만으론 지급 안 된다. 조건 달성 시 앱이 Promotion.grantReward 를 직접 호출해야 한다.
미션 이름: 12자 이내, 「~기」로 끝. 피할 것: 「깨기」「클리어」(결과 기반 반려), 「광고」(시청 유도 반려), 큰 숫자 「N판 플레이하기」(반복 횟수로 반려된 사례). 숫자 없는 진도 문구가 안전(예: 「4막 이야기 열기」).
조건은 횟수가 아니라 진도(깬 단계의 최고값). 횟수로 세면 반복 파밍으로 적자.
금액은 광고 수익 안쪽. 광고를 끝까지 본 뒤에만 지급하는 게이트 권장. 한 사람 평생 1회 기록.
승인된 프로모션은 금액 수정 불가 → 새로 등록 후 코드 교체.
시작하려면 코드가 「테스트됨」이어야 한다 → TEST_ 접두 코드로 검수 빌드 → 🧑 사람 폰에서 지급 확인 → 시작 → 라이브 코드로 다시 빌드. 검수 빌드와 라이브 빌드는 저장 키를 분리(검수 예약이 라이브로 재시도돼 실지급된 사고).
반려된 코드는 라이브 빌드에서 빼고, 실패한 지급은 뒤로 미뤄 다른 지급을 막지 않게.

10. 토스 웹뷰 체크리스트 (빌드 전 확인)

바깥 스크롤 잠김 대응: 스크롤이 필요한 곳은 안쪽 컨테이너 overflow-y:auto
backdrop-filter 미사용
확대·선택 차단: viewport user-scalable=no + touch-action + user-select:none + 제스처 차단 (끌기 있으면 touch-action:none)
상단: 토스 웹뷰 손잡이(뒤로·더보기) 아래로 여유, 안전영역 4방향
부팅 직후 무거운 일괄 처리 없음(첫 탭 멈춤 방지)
이미지 webp
소리는 첫 손짓 뒤에만(아이폰 무음 스위치 대응 포함)

11. 트러블슈팅 결정표

| 증상 | 원인 | 조치 |

|---|---|---|

| 고쳤는데 옛 화면 | dist 재포장 / 옛 푸시 / 캐시 | 관문 통과 후 재빌드, 최신 푸시, ?v= 갱신, 빌드 라벨로 확인 |

| 번들 반려 「테스트용 광고 그룹 ID」 | ait-ad-test 잔존 | 라이브 ID 로, 대체 코드 제거, grep 0 건 |

12. 보고 형식 (에이전트 → 사용자)

각 단계가 끝날 때 한 줄씩:

[단계] 결과 — 확인 방법(무엇을 다시 읽어 확인했는지) — 다음에 사용자가 할 일(있으면)

예: [6. 테스트] 버전 YYYYMMDD-N 테스트 푸시 보냄 — 번들 목록에서 생성됨 확인 — 폰에서 최신 푸시를 열어 주세요

내가 너무 바빠서 다 답은 못하고

요약

핵심 포인트