안녕하세요, 앱인토스입니다.
SDK 3.1.1 이상으로 빌드해 업로드한 WebView 미니앱은 SDK 2.x와 동일한 Origin으로 서비스됩니다.
SDK 2.x에서 SDK 3.x로 마이그레이션한 미니앱에서 localStorage, IndexedDB, OPFS를 사용하고 있다면 Storage 데이터 마이그레이션 및 병합이 필요합니다.
또한 외부 서버와 통신하는 미니앱은 CORS 오류가 발생하지 않도록 서버의 허용 Origin을 확인해 주세요.
Unity SDK도 3.1.1 버전을 지원해요.
Unity로 개발한 미니앱은 Unity SDK를 3.1.1 버전 이상으로 업데이트해 이용해 주세요.
업데이트 후에는 아래 Storage 데이터와 CORS 설정을 함께 확인해 주세요
영향 대상
아래 조건에 해당하는 WebView 미니앱이 대상입니다.
- SDK 2.x에서 SDK 3.x로 마이그레이션했고 localStorage, IndexedDB, OPFS를 사용한 미니앱
- SDK 2.x에서 SDK 3.x로 마이그레이션했고 외부 서버와 통신하는 미니앱
- SDK 3.x로 처음 시작했고 외부 서버와 통신하는 미니앱
SDK 2.x를 계속 사용 중인 미니앱은 이번 변경으로 인한 별도 조치가 필요하지 않습니다.
변경 내용
SDK 3.1.1부터 WebView 미니앱은 SDK 2.x에서 사용하던 Origin으로 서비스됩니다.
- 실제 서비스 환경: https://{appName}.apps.tossmini.com
- 콘솔 QR 테스트 환경: https://{appName}.private-apps.tossmini.com
SDK 3.x에서 사용하던 기존 Origin은 아래와 같습니다.
- 실제 서비스 환경: https://{appName}.web.tossmini.com
- 콘솔 QR 테스트 환경: https://{appName}.private-web.tossmini.com
조치 사항
1. Storage 데이터 확인 및 병합
SDK 2.x에서 SDK 3.1.1로 마이그레이션한 뒤 localStorage, IndexedDB, OPFS를 사용하고 있다면 데이터를 확인하고 병합해 주세요.
Migration.getOriginStorage() API를 제공합니다.
이 API를 사용하면 이전 Origin과 현재 Origin의 Storage 데이터를 함께 조회할 수 있습니다.
조회한 데이터는 각 앱의 저장 규칙에 맞게 병합해 주세요.
2. CORS 허용 Origin 추가
미니앱에서 외부 서버와 통신하고, 서버에서 CORS 허용 Origin을 제한하고 있다면 아래 Origin을 추가해 주세요.
- https://{appName}.apps.tossmini.com
- https://{appName}.private-apps.tossmini.com
위 Origin이 허용되어 있지 않으면 SDK 3.1.1 이상 적용 후 서버 API 호출 시 CORS 오류가 발생할 수 있습니다.
SDK 3.x로 처음 시작한 미니앱
SDK 3.x로 처음 시작한 미니앱은 토스에서 Storage 자동 마이그레이션을 지원합니다.
따라서 별도의 localStorage, IndexedDB, OPFS 마이그레이션 및 병합 작업은 필요하지 않습니다.
단, 외부 서버와 통신한다면 CORS 허용 Origin은 추가해 주세요.
미대응 시 영향
SDK 2.x에서 SDK 3.1.1로 마이그레이션한 미니앱이 Storage 데이터를 병합하지 않으면 사용자가 기존에 저장한 localStorage, IndexedDB, OPFS 데이터를 앱에서 정상적으로 이어서 사용하지 못할 수 있습니다.
외부 서버와 통신하는 미니앱이 CORS 허용 Origin을 추가하지 않으면 SDK 3.1.1 이상 적용 후 서버 API 호출 시 CORS 오류가 발생할 수 있습니다.
적용 기준
- 적용 버전: SDK 3.1.1 이상
- 적용 대상: SDK 3.1.1 이상으로 빌드해 업로드한 WebView 미니앱
- 변경 후 실제 서비스 Origin: https://{appName}.apps.tossmini.com
- 변경 후 콘솔 QR 테스트 Origin: https://{appName}.private-apps.tossmini.com
수정 이력
- 2026-08-25: SDK 3.1.1 Origin 변경, Storage 마이그레이션 API, CORS 허용 Origin 안내 추가
- 2026-08-27: Unity SDK 3.1.1 버전 추가