SubXDocs

Store Setup

A step-by-step guide to obtaining the required keys from Apple App Store and Google Play Store and connecting them to SubX.

먼저 확인하세요: Check first: Your project and app (iOS or Android) must already be registered in the SubX dashboard. If you haven't done this yet, follow the Getting Started guide first. Getting Started

Apple App Store Integration

To manage subscription payments for iOS apps, you need to configure 3 things in App Store Connect.

1

Generate In-App Purchase API Key

어디서? App Store Connect→사용자 및 액세스→통합→인앱 구입

이 키는 SubX가 Apple 서버와 통신해서 영수증을 검증하고 구독 상태를 확인할 때 사용합니다.

  1. App Store Connect에 로그인합니다.
  2. 왼쪽 메뉴에서 사용자 및 액세스를 클릭합니다.
  3. 상단 탭에서 통합 → 인앱 구입을 선택합니다.
  4. "인앱 구입 키 생성" 버튼을 클릭하고, 키 이름을 입력합니다 (예: "SubX").
  5. 생성된 키에서 다음 3가지를 복사하세요:
항목어디에 있나요?
Issuer ID페이지 상단에 표시됩니다
Key ID생성한 키 옆에 표시됩니다
.p8 파일"다운로드" 버튼으로 받습니다 (1회만 다운로드 가능!)

SubX에 입력하기: SubX 대시보드 → 앱 → iOS 앱 선택 → 스토어 인증 탭에서 Issuer ID, Key ID를 입력하고 .p8 파일을 업로드합니다.

2

Set Up Server Notifications (S2S) URL

어디서? App Store Connect→앱→앱 정보→App Store 서버 알림

사용자가 구독을 갱신하거나 취소하면, Apple이 이 URL로 알림을 보냅니다. SubX가 이 알림을 받아서 구독 상태를 자동으로 업데이트합니다.

  1. App Store Connect에서 해당 앱을 선택합니다.
  2. 왼쪽 메뉴 일반 → 앱 정보를 클릭합니다.
  3. 아래로 스크롤하면 "App Store 서버 알림" 섹션이 있습니다.
  4. 프로덕션 서버 URL에 다음을 입력합니다:
https://api.subx.dev/v1/store/apple/{알림토큰}

알림 토큰은 어디서 확인하나요? SubX 대시보드 → 앱 → iOS 앱 선택 →스토어 인증 탭 하단의 "알림 URL"에 전체 URL이 표시되어 있습니다. 그대로 복사해서 App Store Connect에 붙여넣으면 됩니다.

Sandbox URL도 같은 형식으로 입력하세요 (테스트용).

3

Copy Shared Secret

어디서? App Store Connect→앱→인앱 구입→관리→앱 공유 비밀

이 키는 Apple의 영수증을 검증할 때 사용됩니다.

  1. App Store Connect에서 해당 앱 → 인앱 구입 → 관리를 클릭합니다.
  2. 오른쪽 상단의 "앱 공유 비밀" 링크를 클릭합니다.
  3. 표시되는 32자리 문자열을 복사합니다 (없으면 "생성" 버튼 클릭).

SubX에 입력하기: SubX 대시보드 → 앱 → iOS 앱 선택 → 스토어 인증 탭에서"Shared Secret" 필드에 붙여넣습니다.

.p8 파일은 1번만 다운로드 가능합니다! The .p8 file can only be downloaded once! Keep it in a safe place after downloading. If lost, you'll need to revoke the existing key and generate a new one.

Google Play Store Integration

To manage subscription payments for Android apps, you need to configure 2 things in Google Play Console.

1

Create Service Account (Google Cloud)

어디서? Google Play Console→설정→API 액세스

서비스 계정은 SubX가 Google Play 서버와 통신하기 위한 "로봇 계정"입니다. 이 계정을 통해 결제 검증과 구독 상태 조회를 합니다.

  1. Google Play Console에 로그인합니다.
  2. 왼쪽 메뉴 설정 → API 액세스를 클릭합니다.
  3. Google Cloud 프로젝트가 연결되어 있지 않다면, 안내에 따라 연결합니다.
  4. "새 서비스 계정 만들기"를 클릭하면 Google Cloud Console로 이동합니다.
  5. Google Cloud에서:
    • 서비스 계정 이름을 입력합니다 (예: "subx-service").
    • "키" 탭 → "키 추가" → "새 키 만들기" → JSON 선택 후 다운로드합니다.
  6. Google Play Console로 돌아가서, 방금 만든 서비스 계정에 앱 권한을 부여합니다:
    • "재무 데이터 보기"와 "주문 관리" 권한을 체크합니다.
    • 해당 앱을 선택하고 저장합니다.

SubX에 입력하기: SubX 대시보드 → 앱 → Android 앱 선택 → 스토어 인증 탭에서 다운로드한 JSON 키 파일을 업로드합니다.

2

Set Up Real-Time Notifications (RTDN)

어디서? Google Play Console→앱 선택→수익 창출→수익 창출 설정

Apple과 마찬가지로, Google도 구독 상태가 바뀌면 알림을 보냅니다. Google은 Cloud Pub/Sub라는 메시지 시스템을 사용합니다.

  1. 먼저 Google Cloud Console에서 Pub/Sub 주제(Topic)를 만듭니다:
    • Pub/Sub → "주제 만들기" 클릭
    • 주제 ID 입력 (예: subx-play-notifications)
    • 생성 완료 후, 해당 주제에 구독(Subscription)을 추가합니다:
      • 전송 유형: "푸시" 선택
      • 엔드포인트 URL에 다음을 입력:
https://api.subx.dev/v1/store/google/{알림토큰}
  1. 주제에 Google Play 권한 추가: 해당 주제의 권한 탭에서 google-play-developer-notifications@system.gserviceaccount.com에 Pub/Sub 게시자 역할을 부여합니다.
  2. Google Play Console → 해당 앱 → 수익 창출 → 수익 창출 설정으로 이동합니다.
  3. "실시간 개발자 알림" 섹션에 주제 이름을 입력합니다:
projects/{프로젝트ID}/topics/{주제ID}
  1. "테스트 알림 보내기"를 클릭하여 연결을 확인합니다.

알림 토큰은 어디서 확인하나요? SubX 대시보드 → 앱 → Android 앱 선택 →스토어 인증 탭 하단에 전체 URL이 표시되어 있습니다.

서비스 계정 JSON 키 파일은 안전하게 보관하세요! Keep your service account JSON key file safe! If this file is leaked, anyone can access your Google Play data. We recommend deleting the local file after uploading to SubX.

Additional Settings (Optional)

Adjust the following options in App Settings on the SubX dashboard:

SettingDescription
Notification Forwarding URLAlso forwards notifications received from Apple/Google to your server. Use this when you need to process notifications on your own server.
Refund PolicyRevoke immediately (default): Revoke subscription entitlement immediately on refund. Keep until expiry: Keep subscription active until original expiry date even after refund.
Apple Small Business ProgramEnable if you are enrolled in Apple's Small Business Program. Commission drops from 30% to 15% and is reflected in revenue analytics.

Verify Integration

After completing all settings, check the integration status in the SubX dashboard:

  1. 대시보드 → 앱 → 해당 앱 선택
  2. 스토어 인증 탭에서 각 항목의 상태가 녹색 체크로 표시되는지 확인합니다
  3. Apple의 경우: App Store Connect에서 "테스트 알림 보내기"를 눌러 확인
  4. Google의 경우: Play Console의 실시간 알림에서 "테스트 알림 보내기"를 눌러 확인

Sandbox / 테스트 계정으로 먼저 테스트하는 것을 강력히 권장합니다.We strongly recommend testing with Sandbox / test accounts first. You can verify the complete subscription flow without real payments.

Next Steps

  • SDK Integration — iOS/Android 앱에 SubX SDK를 설치합니다.
  • Webhooks — 서버에서 구독 이벤트를 수신합니다.
  • REST API — API로 직접 구독을 관리합니다.
Store Setup | SubX