테스트 및 문제 해결

POS 플러그인의 개발·운영 환경별 로그 확인 방법을 안내해요.

1. ACL 설정

외부 API나 Sentry 수집 서버를 사용하는 경우 개발자센터 ACL에 해당 도메인을 등록해야 해요.

입력 예시

ACL은 도메인마다 줄을 나누어 입력해요.

https://api.example.com
https://cdn.jsdelivr.net

2. 오류 로그 확인하기

개발 환경과 운영 환경은 로그 확인 방법이 달라요.

2-1. 개발 환경: 로컬 테스트

플러그인 유형에 따라 공식 템플릿에서 제공하는 로컬 테스트 방식을 사용해요.

플러그인 유형	실행 명령어	로그 확인 위치
탭 화면(iframe)	npm run dev	로컬 브라우저 개발자 도구의 콘솔
워커	npm run test:dev	테스트를 실행한 터미널의 Jest 결과

• 탭 화면 플러그인 템플릿
• 워커 플러그인 템플릿

2-2. 운영 환경: Sentry

적용 범위

아래 가이드는 POS 탭 화면(iframe) 플러그인과 POS 워커 플러그인에 모두 적용 가능해요.

자체 로그 수집 권장

플러그인 이슈 발생 시 원인 파악을 위해 자체 로그 수집을 권장해요. Sentry 연동이 없거나 자체적으로 앱 로그를 수집하지 않으면 추후 운영 문제 해결이 어려워요. 토스플레이스에서는 파악된 이슈가 프론트/POS 시스템 개선이 필요한 경우에 한하여 지원이 가능해요.

수집 범위

이 가이드의 Sentry Browser SDK 연동 범위는 플러그인 JavaScript 오류와 플러그인이 직접 기록한 로그예요. 프론트·POS 앱 및 결제 모듈의 네이티브 로그는 포함하지 않아요.

Sentry 설치 및 초기화

아래 예시는 빌드 검증을 완료한 Sentry Browser SDK 10.69.0을 기준으로 해요. 이 버전의 설치·번들링에는 Node.js 18 이상이 필요해요. SDK를 프로젝트 의존성으로 설치하고 플러그인 배포 번들에 포함해요.

npm install @sentry/browser@10.69.0 --save

플러그인 진입 파일에서 Sentry를 초기화해요.

import * as Sentry from "@sentry/browser";

Sentry.init({
  dsn: "YOUR_SENTRY_DSN",
  release: "PLUGIN_ID@PLUGIN_VERSION",
  enableLogs: true,
});

Sentry JavaScript 설치 가이드와 로그 가이드를 참고해요.

Sentry 프로젝트의 Client Keys (DSN) 설정에서 실제 DSN을 확인해요. DSN에서 프로토콜과 호스트만 추출하여 개발자센터 ACL에 등록해요. 아래 값은 형식 예시이며 그대로 사용하지 않아요.

DSN 형식: https://{PUBLIC_KEY}@{SENTRY_INGEST_HOST}/{PROJECT_ID}
ACL 형식: https://{SENTRY_INGEST_HOST}

Sentry 수집 호스트는 일반 웹페이지가 아닌 이벤트 수집 API예요. ACL 주소를 브라우저에서 직접 열었을 때 404가 표시되어도 주소가 잘못된 것은 아니에요.

운영 적용 전 실제 단말에서 로그가 Sentry에 수신되는지 확인해주세요.

POS SDK에서 발생한 오류를 Sentry로 수집하려면 플러그인 진입 파일에 에러 리스너를 등록해요.

import { posPluginSdk } from "@tossplace/pos-plugin-sdk";

globalThis.Sentry = Sentry;
posPluginSdk.error.addErrorListener(Sentry.captureException);

Sentry 로그 기록 권장 범위

다음 항목을 확인할 수 있도록 기록해주세요.

• 주문 및 paid·cancel 결제 이벤트의 수신·처리 결과
• 외부 API 호출 및 서버 동기화 결과
• JavaScript 오류와 처리되지 않은 Promise 오류
• posPluginSdk.plugin.getPluginInfo()로 확인한 플러그인 이름·버전과 posPluginSdk.device.getDeviceInfo()로 확인한 POS 시리얼번호

민감정보 보호

다음 정보는 Sentry에 기록하지 않아요.

• 카드번호 및 결제 인증정보
• 고객 이름·전화번호 등 개인정보
• Access Key, Access Secret, 인증 토큰
• 개인정보나 인증정보가 포함된 API 요청·응답 전문 및 URL
• 개인정보가 포함된 paymentKey·외부 주문 키 등 솔루션사 식별값

Browser SDK는 UI 클릭·키 입력, 콘솔, fetch/XHR 요청, 페이지 이동 등을 breadcrumb로 수집할 수 있어요. 민감정보가 포함되지 않도록 기록하고, 필요한 경우 beforeBreadcrumb에서 제거하거나 마스킹해주세요.

Sentry.logger나 Sentry.captureException()에 직접 넣은 값이 SDK에서 자동으로 마스킹된다고 가정하면 안 돼요. 필요한 경우 beforeSend, beforeSendLog에서 전송할 데이터를 마스킹해주세요. 자세한 내용은 Sentry 데이터 관리 가이드와 breadcrumb 가이드를 참고해주세요.

3. 문의사항

플러그인에서 수집한 로그를 먼저 확인해 주세요. 자체 확인으로 원인을 파악하기 어렵거나 POS 시스템 동작 확인이 필요한 경우 문의해 주세요.

간단한 질문이나 다른 개발자의 해결 사례가 궁금하다면 개발자 포럼에서 자유롭게 질문해 주세요.

정확한 확인을 위해 아래 정보를 developer-support@tossplace.com으로 보내주세요.

1. 플러그인 앱 이름:
2. 개발자센터 계정 이메일:
3. POS 시리얼번호:
4. 플러그인 연결 가맹점 정보:
5. 문의 내용: 발생 일시, 재현 절차, 오류 메시지