Android 설정 가이드

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

한눈에 보기

다운로드한 패키지(unveily-sdk-{plan}-vX.X.X.zip)를 압축 해제하면 Android Studio에서 바로 열 수 있는 프로젝트입니다.

unveily-sdk-pro/
├── app/
│   ├── build.gradle.kts          ← 앱 ID, 소셜 키 설정
│   ├── google-services.json      ← Firebase 설정 (교체 필요)
│   └── src/
│       ├── main/
│       │   ├── AndroidManifest.xml            ← 권한 (기능 권한은 주석 처리됨)
│       │   ├── assets/
│       │   │   ├── config.json                ← 기능 ON/OFF
│       │   │   └── config/
│       │   │       └── social_login_config.json
│       │   └── java/.../MainActivity.kt       ← 웹 URL 설정
│       ├── debug/assets/license.key           ← 개발용 라이선스 키 (교체 필요)
│       └── release/assets/license.key         ← 프로덕션 라이선스 키 (교체 필요)
└── libs/
    └── core_bridge_ip.aar        ← SDK 바이너리 (수정 금지)

Mission 1 — 라이선스 키 설치

대시보드 → 다운로드 에서 라이선스 키 파일을 받아 배치합니다. SDK는 빌드 타입별 소스셋의 assets/license.key를 읽습니다.

# 개발 빌드용 (디버그 키)
app/src/debug/assets/license.key

# 릴리즈 빌드용 (프로덕션 키)
app/src/release/assets/license.key

첫 실행 시 SDK가 자동으로 AndroidKeyStore 암호화 저장소로 키를 마이그레이션합니다. 이후에는 파일 시스템을 거치지 않습니다.

Mission 2 — Firebase 설정

Firebase Console에서 Android 앱을 등록하고 google-services.json을 다운로드합니다.

app/google-services.json   ← 교체

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

Mission 3 — 앱 ID 및 웹 URL 설정

`app/build.gradle.kts`

defaultConfig {
    applicationId = "com.yourcompany.yourapp"  // ★ 변경
    // ...
}

`app/src/main/java/.../MainActivity.kt`

private val TRUSTED_WEB_URL = "https://your.domain.com"  // ★ 변경

TRUSTED_WEB_URL이 placeholder 값(https://your.customer.web.url)인 채로 빌드하면 앱 실행 시 즉시 오류가 발생합니다.

딥링크와 PG 콜백 스킴은 build.gradle.kts에서 설정합니다:

buildConfigField("String", "DEEP_LINK_SCHEME",  "\"yourapp\"")
buildConfigField("String", "PG_CALLBACK_SCHEME", "\"yourapp-pg\"")

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

app/src/main/assets/config.json에서 필요한 기능을 켜고 끕니다.

{
  "splash": {
    "mode": "builtin",
    "backgroundColor": "#FFFFFF",
    "darkBackgroundColor": "#000000",
    "minDurationMs": 1500
  },
  "modules": {
    "bottomTabs":    { "enabled": true, "autoHide": false, "barHeightDp": 60 },
    "bottomSheet":   { "enabled": true },
    "accessibility": { "enabled": false },
    "topDownMenu":   { "enabled": false },
    "sideDrawer":    { "enabled": false }
  },
  "security": {
    "screenshotProtectionEnabled": true,
    "backgroundProtectionEnabled": true,
    "rootDetectionEnabled": true
  }
}

금융·의료·결제 앱은 security 옵션 3개를 모두 true로 설정하세요.

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

Mission 5 — 소셜 로그인 설정

`assets/config/social_login_config.json`

사용할 프로바이더의 키만 입력합니다. 미설정 프로바이더는 SDK_NOT_CONFIGURED를 반환하며 앱은 정상 동작합니다.

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

Google / Apple은 google-services.json + Firebase Console에서만 설정합니다.

`app/build.gradle.kts` — Manifest Placeholders

Kakao와 Meta는 build.gradle.kts에 URL 스킴을 추가해야 합니다:

manifestPlaceholders["kakaoScheme"]                 = "kakaoYOUR_KAKAO_KEY"
manifestPlaceholders["facebookLoginProtocolScheme"] = "fbYOUR_META_APP_ID"

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

Google Play Console에서 상품 ID를 생성합니다. JS 브릿지로 조회합니다:

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

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

AndroidManifest.xml에는 기능별 권한이 주석 처리된 상태로 포함되어 있습니다. 사용하는 브릿지 기능에 해당하는 권한만 주석을 해제하세요. 쓰지 않는 권한은 반드시 주석 처리된 채로 두세요 — 예를 들어 위치 권한을 선언만 하고 실제로 위치를 수집하지 않아도, Google Play 자동 스캔은 "위치 수집 가능"으로 판정합니다. 이것이 데이터 보안 양식("수집 안 함")과 불일치하면 데이터 보안 양식 잘못됨으로 앱이 거부될 수 있습니다. (해결책은 양식에 "수집"으로 맞추는 게 아니라, 안 쓰는 권한을 빼는 것입니다.)

기본 활성화된 권한: INTERNET, POST_NOTIFICATIONS, VIBRATE.

주석 처리되어 있어 필요 시 해제하는 권한:

브릿지 기능	필요한 권한
QR 스캔 · 카메라/갤러리	`CAMERA`
음성 인식(STT) · 마이크	`RECORD_AUDIO`, `MODIFY_AUDIO_SETTINGS`
위치(location)	`ACCESS_FINE_LOCATION`, `ACCESS_COARSE_LOCATION`
생체 인증(biometric)	`USE_BIOMETRIC`, `USE_FINGERPRINT`

<!-- 카메라/QR 사용 시 주석 해제 -->
<!-- <uses-permission android:name="android.permission.CAMERA" /> -->

<!-- 마이크/STT 사용 시 주석 해제 -->
<!-- <uses-permission android:name="android.permission.RECORD_AUDIO" /> -->

<!-- 위치 사용 시 주석 해제 -->
<!-- <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" /> -->
<!-- <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" /> -->

<!-- 생체 인증 사용 시 주석 해제 -->
<!-- <uses-permission android:name="android.permission.USE_BIOMETRIC" /> -->
<!-- <uses-permission android:name="android.permission.USE_FINGERPRINT" /> -->

Android 최소 지원 버전은 API 24 (Android 7.0) 입니다.

완료 전 점검

- [ ] applicationId → 자체 패키지명으로 변경
- [ ] TRUSTED_WEB_URL → 운영 도메인으로 변경 (HTTPS)
- [ ] license.key → 대시보드에서 다운로드한 파일로 교체
- [ ] google-services.json → 운영용 Firebase 프로젝트 파일로 교체
- [ ] config.json → 필요한 기능 활성화 확인
- [ ] 릴리즈 빌드로 서명: ./gradlew :app:bundleProRelease

Google Play App Signing 사용 시: Google이 앱을 재서명하므로 업로드 키스토어 SHA-256이 아닌 Google 재서명 인증서 SHA-256을 대시보드에 등록해야 합니다. Play Console → 앱 → 앱 무결성 → 앱 서명 인증서 SHA-256 지문