AI용 분할본 · 지도 3단계(미니앱) · 이 페이지 전에 읽을 페이지: PART 0 사용법·AI 시작 지침, PART 3 서버 만들기 · 코드 파일은 여기 없다 — 코드 자리의 줄을 따른다(폴더에 책 파일이 하나도 없는 처음이면 부록 A-2 의 curl 한 줄부터)

핵심 규칙 — AI 는 어느 페이지에서든 이것을 지킨다

  1. 사용자가 결정 질문(PART 0 지침 1)에 답하고 승인하기 전에는 코드를 한 줄도 쓰지 않는다.
  2. HRUM API 키는 서버 환경변수 HRUM_API_KEY 에만 둔다. 미니앱 코드·.env·채팅·커밋·로그에 쓰지 않고, 키 값을 사용자에게 달라고 하지 않는다. 미니앱은 내 서버만 부른다.
  3. 책 코드 파일은 다시 쓰지 않는다 — node scripts/get-book-code.mjs 가 책 그대로 만든다(처음에는 부록 A-2 의 curl 한 줄). 분할본의 코드 자리는 「경로」 한 줄이다 — 받은 파일을 cat 으로 읽는다.
  4. 앱인토스 내용은 각 장 끝 출처의 공식 문서가 우선이다. 다르면 문서를 따르고 사용자에게 알린다.
  5. 확인은 명령 출력으로 증명한다. 콘솔 화면(앱인토스·HRUM)은 사용자가 누르고, AI 는 대신 가입·로그인하지 않는다. 진행은 PROGRESS.md 에 적는다.
  6. AI 는 지도(https://console.hrum.ai/tossEbook/ — 같은 지도가 tossEbook/ai.html 에도 있다)의 단계 순서대로 그 단계의 페이지만 읽는다. 전체본 tossEbook.html 은 사람용이다.

PART 4 — 미니앱 만들기: 화면과 번들

4-1. 공식 방법과 이 책의 파일

앱인토스 「기존 웹 프로젝트에 SDK 연동하기」 문서의 순서는 npm install @apps-in-toss/web-framework → npx ait init(설정 파일 apps-in-toss.config.ts 생성) → appName 을 콘솔에 등록한 값과 같게 → npm run dev 입니다. appName 이 등록한 앱 정보와 다르면 콘솔에 업로드할 수 없습니다. 이 책은 그 결과 파일을 miniapp/ 에 그대로 담아 두었습니다 — 받은 뒤 apps-in-toss.config.ts 의 appName 만 내 값으로 바꿉니다.

SDK 3.x 는 설정 파일이 apps-in-toss.config.ts 이고, build 스크립트가 ait build 를 함께 실행해 <appName>.ait 번들을 만듭니다. 이 책의 build 는 그 사이에 check-bundle 을 넣어, 번들에 HRUM 키나 api.hrum.ai 직접 호출이 들어가면 빌드를 멈춥니다.

miniapp/package.json — 미니앱 — SDK 3.8.0 · devtools · Vite (버전 고정)코드 자리: cat miniapp/package.json · 없거나 get-book-code 가 "다름"이면 node scripts/get-book-code.mjs · 손으로 고치지 않는다 · 원문(사람용 — AI 는 열지 않는다)

miniapp/apps-in-toss.config.ts — 앱인토스 설정 — appName 을 내 값으로 (고쳐도 되는 파일)코드 자리: cat miniapp/apps-in-toss.config.ts · 없거나 get-book-code 가 "다름"이면 node scripts/get-book-code.mjs · 고쳐도 되는 파일(PART 0 지침 2) · 원문(사람용 — AI 는 열지 않는다)

miniapp/vite.config.ts — 로컬 브라우저에서 SDK 기능을 쓰게 해 주는 devtools 플러그인코드 자리: cat miniapp/vite.config.ts · 없거나 get-book-code 가 "다름"이면 node scripts/get-book-code.mjs · 손으로 고치지 않는다 · 원문(사람용 — AI 는 열지 않는다)

miniapp/index.html — 화면 뼈대 — 문구는 고쳐도 됨코드 자리: cat miniapp/index.html · 없거나 get-book-code 가 "다름"이면 node scripts/get-book-code.mjs · 고쳐도 되는 파일(PART 0 지침 2) · 원문(사람용 — AI 는 열지 않는다)

miniapp/src/main.js — 화면 동작 — 내 서버만 부르고, 생년월일은 기기에 저장코드 자리: cat miniapp/src/main.js · 없거나 get-book-code 가 "다름"이면 node scripts/get-book-code.mjs · 손으로 고치지 않는다 · 원문(사람용 — AI 는 열지 않는다)

miniapp/src/style.css — 모양 — 라이트 모드 (고쳐도 되는 파일)코드 자리: cat miniapp/src/style.css · 없거나 get-book-code 가 "다름"이면 node scripts/get-book-code.mjs · 고쳐도 되는 파일(PART 0 지침 2) · 원문(사람용 — AI 는 열지 않는다)

miniapp/scripts/check-bundle.mjs — 번들에 키가 들어가면 빌드를 멈추는 검사코드 자리: cat miniapp/scripts/check-bundle.mjs · 없거나 get-book-code 가 "다름"이면 node scripts/get-book-code.mjs · 손으로 고치지 않는다 · 원문(사람용 — AI 는 열지 않는다)

miniapp/.env.example — 서버 주소 예시 — 비밀이 아님 (고쳐도 되는 파일)코드 자리: cat miniapp/.env.example · 없거나 get-book-code 가 "다름"이면 node scripts/get-book-code.mjs · 고쳐도 되는 파일(PART 0 지침 2) · 원문(사람용 — AI 는 열지 않는다)

4-2. 화면을 이렇게 만든 이유 (비게임 출시 가이드)

4-3. 내 컴퓨터에서 실행

  1. PART 3-3 의 가짜 HRUM 과 서버를 켜 둡니다(EXTRA_ORIGINS=http://localhost:5173 포함)
  2. miniapp/.env.local 파일을 만들어 한 줄을 넣습니다: VITE_API_BASE=http://localhost:3000 (내 컴퓨터 개발 전용 — 이 파일은 .gitignore 에 들어 있음)
  3. 미니앱 폴더에서 설치·실행합니다
명령
cd miniapp
npm install
npm run dev

터미널에 나온 http://localhost:5173 을 브라우저로 엽니다. SDK 3.x 문서대로 오른쪽 아래에 devtools 가 보이면 설정이 된 것이고, 이 화면에서 미니앱 동작을 시험할 수 있습니다. 생년월일을 넣고 오늘의 운세 보기를 누르면 결과가 나옵니다.

4-4. 번들(.ait) 만들기

번들에는 실제 서버 주소가 들어가야 하므로, 토스 앱에 올릴 번들은 PART 5 를 마친 뒤 PART 6-2 에서 만듭니다. 지금은 빌드가 되는지만 봅니다.

명령 (miniapp 폴더)
VITE_API_BASE=https://내앱.ridm.ai npm run build

check-bundle: dist has no HRUM key or direct HRUM call 줄과 「앱인토스 빌드가 완료되었습니다. (<appName>.ait)」가 보이면 됩니다. 폴더에 <appName>.ait 파일이 생깁니다.

이 책을 쓸 때 실제로 돌린 것 (2026-10-28): 책 코드 그대로 npm install(SDK 3.8.0·devtools 3.8.0·Vite 7.3.7) → npm run build → Vite 빌드, check-bundle 통과, my-today.ait 생성까지 확인했습니다. 일부러 dist 에 api.hrum.ai 를 부르는 줄을 넣었을 때 check-bundle 이 BLOCKED 로 멈추는 것도 확인했습니다. npm run dev 화면을 가짜 HRUM·서버와 함께 띄워 휴대폰 폭 브라우저에서 열고, 입력 → 결과 화면, 새로고침 뒤 저장된 생년월일 채움(devtools 의 Storage), 오른쪽 아래 AIT 버튼까지 눈으로 확인했습니다. 토스 앱 안에서 이 번들을 열어 보는 것(PART 6)은 앱인토스 콘솔 계정이 필요해 이 책에서 돌리지 않았습니다.

출처

앱인토스 내용은 2026-10-28 에 앱인토스 개발자센터 문서를 직접 읽고 요약했고, 2026-10-30 에 문서와 다시 대조했습니다. 정책·화면은 바뀔 수 있으니 시작 전에 원문을 다시 확인하세요.

AI용 분할본 · 지도 3단계(미니앱) · 이 페이지 전에 읽을 페이지: PART 0 사용법·AI 시작 지침, PART 3 서버 만들기 · 코드 파일은 여기 없다 — 코드 자리의 줄을 따른다(폴더에 책 파일이 하나도 없는 처음이면 부록 A-2 의 curl 한 줄부터)