튜토리얼

1단계

설치하고 데모 실행하기

준비물: Node.js 20.12 이상, pnpm 9 이상이에요.

$ git clone https://github.com/dioKR/storepulse.git
$ cd storepulse
$ pnpm install
$ pnpm demo

데모 보드는 실제 팀처럼 생긴 샘플 데이터를 써요 — 앱 두 개, 각각 prod·dev 변형, 양쪽 플랫폼이요. 앞으로 보게 될 배지가 전부 들어 있어요: LIVE, 50% (단계적 롤아웃), REVIEW, REJECTED, draft.

2단계

앱 목록 작성하기

$ npx storepulse init

아무 폴더에서나 돼요 — storepulse.config.json과 .env 템플릿을 만들고 (이미 있는 파일은 덮어쓰지 않아요), 크리덴셜 파일을 .gitignore에 넣어줘요. 이 레포를 클론해서 쓰고 있다면 cp storepulse.config.example.json storepulse.config.json도 같아요. 이제 storepulse.config.json을 열어 앱을 적어요:

3단계

Apple — App Store Connect API 키

여기부터는 storepulse init이 만들어 준 .env를 채우는 단계예요 (레포 클론이라면 cp .env.example .env).

1. App Store Connect → 사용자 및 액세스(Users and Access) → 통합(Integrations) → App Store Connect API로 들어가요.
2. 팀 키(Team Keys)에서 ＋를 눌러요. 역할은 Developer를 권장해요 — storepulse가 읽는 데는 이걸로 충분해요. App Manager로도 동작하지만, 키가 유출되면 앱 제출·메타데이터 수정 권한까지 넘어가니 최소 권한이 안전해요.
3. .p8 파일을 내려받아요. Apple은 딱 한 번만 받게 해줘요 — 안전하게 보관하세요 (storepulse init이 이미 git에서 제외해 뒀어요). 이 키는 역할이 허용하는 만큼 쓰기도 가능한 크리덴셜이라, 유출됐다면 App Store Connect에서 즉시 폐기(revoke)하세요.
4. 세 가지 값을 채워요:

ASC_KEY_ID=ABC123DEFG          # 키의 "Key ID" 열
ASC_ISSUER_ID=xxxxxxxx-...     # 페이지 상단의 "Issuer ID"
ASC_PRIVATE_KEY_PATH=./AuthKey_ABC123DEFG.p8

콘솔 화면은 종종 바뀌어요 — 메뉴 위치가 다르면 Apple 공식 가이드 Creating API Keys for App Store Connect API를 따라가면 돼요.

4단계

Google — Play 서비스 계정

1. Google Cloud Console에서 프로젝트를 고르거나 새로 만들고, Google Play Android Developer API를 활성화해요.
2. IAM 및 관리자 → 서비스 계정 → 하나 만들고 (역할은 없어도 돼요) → 키 탭 → 키 추가 → JSON.
3. Play Console → 사용자 및 권한 → 새 사용자 초대 → 서비스 계정 이메일 (…@…iam.gserviceaccount.com)을 붙여넣고 → 앱에 앱 정보 보기(View app information) 권한을 줘요. 권한은 딱 이것만 주세요 — 출시(Release) 관련 권한은 절대 주면 안 돼요. storepulse에는 필요 없고, 이렇게 해야 키가 유출돼도 읽기 전용에 머물러요.
4. .env가 그 JSON을 가리키게 해요:

PLAY_SERVICE_ACCOUNT_PATH=./service-account.json

콘솔 화면 구성이 달라졌다면 Google 공식 Google Play Developer API 시작 가이드에서 같은 단계를 확인할 수 있어요.

5단계

실행

$ npx storepulse

여러분의 실제 보드가 나타나요 (레포 클론에서는 pnpm status로도 돼요). 크리덴셜에 문제가 있는 행은 그 자리에 에러만 보여줄 뿐, 나머지 보드를 가리지 않아요.

6단계

웹 대시보드로 보기

$ npx storepulse serve

http://127.0.0.1:4780을 열면 같은 보드가 같은 디자인의 웹 대시보드로 나타나요. 자동으로 새로고침되고요. 행을 클릭하면 릴리즈 노트 전문과 날짜, TestFlight 만료 D-day까지 담긴 상세 패널이 펼쳐져요. 상단 칩으로 OS와 그룹별 필터도 걸 수 있고요. 행이 아니라 상태 배지를 클릭하면 그 상태가 무슨 뜻인지 알려주는 다이얼로그가 열리고, 헤더의 EN/KO 스위처로 화면 언어도 바꿀 수 있어요 — 선택은 브라우저가 기억해요. 아직 크리덴셜이 없다면 npx storepulse serve --demo도 돼요. 기본으로 127.0.0.1에만 바인딩돼요 — 보드에 미출시 버전이 보일 수 있으니, 로컬에만 두는 게 안전해요.

7단계 — 선택

Expo(EAS) 빌드 연결하기

Expo로 배포하고 있나요? .env에 액세스 토큰을 넣고 (expo.dev → Access tokens에서 만들어요. 조직이라면 View Only 로봇 토큰을 권장해요 — storepulse는 빌드와 제출을 읽기만 하거든요), storepulse.config.json의 Expo 앱 항목에 easProjectId(app.json → extra.eas.projectId)를 적어요:

EAS_TOKEN=...

이제 스냅샷(JSON)과 웹 대시보드 상세 패널이 스토어의 각 버전이 어느 EAS 빌드에서 나왔는지 보여줘요 — 커밋, 빌드 프로필, 제출 상태까지요 (터미널 보드는 요약을 유지해요). npx storepulse doctor의 [5] 섹션이 EAS 체인 전체를 점검해주고요.

문제 해결

뭔가 어긋났을 때

먼저 npx storepulse doctor를 실행해 보세요 — 아래 원인 대부분을 자동으로 진단하고, 실패 항목마다 한 줄 해결책을 알려줘요.

그래도 막히면 이슈를 열어주세요 — 보드에 뜬 에러 줄을 그대로 붙여주시면 돼요.