연동가이드

테스트 및 문제 해결 ​

프론트 플러그인 테스트 방법 및 다양한 문제 해결 사례를 소개해드려요.

1. ACL 설정 ​

외부 API나 CDN을 사용하는 경우 반드시 ACL에 해당 도메인을 등록해야 해요.

입력 예시

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

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

중요

  • ACL 추가 후 반영을 위해서는 로그아웃 후 재온보딩이 필요해요.
  • 프론트 단말기 > 설정 > 7055 > [매장명] 선택 > 로그아웃 > 로그아웃 완료 후 첫 화면에서 [시작하기] 터치

2. CORS 설정 ​

플러그인 애플리케이션은 토스 프론트 단말기에서 실행되며, 필요에 따라 다음 URL에 대해 CORS 설정을 해주세요.

예시

  • https://[appName].plugin.tossplace.com
  • https://[appName].plugin-dev.tossplace.com

중요

  • appName은 개발자센터에서 확인 가능해요.
  • 모든 서버 요청은 반드시 https로 이루어져야 해요.

3. 오류 로그 확인하기 ​

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

3-1. 개발 환경: 로그 뷰어 활용 ​

테스트 단말기로 등록된 프론트에서는 실시간 로그를 브라우저에서 확인할 수 있어요.

로그 뷰어 접속 방법 ​

  1. 테스트 단말기 등록 확인:

    • 개발자센터에서 해당 프론트를 테스트 단말기로 등록
    • 프론트 화면 상단에 IP:PORT 주소가 표시됨
    프론트 테스트 단말기 모드

  2. 로그 뷰어 접속:

    • 동일한 네트워크에 연결된 노트북/PC에서 접속
    • 브라우저에서 표시된 IP:PORT 주소로 접속
    • 실시간 로그 뷰어가 자동으로 표시됨

    실시간 로그 뷰어

활용 방법 ​

  • 실시간 로그: 플러그인의 콘솔 및 SDK 처리 로그를 실시간으로 확인
  • 에러 추적: JavaScript 에러나 API 호출 실패를 즉시 파악
  • 디버깅: 단말기에서 발생한 로그를 동일 네트워크의 PC에서 확인

개발 팁

로그 뷰어를 활용하면 플러그인 테스트 중 발생하는 문제를 실시간으로 파악할 수 있어 디버깅 효율성이 크게 향상돼요.

3-2. 운영 환경: Sentry ​

자체 로그 수집 권장

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

수집 범위

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

Sentry 설치 및 초기화 ​

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

bash
npm install @sentry/browser@10.69.0 --save

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

js
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에 등록해요. 아래 값은 형식 예시이며 그대로 사용하지 않아요.

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

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

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

번들러가 없는 경우: esbuild 사용 예시

Sentry를 로컬 JavaScript 파일로 번들링하여 플러그인 ZIP에 포함해요.

bash
npm install --save-dev esbuild
js
// sentry-entry.js
import * as Sentry from "@sentry/browser";

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

globalThis.Sentry = Sentry;
bash
npx esbuild sentry-entry.js --bundle --minify --format=iife --target=es2020 --outfile=sentry.bundle.js

플러그인 진입 HTML에서 애플리케이션 스크립트보다 먼저 불러와요.

html
<script src="./sentry.bundle.js"></script>

Sentry 로그 기록 권장 범위 ​

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

  • 결제·결제 취소 요청의 시작, 성공 및 실패
  • getPayment·getPaymentCancel을 이용한 결제·취소 결과 복구
  • 외부 API 호출 및 서버 저장 결과
  • JavaScript 오류와 처리되지 않은 Promise 오류
  • Sentry release와 sdk.app.getSerialNumber()로 확인한 프론트 시리얼번호

민감정보 보호 ​

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

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

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

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

4. 자주 묻는 질문 ​

테스트 단말기를 등록하고 싶어요 ​

A. 프론트 단말기가 테스트 가맹점에 정상 로그인되어야 등록이 가능해요.

  1. 프론트에서 테스트 가맹점으로 로그인 완료
  2. 개발자센터 > 내 애플리케이션 > 테스트 단말기 등록 메뉴에서 해당 단말기 등록

새 버전 출시 후 단말기를 재부팅해야 반영되나요? ​

A. 네, 반드시 프론트 앱 재시작이 필요해요.

  • 설정 → 7055 → 하단 "토스 프론트 재시작" 클릭
  • 단말기 재부팅은 불필요

개발자센터에서 업로드 후 변경사항 확인은 어떻게 해야 하나요? ​

A. 다음 순서로 진행하세요:

  1. 개발자센터에서 새 버전 업로드
  2. 프론트 단말기에서 재시작 실행
  3. 플러그인 실행하여 변경사항 확인

테스트는 어떻게 해야 하나요? ​

A. 체계적인 테스트 계획을 수립하세요:

  1. 기능별 테스트: 각 기능이 정상 동작하는지 확인
  2. 시나리오 테스트: 실제 사용 시나리오대로 테스트
  3. 에러 테스트: 예외 상황에서도 안정적인지 확인
  4. 성능 테스트: 반응 속도 및 안정성 확인

에러 로그는 어떻게 볼 수 있나요? ​

A. 운영 환경에서는 Sentry를 사용하고, 개발 환경에서는 로그 뷰어를 사용해주세요.

5. 문의사항 ​

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

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

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

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