모범 사례

Markdown

이 페이지는 Unico SDK를 통합하고 유지 관리하기 위한 가장 중요한 지침을 정리합니다. 이러한 사례를 따르면 통합 오류를 줄이고, 보안 사고를 예방하며, 원활한 프로덕션 출시를 보장합니다.

시작하기

레퍼런스 앱으로 시작하기

Unico는 reference-apps 저장소에서 각 SDK용 레퍼런스 앱을 제공합니다. 각 앱은 전체 사용자 여정을 구현합니다.

SDK를 항상 최신 상태로 유지하기

SDK는 더 높은 보안과 새로운 기능을 제공하기 위해 지속적으로 발전합니다. 특히 중요한 업데이트를 신속하게 적용하는 것이 필수적입니다. 타임라인 및 의무 사항은 업데이트 정책을 참조하세요.

최신 버전 확인하기

각 플랫폼의 현재 버전을 해당 릴리스 노트에서 확인하세요:

• Android 릴리스 노트
• iOS 릴리스 노트
• Flutter 릴리스 노트
• Web — Journeys SDK 릴리스 노트

업데이트 전략

SDK와 다른 구성 요소를 동시에 업데이트하지 않기

애플리케이션은 Unico SDK와 함께 여러 라이브러리를 로드할 가능성이 높습니다. 여러 종속성을 동시에 업그레이드하면 오류의 근본 원인을 파악하기 어렵습니다. SDK를 독립적으로 업데이트하고, 다른 변경 사항과 결합하기 전에 스테이징 환경에서 검증하세요.

SDK 업데이트 지원 받기

업데이트 문제에 대한 지원 티켓을 열 때 다음을 포함하세요:

• SDK 언어 및 구현 유형 (네이티브 또는 하이브리드)
• 사용된 프레임워크
• 현재 버전 및 목표 버전
• API Key
• 변경 사항 설명 및 재현 단계
• 결과, 오류, 로그, 스크린샷 또는 동영상

JWT 보안

JWT 객체를 조작하지 않기

암호화된 JWT를 열거나 수정하지 마세요

성공적인 캡처 후 반환된 JWT는 암호화되어 있습니다. 열거나, 파싱하거나, 직렬화하지 마세요. 내부 구조는 예고 없이 변경될 수 있습니다. Unico의 API에 이미지를 제출할 때만 사용하세요.

이미지 미리보기의 경우, JWT 자체를 디코딩하지 말고 JWT와 함께 제공된 Base64 속성을 사용하세요.

JWT를 10분 이내에 전송하기

경고

보안상의 이유로, JWT는 캡처 후 10분 이내에 Unico의 백엔드로 전송되어야 합니다. 이 시간 이후에 제출된 패키지는 무효화됩니다.

JWT를 한 번만 전송하기

경고

JWT는 한 번만 제출되어야 합니다. 제출 중 오류가 발생하면 새로운 생체 인식 캡처를 수행해야 합니다 — 동일한 JWT를 재사용하지 마세요.

테스트 지침

가상화 또는 에뮬레이터 사용 금지

가상 머신이나 에뮬레이터에서 SDK를 실행하면 보안 오류 코드(73006, 73600, 73400)가 발생합니다. 오류를 잘못 식별하거나 불필요한 재작업을 피하기 위해 항상 물리적 장치에서 테스트하세요.

웹 캡처 중 DevTools를 열어두지 않기

Web SDK는 열린 DevTools를 잠재적인 사기 신호로 감지하여 제출을 무효화합니다. 엔드-투-엔드 캡처 테스트를 실행하기 전에 DevTools를 닫으세요.

Unico의 스테이징 환경에서 테스트 수행하기

프로덕션으로 이동하기 전에 현실적인 시나리오로 Unico의 스테이징 환경에서 철저한 테스트를 실행하세요. 스테이징 전용 API Key와 구성을 사용하세요 — 테스트에서 프로덕션 자격 증명을 절대 사용하지 마세요.

IDCloud의 스테이징 환경(UAT)은 프로덕션과 동일한 보안 기준을 적용합니다. 아래 지침은 그 이유와 중단 없이 테스트하는 방법을 설명합니다.

스테이징에서 변경된 사항

이전 — 감지했지만 거부하지 않음 실제 사용 패턴을 벗어난 조건은 식별되었지만 캡처를 막지는 않았습니다.

현재 — 감지하고 거부함 동일한 조건이 이제 프로덕션과 같은 엄격함으로 라이브니스 거부를 발생시킵니다.

이 제한이 존재하는 이유

충실성 — 프로덕션과의 유사성 스테이징에서 통과한 것은 프로덕션에서도 동일하게 동작해야 합니다 — 테스트에서 승인된 통합이 출시 후 예기치 않게 실패하는 것을 방지합니다.

할 수 있는 것과 할 수 없는 것

실제 사용에 가까운 조건에서 테스트하면 보안 계층이 개발에 영향을 주지 않습니다.

시장 표준이 아닌 개발 도구는 보안 검증을 유발하며, 거래가 차단될 수 있습니다.

시나리오	상태
통합의 전체 플로우 — 캡처, 전송, API 응답, 반환	✅ 가능
기능 시나리오: UI/UX, 성능, 비즈니스 오류	✅ 가능
최종 사용자의 표준 구성 기기	✅ 가능
백엔드, API, 데이터 처리와의 통합	✅ 가능
루팅/탈옥된 기기	❌ 불가
디버그 모드 / USB 디버깅 활성화	❌ 불가
에뮬레이터 또는 가상화	❌ 불가
가상 카메라 또는 캡처 자동화 도구	❌ 불가
연결을 변경하는 도구	❌ 불가
기업 MDM 또는 기기의 활성 모니터링	❌ 불가
컨테이너나 가상 머신의 샌드박스	❌ 불가

이러한 조건 중 하나라도 라이브니스 거부를 발생시킬 수 있습니다.

QA 주기가 이러한 조건 중 하나에 의존합니까?

환경 구성에 대한 안내는 지원 팀에 문의하세요. 예외, 일회성 허용 또는 일시적 완화는 없습니다 — Unico는 필요하다고 판단하는 동안 스테이징을 프로덕션과 동일하게 유지합니다.

플랫폼별 지침

Flutter: Unico의 Flutter 플러그인 사용하기

Flutter 애플리케이션 내에서 네이티브 Android 또는 iOS SDK를 브리지하려고 시도하지 마세요. 네이티브 브리지는 자주 매핑되지 않은 오류를 발생시킵니다. 항상 Unico의 전용 Flutter 플러그인을 사용하세요.

Web: 버전 업데이트 시 오래된 리소스 파일 삭제하기

Web SDK를 업그레이드할 때 새 파일을 삽입하기 전에 public 폴더에서 오래된 리소스 파일을 삭제하세요. 동일한 이름의 파일은 자동으로 덮어쓰이지 않으며 버전 충돌을 일으킬 수 있습니다.

모바일: 새 버전 빌드 전 캐시 지우기

이전 SDK 버전의 빌드 아티팩트는 업데이트 후 종속성 오류를 일으킬 수 있습니다. 새 버전을 빌드하기 전에:

• Flutter: pubspec.lock을 삭제하고 flutter pub get을 실행하세요
• iOS: pod cache clean --all 및 pod install을 실행하세요
• Android: ./gradlew clean을 실행하세요

난독화 설정

난독화 구성에서 Unico SDK 코드를 제외하세요. SDK를 난독화하면 디버그 빌드에서는 나타나지 않는 릴리스 빌드 오류가 자주 발생합니다. 필요한 keep 규칙에 대해서는 플랫폼별 문서를 참조하세요.

UX 및 성능

준비 및 카메라 열기 흐름을 두 단계로 분리하기

SDK 흐름을 두 개의 별개 단계로 구조화하세요:

1. 준비 — 페이지가 로드되는 동안 SDK를 초기화합니다 (사용자 상호작용 전).
2. 열기 — 사용자가 명시적으로 동작을 트리거할 때만 카메라를 실행합니다.

미리 SDK를 준비하면 인지되는 지연 시간이 줄어들고 사용자 경험이 크게 향상됩니다.

프로덕션 출시

프로덕션 출시를 위한 안전한 체크리스트 작성하기

프로덕션에 배포하기 전에 다음을 확인하세요:

• 프로덕션 API Key 및 환경 구성이 올바른지 확인
• 롤백 계획이 정의되고 테스트되었는지 확인
• 로그 수집 프로토콜이 준비되어 있는지 확인
• 오류 처리를 위한 지원 티켓 절차가 문서화되어 있는지 확인
• 모든 검증이 스테이징 환경에서 통과되었는지 확인