한 플러그인에 탭 화면(iframe)과 웹 워커를 함께 넣는 패키지 형식 문의

[시즌7]

어떤 제품을 사용하나요?

• 제품: POS 플러그인
• SDK 또는 API 버전: @tossplace/pos-plugin-sdk 0.0.28
• 환경: 개발 (개발 배포 · 테스트 기기)

무엇이 궁금한가요?

탭 화면(iframe) 플러그인에서 draftOrder.startPayment()로 결제를 시작하면, POS가 결제 화면으로 넘어가면서 탭 화면이 닫혀 payment.on('paid') 이벤트를 받지 못합니다. 그래서 결제가 끝날 때마다 점원이 ☰ → 서비스 연동 → 플러그인으로 다시 들어가야 합니다.

이를 해결하려고 웹 워커가 POS에 상주하며 payment.on('paid')를 받아 처리하게 하고, 결제가 끝나면 SDK 0.0.28의 navigation.navigate('plugin-tab', packageName)으로 우리 플러그인 탭으로 이동시키려고 합니다. SDK 소개 문서에 "웹 워커와 탭 화면을 함께 쓰는 구조"가 언급돼 있어 아래를 여쭙니다.

1. 한 플러그인에 탭 화면과 웹 워커를 함께 넣으려면 패키지(zip) 구조나 manifest를 어떻게 써야 하나요? (파일 이름, 위치, manifest 항목 등)
2. 함께 넣을 수 없다면, 웹 워커를 별도 플러그인으로 등록해야 하나요? 그 경우 탭 플러그인과 storage를 공유하거나 pluginUnicast로 통신할 수 있나요? (send(message, to)의 to에는 무엇을 넣나요?)
3. navigation.navigate('plugin-tab', packageName)의 packageName에는 무엇을 넣어야 하나요? (plugin.getPluginInfo().name 값인지, 탭 제목인지)
4. 결제 완료 후 POS가 원래 플러그인 탭으로 돌아오게 하는 다른 권장 방법이 있다면 알려 주세요.

오류가 있다면 알려주세요

• 발생 시각: 2026-10-24 오전 11시 50분 ~ 12시 10분 (한국 시간)
• 재현 방법:
  a. dist/ 안에 탭 화면 파일(iframe-manifest.json, index.html, assets/)과 웹 워커 빌드 파일(main.js)을 함께 넣어 zip 생성
  b. 개발자센터 개발 배포로 업로드 → POS 완전 종료 후 재실행
• 기대한 결과와 실제 결과:
  • 기대: 테스트 기기에 새 버전(탭 + 웹 워커)이 적용됨
  • 실제: 새 버전이 적용되지 않고 라이브 버전이 표시됨. 같은 구성에서 main.js만 빼고 올리면 새 버전이 정상 적용됨
• 오류 코드·메시지: 업로드 시 표시된 오류 없음 (POS에서도 별도 오류 표시 없음)

---

[토스플레이스-개발자센터]

안녕하세요. 토스플레이스 개발자센터입니다.

탭 화면과 웹 워커 구성, 결제 후 화면 복귀 방법을 안내 드립니다.

1. 패키지와 앱 등록
현재 개발자센터에서는 실행 환경을 탭 화면 또는 웹 워커로 구분해 등록합니다. 탭 화면 앱과 웹 워커 앱을 각각 등록·배포하고, 같은 매장에 활성화하는 방식으로 구성해 주세요. ‘함께 사용하는 구조’는 두 역할을 연계한다는 의미이며, 파일을 한 ZIP에 넣는 것만으로 두 실행 환경이 함께 활성화되는 것은 아닙니다.
탭 화면 ZIP은 최상위에 iframe-manifest.json과 화면 파일을, 웹 워커 ZIP은 최상위에 main.js를 포함합니다. 각 탭 화면 가이드와 웹 워커 가이드의 샘플로 각각 빌드해 주세요.

2. 앱 간 데이터 전달
서로 다른 앱의 Storage는 공유되지 않습니다. 실행 중인 앱 간에는 Plugin Unicast API를 사용할 수 있으며, send(message, to)의 to에는 수신할 앱의 앱 ID(packageName)를 넣습니다.
탭이 닫힌 동안의 메시지를 나중에 자동으로 받는 구조로 의존하지 말고, 결제 결과는 서버에 저장해 탭을 다시 열 때 조회하도록 구성해 주세요.

3. 이동할 탭 지정
navigation.navigate('plugin-tab', packageName)의 packageName도 이동할 탭 앱의 앱 ID입니다. 해당 탭 앱에서 조회한 plugin.getPluginInfo().name과 같은 값이며, 화면에 표시되는 탭 제목이나 숫자 App ID가 아닙니다. 워커에서 조회한 name은 워커 자신의 ID이므로 그대로 넣지 않도록 주의해 주세요.

4. 결제 후 복귀
웹 워커에서 payment.on('paid')를 수신한 뒤, 해당 서비스의 주문인지와 전체 결제 완료 여부를 확인하고 탭 앱으로 이동해 주세요. 분할결제는 결제 건마다 이벤트가 발생하므로, 주문의 paymentPrice.paymentUnpaidValue가 0인지 확인하는 과정이 필요합니다.
같은 흐름을 안내한 기존 결제 이벤트 답변과 화면 자동 이동 공지를 함께 참고해 주세요.

개발 배포가 적용되지 않은 원인은 패키지에 main.js가 있다는 사실만으로 확정하기 어렵습니다. 해당 앱 ID, 개발 배포 버전 번호, POS 시리얼번호를 개발자센터 메일로 전달 부탁 드립니다. 발생 시간은 글에 남겨주신 10월 24일 11:50~12:10 KST 기준으로 확인하겠습니다.