iOS 설정 가이드

Unveily iOS SDK를 Xcode 프로젝트에 통합하고 운영 배포까지 준비합니다.

한눈에 보기

다운로드한 패키지(unveily-sdk-ios-{plan}-vX.X.X.zip)를 압축 해제하면 XcodeGen으로 프로젝트를 생성할 수 있는 구조입니다.

unveily-sdk-ios-pro/
├── project.yml                        ← Xcode 프로젝트 설정 (구독자 설정 핵심)
├── Frameworks/
│   └── UnveilyCore.xcframework       ← SDK 바이너리 (수정 금지)
└── UnveilyApp/
    ├── App/
    │   ├── Info.plist                 ← 권한, URL 스킴
    │   ├── UnveilyApp.entitlements    ← Apple 로그인, APNs 설정
    │   └── GoogleService-Info.plist.template  ← Firebase 설정 (교체 필요)
    ├── Bridges/                       ← Swift 브릿지 핸들러 (수정 가능)
    ├── Controllers/
    │   └── MainViewController.swift
    ├── Views/
    ├── Resources/
    │   ├── config.json                ← 기능 ON/OFF
    │   └── social_login_config.json   ← 소셜 SDK 키
    └── Supporting/
        └── license.key                ← 라이선스 키 (교체 필요)

시작 전 준비 — XcodeGen 설치

SDK는 project.yml 기반으로 동작합니다. Xcode 프로젝트(.xcodeproj)를 생성하려면 XcodeGen이 필요합니다.

brew install xcodegen

설치 후 SDK 폴더에서 실행합니다:

cd unveily-sdk-ios-pro
xcodegen generate
open *.xcodeproj

Mission 1 — 라이선스 키 설치

대시보드 → 다운로드 에서 라이선스 키 파일을 받아 배치합니다.

UnveilyApp/Supporting/license.key

첫 실행 시 SDK가 자동으로 iOS Keychain으로 키를 마이그레이션합니다. 이후에는 번들 파일을 거치지 않습니다.

Mission 2 — Firebase 설정

Firebase Console에서 iOS 앱을 등록하고 GoogleService-Info.plist를 다운로드합니다.

UnveilyApp/App/GoogleService-Info.plist.template → GoogleService-Info.plist 로 교체

기능	Firebase 설정
Google 로그인	Authentication → Google 활성화
Apple 로그인	Authentication → Apple 활성화 + Apple Developer 키 입력
푸시 알림 (APNs)	Cloud Messaging → APNs 인증 키 업로드

Apple 로그인은 iOS에서 ASAuthorizationController를 사용하는 네이티브 방식으로 동작합니다. Firebase Console에서 Apple 프로바이더를 활성화하고, Apple Developer에서 Service ID와 Key를 발급받아 입력하세요.

Mission 3 — Bundle ID 및 웹 URL 설정

project.yml에서 앱 식별자와 웹 URL을 설정합니다.

targets:
  UnveilyPro:        # Basic → UnveilyBasic, Standard → UnveilyStandard
    settings:
      base:
        PRODUCT_BUNDLE_IDENTIFIER: com.yourcompany.yourapp  # ★ 변경
        DEVELOPMENT_TEAM: "XXXXXXXXXX"                       # ★ Apple Developer Team ID
        DEEP_LINK_SCHEME: yourapp                            # ★ 딥링크 스킴
        PG_CALLBACK_SCHEME: yourapp-pg                       # ★ PG 콜백 스킴
    info:
      properties:
        UnveilyInitialURL: "https://your.domain.com"         # ★ 변경

UnveilyInitialURL이 비어 있으면 앱이 내장 테스트 페이지를 로드합니다. 운영 빌드 전에 반드시 실제 도메인으로 변경하세요.

설정 변경 후 Xcode 프로젝트를 재생성합니다:

xcodegen generate

Mission 4 — 기능 활성화 (`config.json`)

UnveilyApp/Resources/config.json에서 필요한 기능을 켜고 끕니다.

{
  "remoteConfigUrl": "",
  "debugMode": false,
  "splash": {
    "mode": "builtin",
    "backgroundColor": "#FFFFFF",
    "darkBackgroundColor": "#000000",
    "minDurationMs": 1500
  },
  "modules": {
    "accessibility": { "enabled": false },
    "topDownMenu":   { "enabled": false },
    "sideDrawer":    { "enabled": false },
    "bottomTabs":    { "enabled": true, "autoHide": false },
    "bottomSheet":   { "enabled": true }
  },
  "security": {
    "screenshotProtectionEnabled": true,
    "backgroundProtectionEnabled": true,
    "rootDetectionEnabled": true
  },
  "socialLogin": {
    "google": true,
    "apple": true,
    "kakao": false,
    "naver": false,
    "line": false,
    "meta": false
  }
}

socialLogin 값은 로그인 버튼의 표시 여부를 제어합니다. 실제 SDK 키는 social_login_config.json에서 별도로 설정합니다. 금융·의료·결제 앱은 security 옵션 3개를 모두 true로 설정하세요.

스플래시 배경 이미지·레이어 애니메이션 설정은 **스플래시 커스터마이징 가이드**를 참고하세요.

Info.plist — 권한 사용 설명 (Usage Description)

iOS는 특정 기능을 처음 사용할 때 권한 사용 목적을 사용자에게 표시합니다. Info.plist에는 아래 키가 포함되어 있으며, 사용하는 기능에 맞게 설명 문구를 앱에 맞게 수정하세요. 사용하지 않는 기능의 키는 그대로 두어도 무방하지만, 실제 사용하는 기능의 키가 없으면 해당 API 호출 시 앱이 크래시됩니다.

기능	Info.plist 키
카메라 · QR 스캔	`NSCameraUsageDescription`
갤러리(사진 선택)	`NSPhotoLibraryUsageDescription`
사진 저장	`NSPhotoLibraryAddUsageDescription`
마이크	`NSMicrophoneUsageDescription`
음성 인식(STT)	`NSSpeechRecognitionUsageDescription`
위치	`NSLocationWhenInUseUsageDescription`
생체 인증 (Face ID)	`NSFaceIDUsageDescription`

<key>NSCameraUsageDescription</key>
<string>QR 코드 스캔 및 사진 촬영에 카메라를 사용합니다.</string>
<key>NSFaceIDUsageDescription</key>
<string>안전한 로그인을 위해 Face ID를 사용합니다.</string>
<key>NSLocationWhenInUseUsageDescription</key>
<string>주변 정보를 제공하기 위해 위치를 사용합니다.</string>
<key>NSMicrophoneUsageDescription</key>
<string>음성 입력에 마이크를 사용합니다.</string>
<key>NSSpeechRecognitionUsageDescription</key>
<string>음성을 텍스트로 변환하기 위해 음성 인식을 사용합니다.</string>
<key>NSPhotoLibraryUsageDescription</key>
<string>사진을 선택하기 위해 사진 보관함에 접근합니다.</string>
<key>NSPhotoLibraryAddUsageDescription</key>
<string>이미지를 사진 보관함에 저장합니다.</string>

Mission 5 — 소셜 로그인 설정

`Resources/social_login_config.json`

사용할 프로바이더의 키만 입력합니다. 키가 비어 있으면 해당 프로바이더는 자동으로 비활성화됩니다.

{
  "kakao": { "nativeAppKey": "YOUR_KAKAO_KEY" },
  "naver": { "clientId": "YOUR_ID", "clientSecret": "YOUR_SECRET", "appName": "YOUR_APP_NAME" },
  "line":  { "channelId": "YOUR_CHANNEL_ID" },
  "meta":  { "appId": "YOUR_APP_ID", "clientToken": "YOUR_TOKEN" }
}

Google은 GoogleService-Info.plist, Apple은 Firebase Console + Apple Developer에서만 설정합니다.

iOS 현재 지원 범위: iOS에서는 Apple과 Google 로그인만 즉시 동작합니다. kakao·naver·line·meta는 config.json의 표시 플래그는 켤 수 있으나, 현재 iOS 빌드에서 호출하면 SDK_NOT_READY 오류를 반환합니다(네이티브 SDK는 향후 iOS 업데이트에서 추가 예정). Android는 모든 프로바이더를 현재 지원합니다.

`Info.plist` — 소셜 URL 스킴 교체

Info.plist에서 아래 플레이스홀더를 실제 값으로 교체합니다:

<!-- Google: GoogleService-Info.plist의 REVERSED_CLIENT_ID 값 -->
<string>REPLACE_WITH_GOOGLE_REVERSED_CLIENT_ID</string>

<!-- Kakao: kakao{NATIVE_APP_KEY} 형식 (예: kakao1a2b3c4d5e) -->
<string>REPLACE_WITH_KAKAO_SCHEME</string>

<!-- Meta: fb{FACEBOOK_APP_ID} 형식 -->
<string>REPLACE_WITH_FB_SCHEME</string>

Facebook App ID와 Client Token도 교체합니다:

<key>FacebookAppID</key>
<string>REPLACE_WITH_FB_APP_ID</string>
<key>FacebookClientToken</key>
<string>REPLACE_WITH_FB_CLIENT_TOKEN</string>

Naver 로그인은 공식 SPM 패키지가 없습니다. CocoaPods를 사용해야 합니다:

pod 'naveridlogin-sdk-ios'

`UnveilyApp.entitlements` — Apple 로그인 + APNs

Apple 로그인(com.apple.developer.applesignin)과 APNs(aps-environment)는 이미 entitlements에 설정되어 있습니다. 운영 배포 전 aps-environment를 production으로 변경합니다:

<key>aps-environment</key>
<string>production</string>   <!-- 개발 시: development -->

Mission 6 — 인앱결제 설정 (Pro 플랜)

App Store Connect에서 상품 ID를 생성합니다. JS 브릿지로 조회합니다:

window.unveilyBridge.iap.queryProducts(["your.product.id"], "inapp", "onProductsLoaded");

서버 검증 흐름 (Model B): 구매가 완료되면 SDK는 StoreKit 2의 signedTransaction(JWS)을 웹 앱으로 전달합니다. 웹 앱은 이 JWS를 고객사(귀사)의 백엔드로 전송하고, 귀사 백엔드가 Unveily 검증 API를 호출합니다. SDK나 Unveily가 직접 검증 엔드포인트를 호출하지 않습니다 — 검증 요청의 주체는 항상 귀사 백엔드입니다.

SECURE 스토리지

v1.0.0부터 Keychain 기반 암호화 저장소 티어가 추가되었습니다. 토큰, 세션 등 민감 데이터를 SECURE로 저장하세요.

// 저장
window.unveilyBridge.saveData("access_token", value, "SECURE");

// 불러오기 (비동기 전용)
window.unveilyBridge.loadSecureData("access_token", "onTokenLoaded");

// 삭제
window.unveilyBridge.removeData("access_token", "SECURE");

loadData(key, "SECURE")는 항상 빈 값을 반환합니다. 반드시 loadSecureData(key, callback) 비동기 방식을 사용하세요.

완료 전 점검

- [ ] XcodeGen 설치 완료 (brew install xcodegen)
- [ ] PRODUCT_BUNDLE_IDENTIFIER → 자체 Bundle ID로 변경
- [ ] DEVELOPMENT_TEAM → Apple Developer Team ID 입력
- [ ] UnveilyInitialURL → 운영 도메인으로 변경 (HTTPS)
- [ ] xcodegen generate → 프로젝트 재생성
- [ ] license.key → 대시보드에서 다운로드한 파일로 교체
- [ ] GoogleService-Info.plist → 운영용 Firebase 프로젝트 파일로 교체 (.template 제거)
- [ ] Info.plist → 소셜 로그인 플레이스홀더 실제 값으로 교체
- [ ] entitlements → aps-environment를 production으로 변경
- [ ] config.json → 필요한 기능 활성화 확인
- [ ] Xcode → Product → Archive → App Store Connect 업로드
- [ ] App Store Connect → 앱 서명 인증서 SHA-256 확인 후 대시보드 등록

대시보드에 등록하는 앱 서명 해시는 App Store Connect의 배포 인증서 SHA-256이어야 합니다. 로컬 개발 인증서와 다릅니다.