toss-apps

name: toss_apps description: Toss 미니앱 개발 기초 — 프레임워크, TDS 컴포넌트, mTLS 보안, S2S API, Supabase 연동 패턴.

Toss Apps Skill — 개발 기초

Toss 미니앱 개발에 필요한 프레임워크, TDS(Toss Design System), 보안, API, Supabase 연동을 다룬다. 화면 와이어프레임은 /toss_wireframes, 사용자 여정은 /toss_journey를 참조.

1. Service Overview & Process

Apps in Toss run within the Toss application, leveraging its massive traffic.

Service Open Process

1. Agreement & Contract: Sign partnership agreement with Toss.
2. Registration: Register app in Toss Developers Console.
3. Development: Choose Web (WebView), React Native, or Unity.
4. QA & Review: Test in Sandbox app and request formal review.
5. Launch: Once approved, the app is launched within Toss.

2. Development Frameworks & SDKs

Implementations

• Web (WebView): Uses @apps-in-toss/web-framework. Mandatory TDS WebView for non-game apps.
• React Native: Uses @granite-js/react-native as the runtime baseline (the @apps-in-toss/react-native-framework template can be used when scaffolding), with file-based routing.
• Game Engine: Unity/Cocos support via plugins.

JavaScript SDK (AppsInToss object)

The AppsInToss SDK (likely available globally or via the framework) provides:

• Routing: Internal navigation and query parameter handling.
• System Control: Controlling the native back button behavior and app lifecycle.
• Standard APIs: Standard Web APIs (window.open, etc.) are generally supported within the WebView context.

Design Tools

• Toss AppBuilder (Deus): Build screens using TDS components. Supports branding and prototyping.
• Figma: Official component library for design consistency.

3. Toss Design System (TDS) — React Native 전체 컴포넌트 카탈로그

Foundation

Colors (@toss/tds-react-native → colors.*)

Perceptually uniform color space. import { colors } from '@toss/tds-react-native'

Semantic 토큰 (하드코딩 금지 — 반드시 토큰 사용):

• background → #FFFFFF (기본 배경)
• greyBackground → 중립 서피스
• layeredBackground → 오버레이 백
• floatedBackground → 플로팅 요소

프로젝트 컬러 매핑 (현재 하드코딩 → 토큰 전환 대상):

Typography (토큰 스케일 — 하드코딩 금지)

동적 접근성 스케일링을 위해 반드시 토큰 사용. fontSize 직접 입력 금지.

접근성 스케일링: iOS LargeA11y_xxxLarge (100%310%), Android 연속 스케일. 기저 토큰 F11~F42 (42단계) → 위 7개 Typography로 조합. 하드코딩 시 동적 스케일 불가.

3-1. UI 컨트롤 (13)

3-2. 네비게이션 / 레이아웃 (12)

3-3. 피드백 / 정보 (12)

3-4. 오버레이 / 훅 (4)

3-5. 시각 요소 (6)

3-6. 데이터 시각화 (1)

시스템 훅

• useVisualViewport: 키보드 등에 의한 뷰포트 변화 감지

4. Backend & Security (mTLS)

• Requirement: All S2S communication must use mTLS.
• Certificates: Issued via the Developers Console.
• Network: Allow Toss Inbound/Outbound IP ranges in your firewall.
• Repo Path Contract: This project keeps backend code in-repo at Backend/app/... and migrations at Backend/alembic/..., while Toss bridge functions stay in supabase/functions/....

5. S2S API & Authentication

Toss Login (OAuth2)

• Profile Endpoint: GET /api-partner/v1/apps-in-toss/user/oauth2/login-me
• Authorization: Bearer {AccessToken}
• Note: User profile fields may be null based on consent.

Core Features

• In-App Payment (IAP): Consumable/Non-consumable. Refunds follow OS policies.
• Smart Message: Push (OS) and Notification (Bell). Titles max 13 chars, body max 20 chars.
• Promotion: Toss Points integration via S2S APIs.
• Game Center: Global leaderboards and player profiles.

6. AI & LLM Integration

MCP Server Support

Apps in Toss provides an MCP (Model Context Protocol) server for Cursor and Codex.

• Benefits: AI refers to SDK docs directly, detects API errors, and generates accurate code.

Search & Installation

• docs-search: Semantic search based on the comprehensive llms-full.txt index.
• Codex: Install via $skill-installer using repo toss/apps-in-toss-skills.
• Codex: Install from marketplace.

7. Testing & Launch Checklist

단계 1: 로컬 개발 (일상 개발 기본)

• npm run dev로 로컬 개발 서버 실행
• iOS Simulator / Android Emulator에서 토스 샌드박스 앱으로 로컬 검수
• Android 에뮬레이터 연결: adb reverse tcp:8081 tcp:8081 + adb reverse tcp:5173 tcp:5173
• 샌드박스 앱에서는 문서 표기(Bedrock 열기) 기준으로 개발 서버 진입
• Hot Reload 중심으로 UI/상태/라우팅 검수
• 참고: 일상 개발은 폰 연결 없이 가능하지만, 토스 인증/일부 시나리오는 실기기 확인이 필요할 수 있음

단계 2: 코드 레벨 테스트 (자동화)

• FE 단위: Jest + React Native Testing Library
• BE 단위: pytest
• 통합: Toss Auth mock, IAP 시뮬레이션, Edge Function contract test
• IAP 통합 테스트에 verify-iap-order 실패 복구 케이스 포함

단계 3: Sandbox/실기기 테스트 (출시 전 필수)

• 토스 Sandbox 앱 실기기 테스트 최소 1회 완료 후 심사 요청
• .ait 번들 업로드 + QR 테스트로 실환경 플로우 확인
• IAP 필수 3시나리오: 구매 성공 / 결제 성공 후 서버 지급 실패 복구 / 에러 처리
• 광고는 Sandbox 앱에서 테스트 불가. 토스 앱 QR 테스트로 별도 검증
• intoss-private:// 스킴 기반 사설 번들 테스트 활용
• 릴리즈 전 UX Writing 가이드 필수 점검: UX Writing Guide

UX 라이팅 5원칙 (심사 필수)

예외 허용: 서비스 종료/기간 만료, 사용자 영향 설명, 안심 문구에서는 수동형("~돼요") 허용. "되어요" → 모두 "돼요" 로 통일.

TaillogToss 주요 점검 문구:

• Toast: "~에 실패했어요. 다시 시도해주세요" (긍정형 전환 검토)
• EmptyState: "아직 기록이 없어요" → "첫 기록을 남겨보세요"
• Dialog 확인 버튼: "확인" / "취소" (간결체 유지)
• BottomCTA: 동사형 ("기록하기", "시작하기", "저장하기")

7.5 TDS 컴포넌트 갭 및 대안

토스 미니앱 샌드박스 런타임에서 네이티브 모듈 링킹이 불가능하므로, TDS에 없는 UI 패턴은 아래 대안으로 구현한다.

Chip 구현 패턴

// components/Chip.tsx — TouchableOpacity + Badge 래퍼
import { TouchableOpacity } from 'react-native';
import { Badge } from '@toss/tds';

interface ChipProps {
  label: string;
  selected?: boolean;
  onPress: () => void;
}

export function Chip({ label, selected, onPress }: ChipProps) {
  return (
    <TouchableOpacity onPress={onPress}>
      <Badge
        text={label}
        variant={selected ? 'info' : 'default'}
      />
    </TouchableOpacity>
  );
}

Accordion 구현 패턴

// components/Accordion.tsx — Animated.View height 보간
import { Animated, LayoutAnimation } from 'react-native';

export function useAccordion(initialExpanded = false) {
  const [expanded, setExpanded] = useState(initialExpanded);
  const toggle = () => {
    LayoutAnimation.configureNext(LayoutAnimation.Presets.easeInEaseOut);
    setExpanded(!expanded);
  };
  return { expanded, toggle };
}

7.6 차트 전략 — TDS BarChart + WebView 하이브리드

제약 사항

• Victory Native 사용 불가: react-native-svg, react-native-reanimated 등 네이티브 모듈 링킹 불가 (토스 미니앱 샌드박스 런타임)
• TDS에는 BarChart 1개만 존재 (Section 3-6 참조)

하이브리드 전략

ChartWebView 재사용 컴포넌트

// lib/charts/ChartWebView.tsx
import WebView from '@granite-js/native/react-native-webview';
import { useColorScheme } from '@toss/tds';

interface ChartWebViewProps {
  type: 'radar' | 'heatmap' | 'line';
  data: unknown;
  height?: number;
}

export function ChartWebView({ type, data, height = 250 }: ChartWebViewProps) {
  const colorScheme = useColorScheme();
  // TDS 색상 토큰에 맞춰 Chart.js 테마 자동 적용
  const html = generateChartHTML(type, data, colorScheme);
  return <WebView source={{ html }} style={{ height }} />;
}

색상 토큰 매칭

• WebView 내 Chart.js 차트는 TDS Colors v5 토큰을 CSS 변수로 주입
• 다크/라이트 모드 자동 대응: useColorScheme() → Chart.js 테마 전환

7.7 토스 Ads SDK 2.0 — 보상형 광고

지원 광고 유형

제약 사항

• react-native-google-mobile-ads 직접 사용 불가 → 토스 통합 SDK 필수
• 토스 광고 우선 노출. AdMob 폴백은 토스 SDK 공식 지원 범위에서만 허용 (미지원 시 무광고 폴백)
• 테스트 ID: ait-ad-test-rewarded-id

보상형 광고 터치포인트 (3개)

전환 심리

Skeleton 블러 → TextButton("광고 보고 열기") → Rewarded 시청 → 1회 해제 → "매번 광고 귀찮다 → PRO 구독" 자연 전환

8. Toss + Supabase Integration Pattern

End-to-End Login Flow

Follow this runtime path:

1. Client calls appLogin() from @apps-in-toss/framework.
2. Client sends { authorizationCode, referrer } to Supabase Edge Function (login-with-toss).
3. Edge Function calls Toss OAuth endpoints with mTLS:
   • POST /api-partner/v1/apps-in-toss/user/oauth2/generate-token
   • GET /api-partner/v1/apps-in-toss/user/oauth2/login-me
4. Edge Function maps Toss userKey to Supabase Auth account.
5. Edge Function returns Supabase session tokens.
6. Client runs supabase.auth.setSession() and continues onboarding.

Client Baseline

• Env: EXPO_PUBLIC_SUPABASE_URL, EXPO_PUBLIC_SUPABASE_ANON_KEY
• Init:

import { createClient } from '@supabase/supabase-js';
const supabase = createClient(process.env.EXPO_PUBLIC_SUPABASE_URL!, process.env.EXPO_PUBLIC_SUPABASE_ANON_KEY!);

• Login bridge:

const { data } = await supabase.functions.invoke('login-with-toss', {
  body: { authorizationCode, referrer },
});
await supabase.auth.setSession({
  access_token: data.access_token,
  refresh_token: data.refresh_token,
});

Edge Function Baseline

Use server secrets only:

• SUPER_SECRET_PEPPER
• SUPABASE_URL
• SUPABASE_SERVICE_ROLE_KEY
• TOSS_CLIENT_CERT_BASE64
• TOSS_CLIENT_KEY_BASE64

Function requirements:

1. Decode cert/key base64 and create Deno.createHttpClient({ cert, key }).
2. Call Toss OAuth APIs using client: tossHttpClient.
3. Derive deterministic password from tossUserKey + pepper (PBKDF2).
4. Sign in existing auth user, otherwise create user and insert public.users.
5. Return session payload (access_token, refresh_token).

• Path note: Edge Functions live under supabase/functions/...; FastAPI server code lives under Backend/app/... in this repository.

Supabase Config

Example supabase/config.toml:

[functions.login-with-toss]
enabled = true
verify_jwt = true
import_map = "./functions/login-with-toss/deno.json"
entrypoint = "./functions/login-with-toss/index.ts"

If pre-login invoke gets 401, use verify_jwt = false for this endpoint or ensure JWT exists before invoke.

DB Contract

Use UUID identity linked to auth.users:

CREATE TABLE IF NOT EXISTS public.users (
  id UUID PRIMARY KEY REFERENCES auth.users(id) ON DELETE CASCADE,
  toss_user_key TEXT UNIQUE NOT NULL,
  role TEXT DEFAULT 'user' NOT NULL CHECK (role IN ('user', 'trainer', 'org_owner', 'org_staff'))
);
ALTER TABLE public.users ENABLE ROW LEVEL SECURITY;
CREATE POLICY "Allow individual read access" ON public.users FOR SELECT USING (auth.uid() = id);
CREATE POLICY "Allow individual update access" ON public.users FOR UPDATE USING (auth.uid() = id);

Never mix integer users.id schema with Supabase Auth UUID schema.

9. 콘솔 등록 & 운영 API (공식 문서 기반)

9.1 콘솔 앱 등록 프로세스

1. 콘솔 가입 (토스 비즈니스 회원, 만 19세 이상)
2. 워크스페이스 생성 → 앱 등록 (개발 전에도 등록 가능)
3. 사업자 정보 등록 (토스 로그인, IAP 등 수익화 기능 사용 시 필수)
4. 토스 로그인 설정: 약관 URL + 동의문 URL + 연결 끊기 콜백 등록
5. mTLS 인증서 발급 (콘솔에서 발급, 만료 전 무중단 교체 = 2장 병행 등록)

9.2 약관 등록 — 자동 동의 화면

• 콘솔에 약관 URL 등록 → 토스 앱이 OAuth 시 WebView로 자동 노출
• 개발자가 약관 동의 UI를 별도로 구현할 필요 없음
• 첫 로그인 시에만 동의 요청, 이후 세션 유지
• agreedTerms 배열로 사용자가 동의한 약관 목록 반환

9.3 연결 끊기 콜백 (Disconnect Callback)

토스 → 파트너 서버 방향. Basic Auth 인증 (mTLS 아님).

POST {콜백URL}
Headers: Authorization: Basic {base64(id:password)}
Content-Type: application/json
Body: {"userKey": 443731103, "referrer": "UNLINK"}
Response: 200 OK

• GET/POST 모두 지원 (콘솔에서 선택)
• CORS: https://apps-in-toss.toss.im 허용 (콘솔 테스트 버튼용)
• 콘솔 테스트 시 userKey=0, referrer="UNLINK" 전송
• Basic Auth ID/PW: 콘솔 + 서버 secrets에 동일 값 설정

9.4 S2S API 엔드포인트 (공식 확인)

모든 S2S 호출은 mTLS 클라이언트 인증서 필요.

• Authorization Code 유효기간: 10분
• AccessToken 유효기간: 1시간 (3600초)
• RefreshToken 유효기간: 14일
• scope: 동의된 권한 (예: user_ci, user_name, user_phone)

9.5 PII 복호화 (AES-256-GCM)

Toss가 반환하는 사용자 정보는 AES-256-GCM 암호화 상태.

• 복호화 키 + AAD: 콘솔에서 이메일로 별도 제공
• IV: 12바이트 (암호문 앞 12바이트)
• AAD: Additional Authenticated Data (콘솔 제공)

// 복호화 예시 (Deno Edge Function)
function decryptTossPII(encryptedBase64: string, keyHex: string, aad: Uint8Array): string {
  const encrypted = Uint8Array.from(atob(encryptedBase64), c => c.charCodeAt(0));
  const iv = encrypted.slice(0, 12);
  const ciphertext = encrypted.slice(12);
  // AES-256-GCM decrypt with iv + aad
}

9.6 mTLS 인증서 배포

• 인증서: 콘솔에서 발급, PEM 형식 (cert + private key)
• Supabase secrets로 등록:
  • TOSS_CLIENT_CERT_BASE64 = base64(taillog_public.crt)
  • TOSS_CLIENT_KEY_BASE64 = base64(taillog_private.key)
• Edge Function에서 사용:

const cert = atob(Deno.env.get('TOSS_CLIENT_CERT_BASE64')!);
const key = atob(Deno.env.get('TOSS_CLIENT_KEY_BASE64')!);
const httpClient = Deno.createHttpClient({ certChain: cert, privateKey: key });

• ⚠️ 인증서 파일은 git 저장소에 포함하지 않음 (.gitignore)
• 만료 전 교체: 새 인증서 발급 → secrets 업데이트 → 기존 인증서 7일 유예 후 삭제

10. Ads SDK 2.0 ver2 — 공식 인터페이스 (2026-02 확인)

공식 함수 시그니처

// 기존 v1: loadRewardedAd / showRewardedAd → 폐기
// 공식 ver2: loadFullScreenAd / showFullScreenAd + adGroupId + destroy
interface TossAdsSdk {
  loadFullScreenAd(options: { adGroupId: string }): Promise<void>;
  showFullScreenAd(): Promise<{ rewarded: boolean }>;
  isAdLoaded(): boolean;
  destroy(): void;  // cleanup — useEffect return에서 호출
}

• adGroupId: 콘솔에서 발급받는 광고 그룹 ID (기존 unitId 대체)
• destroy(): 광고 리소스 정리 — 컴포넌트 언마운트 시 필수 호출
• 테스트 adGroupId: ait-ad-test-rewarded-id

11. IAP SDK — 공식 결제 패턴 (2026-02 확인)

createOneTimePurchaseOrder (일회성 구매)

import { createOneTimePurchaseOrder } from '@apps-in-toss/framework';

const cleanup = createOneTimePurchaseOrder({
  options: { sku: 'pro_monthly' },
  processProductGrant: async (receipt) => {
    // Edge Function으로 서버 검증 + 상품 지급
    const result = await supabase.functions.invoke('verify-iap-order', {
      body: { orderId: receipt.orderId, productId: receipt.productId,
              transactionId: receipt.transactionId }
    });
    return result.data?.ok === true;  // true=완료, false=환불 트리거
  },
  onEvent: (event) => { /* PURCHASE_STARTED, PAYMENT_COMPLETED, GRANT_COMPLETED */ },
  onError: (error) => { /* 결제 에러 UI */ },
});
// cleanup() — 결제 프로세스 취소/정리

미완료 주문 복구 (앱 시작 시)

import { getPendingOrders, completeProductGrant } from '@apps-in-toss/framework';

const pending = await getPendingOrders();
for (const order of pending) {
  await completeProductGrant(order.orderId);
}

SUBSCRIPTION 상품 유형

• 토스 IAP가 SUBSCRIPTION 타입 공식 지원 (2026년~)
• PRO 월간을 ONE_TIME 반복 대신 SUBSCRIPTION으로 등록 가능
• 자동 갱신, 해지, 유예 기간 등 토스가 관리

주의

• @apps-in-toss/framework 패키지가 @granite-js/react-native에 포함인지 별도 설치인지 확인 필요
• 현재 프로젝트 package.json에 미포함 — 확인 전까지 Edge Function 직통 방식 유지

11.5 접근성 체크리스트

11.6 디자인 퀄리티 원칙 (토스 기준)

12. 심사 체크리스트 (공식 Review Requirements)

CORS 허용 origin

• https://apps-in-toss.toss.im — 콘솔 테스트 버튼
• https://{appName}.private-apps.tossmini.com — Sandbox 테스트
• 프로덕션은 토스 앱 내부 WebView → CORS 불필요