스냅툴 구독킷
연동 가이드

iframe 연동

구독킷 iframe 연동 방법 안내

iframe 연동 가이드

구독킷은 결제 페이지와 구독 관리 포털을 iframe으로 쉽게 연동할 수 있도록 지원합니다.

지원하는 페이지 타입

  • 카드 등록 페이지 (card-registration)
  • 사전 주문 페이지 (pre-order)
  • 카드 변경 페이지 (card-update)
  • 구독 포털 (subscription-portal)

기본 사용법

iframe URL 생성

const EXTERNAL_BASE_URL = 'https://subscription-kit-admin.snap-tool.com/external';
const url = new URL(`${EXTERNAL_BASE_URL}/${pageType}`);
url.searchParams.append('mode', 'iframe');

iframe 요소 추가

<iframe
  src="https://subscription-kit-admin.snap-tool.com/external/card-registration?mode=iframe"
  width="100%"
  height="600px"
  frameBorder="0"
  allow="payment"
/>

메시지 수신 설정

window.addEventListener('message', (event) => {
  if (event.origin !== EXTERNAL_BASE_URL) return;
 
  const {type, data} = event.data;
  switch (type) {
    case 'CARD_REGISTRATION_SUCCESS':
    // 카드 등록 완료 처리
    break;
    case 'PAYMENT_SUCCESS':
    // 결제 완료 처리
    break;
    case 'ERROR':
    // 에러 처리
    break;
  }
});

페이지별 연동 가이드

카드 등록 페이지

const CardRegistration = () => {
  const handleMessage = (event: MessageEvent) => {
    const {type, data} = event.data;
    if (type === 'CARD_REGISTRATION_SUCCESS') {
      console.log('카드 끝번호:', data.cardEndNumber);
    }
  };
 
  useEffect(() => {
    window.addEventListener('message', handleMessage);
    return () => window.removeEventListener('message', handleMessage);
  }, []);
 
  return (
  <iframe
  src="https://subscription-kit-admin.snap-tool.com/external/card-registration?customerKey=USER_123&productId=PRODUCT_456&mode=iframe"
  width="100%"
  height="600px"
  frameBorder="0"
  allow="payment"
  />
  );
};

필수 파라미터

파라미터설명
customerKey고객 식별자
productId구독 상품 ID
mode'iframe' 고정값

옵션 파라미터

파라미터설명기본값
quantity구매 수량1
withTrial무료체험 시작 여부false
withPayment즉시 결제 여부false
discountCodes할인 코드 목록 (쉼표로 구분)-

무료체험과 즉시 결제는 동시에 설정할 수 없습니다.

사전 주문 페이지

사전 주문 페이지는 실제 결제 없이 최종 결제 금액을 미리 계산하여 보여줍니다.

const PreOrder = () => {
  const handleMessage = (event: MessageEvent) => {
  const {type, data} = event.data;
  if (type === 'PRICE_CALCULATED') {
    console.log('최종 금액:', data.finalPrice);
    console.log('할인 내역:', data.discounts);
  }
};
 
useEffect(() => {
  window.addEventListener('message', handleMessage);
  return () => window.removeEventListener('message', handleMessage);
}, []);
 
return (
  <iframe
    src="https://subscription-kit-admin.snap-tool.com/external/pre-order?productId=PRODUCT_456&quantity=2&mode=iframe"
    width="100%"
    height="600px"
    frameBorder="0"
  />
  );
};

필수 파라미터

파라미터설명
productId구독 상품 ID
mode'iframe' 고정값

옵션 파라미터

파라미터설명기본값
quantity구매 수량1
discountCodes할인 코드 목록 (쉼표로 구분)-

메시지 이벤트

구독킷 iframe은 다양한 이벤트를 부모 창으로 전달합니다.

카드 등록 관련

interface CardRegistrationSuccess {
  type: 'CARD_REGISTRATION_SUCCESS';
  data: {
    cardEndNumber: string;
  };
}
 
interface CardRegistrationError {
  type: 'CARD_REGISTRATION_ERROR';
  error: {
    code: string;
    message: string;
  };
}

결제 관련

interface PaymentSuccess {
  type: 'PAYMENT_SUCCESS';
  data: {
    transactionId: string;
    amount: number;
    currency: string;
  };
}
 
interface PaymentError {
  type: 'PAYMENT_ERROR';
  error: {
    code: string;
    message: string;
  };
}

가격 계산 관련

interface PriceCalculated {
  type: 'PRICE_CALCULATED';
  data: {
    originalPrice: number;
    finalPrice: number;
    discounts: Array<{
      code: string;
      type: 'PERCENTAGE' | 'FIXED_AMOUNT';
      value: number;
      appliedAmount: number;
    }>;
  };
}

보안 고려사항

iframe 통합 시 다음 보안 사항을 반드시 확인하세요:

  • 올바른 도메인에서만 메시지를 수신하도록 origin 체크
  • 결제 관련 민감 정보는 항상 암호화 전송
  • CSRF 토큰 검증
// 올바른 origin 체크 예시
window.addEventListener('message', (event) => {
  // 허용된 도메인 체크
  if (event.origin !== 'https://subscription-kit-admin.snap-tool.com') {
    return;
  }
 
  // 메시지 처리
  const { type, data } = event.data;
  // ...
});

문제 해결

iframe이 로드되지 않는 경우

  • HTTPS 프로토콜 사용 여부 확인
  • CSP(Content Security Policy) 설정 확인
  • X-Frame-Options 헤더 확인

결제가 진행되지 않는 경우

  • allow="payment" 속성 확인
  • 팝업 차단 설정 확인
  • 필수 파라미터 전달 여부 확인

Previous

API 연동

On this page