FacePass API

토스 프론트에서 얼굴입장 인증 기능을 제공하는 API입니다. 얼굴 인식을 통한 사용자 인증 및 결과 처리를 지원합니다.

Methods

start

얼굴입장 인증을 시작합니다.

Parameters

파라미터	타입	필수	기본값	설명
params	Object		-	인증 시작 파라미터
params.showResultScreen	boolean		true	결과 화면 직접 표시 여부

Response

성공 시 (type: 'SUCCESS')

{
  type: "SUCCESS"; // 인증이 성공적으로 시작됨
}

취소 시 (type: 'FAILED')

{
  type: "FAILED"; // 페이스패스 화면 렌더링 실패
}

Example

/**
 * 얼굴입장 인증 시작 (기본값: 결과 화면 표시)
 */
const result = await sdk.facePass.start();

/**
 * 얼굴입장 인증 시작 (결과 화면 표시 여부 설정)
 */
const result = await sdk.facePass.start({
  showResultScreen: false, // 결과 화면을 직접 표시하지 않음
});

if (result.type === "FAILED") {
  console.log("페이스패스 화면 렌더링에 실패했습니다.");
  return;
}

console.log("인증이 시작되었습니다.");

listenData

얼굴입장 인증 결과를 이벤트로 수신합니다.

Parameters

파라미터	타입	필수	기본값	설명
callback	Function	✓	-	인증 결과를 처리할 콜백 함수

콜백 함수 파라미터:

• params.merchantUserKey (string, optional): 가맹점 사용자 키
• params.authenticated (boolean): 인증 성공 여부
• params.result (string): 인증 결과 코드
  • 'Authenticated': 인증 성공
  • 'FaceFailed': 얼굴 인식 실패
  • 'Blocked': 차단됨
  • 'Denied': 거부됨
  • 'Disconnected': 연결 해제
  • 'WrongCode': 잘못된 코드
  • 'Timeout': 시간 초과
• params.message (string): 결과 메시지

Response

성공 시

Function; // 이벤트 리스너 해제 함수 반환

Example

/**
 * 얼굴입장 인증 결과 이벤트 리스너 등록
 * @param {Function} callback 인증 결과를 처리할 콜백 함수
 * @returns {Function} 이벤트 리스너 해제 함수
 */
const unlistenData = sdk.facePass.listenData((params) => {
  console.log("인증 상태:", params.authenticated);
  console.log("결과 코드:", params.result);
  console.log("메시지:", params.message);

  if (params.merchantUserKey) {
    console.log("사용자 키:", params.merchantUserKey);
  }
});

// 이벤트 리스너 해제
unlistenData();

사용 예시

얼굴입장 인증 시작 및 결과 수신

// 1. 결과 이벤트 리스너를 먼저 등록합니다.
const unlisten = sdk.facePass.listenData((params) => {
  switch (params.result) {
    case "Authenticated":
      console.log("인증 성공:", params.message);
      break;
    case "FaceFailed":
      console.log("얼굴 인식 실패:", params.message);
      break;
    case "Blocked":
      console.log("차단된 사용자:", params.message);
      break;
    case "Denied":
      console.log("인증 거부:", params.message);
      break;
    case "Disconnected":
      console.log("연결 해제:", params.message);
      break;
    case "WrongCode":
      console.log("잘못된 코드:", params.message);
      break;
    case "Timeout":
      console.log("인증 시간 초과:", params.message);
      break;
  }

  // 결과 수신 후 리스너 해제
  unlisten();
});

// 2. 얼굴입장 인증을 시작합니다.
const result = await sdk.facePass.start();

if (result.type === "FAILED") {
  // 얼굴입장 화면 띄우기에 실패한 케이스
  // 추가적인 예외 처리가 필요합니다.
  unlisten();
}