iOS Setup Guide

Integrate the Unveily iOS SDK into your Xcode project and prepare for production deployment.

At a Glance

Extract the downloaded package (unveily-sdk-ios-{plan}-vX.X.X.zip) — it contains a XcodeGen-based project structure.

unveily-sdk-ios-pro/
├── project.yml                        ← Xcode project config (main subscriber settings file)
├── Frameworks/
│   └── UnveilyCore.xcframework       ← SDK binary (do not modify)
└── UnveilyApp/
    ├── App/
    │   ├── Info.plist                 ← Permissions, URL schemes
    │   ├── UnveilyApp.entitlements    ← Apple Sign-In, APNs
    │   └── GoogleService-Info.plist.template  ← Firebase config (replace required)
    ├── Bridges/                       ← Swift bridge handlers (modifiable)
    ├── Controllers/
    │   └── MainViewController.swift
    ├── Views/
    ├── Resources/
    │   ├── config.json                ← Feature ON/OFF
    │   └── social_login_config.json   ← Social login SDK keys
    └── Supporting/
        └── license.key                ← License key (replace required)

Before You Begin — Install XcodeGen

The SDK uses project.yml as its project definition. You need XcodeGen to generate the .xcodeproj file.

brew install xcodegen

Then run in the SDK folder:

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

Mission 1 — Install License Key

Download the license key file from Dashboard → Downloads and place it here:

UnveilyApp/Supporting/license.key

On first launch, the SDK automatically migrates the key to iOS Keychain. After that, it no longer reads the bundle file.

Mission 2 — Firebase Setup

UnveilyApp/App/GoogleService-Info.plist.template → replace with GoogleService-Info.plist

Feature	Firebase Setup
Google Sign-In	Authentication → Enable Google
Apple Sign-In	Authentication → Enable Apple + Enter Apple Developer Keys
Push Notifications (APNs)	Cloud Messaging → Upload APNs Auth Key

Apple Sign-In on iOS uses the native ASAuthorizationController. Enable the Apple provider in Firebase Console and enter the Service ID and Key from Apple Developer.

Mission 3 — Bundle ID & Web URL

Set your app identifier and web URL in project.yml.

targets:
  UnveilyPro:        # Basic → UnveilyBasic, Standard → UnveilyStandard
    settings:
      base:
        PRODUCT_BUNDLE_IDENTIFIER: com.yourcompany.yourapp  # ★ Change this
        DEVELOPMENT_TEAM: "XXXXXXXXXX"                       # ★ Your Apple Developer Team ID
        DEEP_LINK_SCHEME: yourapp                            # ★ Deep link scheme
        PG_CALLBACK_SCHEME: yourapp-pg                       # ★ PG callback scheme
    info:
      properties:
        UnveilyInitialURL: "https://your.domain.com"         # ★ Change this

If UnveilyInitialURL is empty, the app will load the bundled test page. Make sure to set your production domain before shipping.

Regenerate the Xcode project after making changes:

xcodegen generate

Mission 4 — Enable Features (`config.json`)

Toggle features on and off in 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
  }
}

The socialLogin values control button visibility. Actual SDK keys are configured separately in social_login_config.json. For financial, healthcare, and payment apps, set all three security options to true.

For splash background images and layer animations, see the Splash Customization guide.

Info.plist — Usage Descriptions

iOS prompts the user for permission the first time a feature is used. Info.plist ships with the keys below — edit each description string to match your app. Keys for features you don't use can be left as-is, but if the key for a feature you do use is missing, calling that API will crash the app.

Feature	Info.plist key
Camera · QR scan	`NSCameraUsageDescription`
Photo library (pick photos)	`NSPhotoLibraryUsageDescription`
Save photos	`NSPhotoLibraryAddUsageDescription`
Microphone	`NSMicrophoneUsageDescription`
Speech-to-text (STT)	`NSSpeechRecognitionUsageDescription`
Location	`NSLocationWhenInUseUsageDescription`
Biometric auth (Face ID)	`NSFaceIDUsageDescription`

<key>NSCameraUsageDescription</key>
<string>Used to scan QR codes and take photos.</string>
<key>NSFaceIDUsageDescription</key>
<string>Used for secure sign-in with Face ID.</string>
<key>NSLocationWhenInUseUsageDescription</key>
<string>Used to provide nearby information.</string>
<key>NSMicrophoneUsageDescription</key>
<string>Used for voice input.</string>
<key>NSSpeechRecognitionUsageDescription</key>
<string>Used to convert your speech to text.</string>
<key>NSPhotoLibraryUsageDescription</key>
<string>Used to let you pick photos.</string>
<key>NSPhotoLibraryAddUsageDescription</key>
<string>Used to save images to your photo library.</string>

`Resources/social_login_config.json`

Enter keys only for the providers you use. Providers with empty keys are automatically disabled.

{
  "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 is configured via GoogleService-Info.plist. Apple uses Firebase Console + Apple Developer only.

Current iOS coverage: On iOS, only Apple and Google sign-in work today. You can turn on the display flags for kakao, naver, line, and meta in config.json, but calling them on the current iOS build returns an SDK_NOT_READY error (their native SDKs arrive in a future iOS update). Android supports all providers today.

Replace the following placeholders in Info.plist with your actual values:

<!-- Google: REVERSED_CLIENT_ID from your GoogleService-Info.plist -->
<string>REPLACE_WITH_GOOGLE_REVERSED_CLIENT_ID</string>

<!-- Kakao: kakao{NATIVE_APP_KEY} format (e.g. kakao1a2b3c4d5e) -->
<string>REPLACE_WITH_KAKAO_SCHEME</string>

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

Also replace the Facebook App ID and Client Token:

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

Naver login has no official SPM package. CocoaPods is required:

pod 'naveridlogin-sdk-ios'

Apple Sign-In (com.apple.developer.applesignin) and APNs (aps-environment) are already set in the entitlements file. Before production deployment, change aps-environment to production:

<key>aps-environment</key>
<string>production</string>   <!-- development for local builds -->

Mission 6 — In-App Purchase Setup (Pro Plan)

Create product IDs in App Store Connect. Query them via the JS bridge:

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

Server-side verification flow (Model B): When a purchase completes, the SDK hands the StoreKit 2 signedTransaction (JWS) to your web app. The web app forwards that JWS to your own backend, and your backend calls the Unveily verify API. The SDK and Unveily never call the verify endpoint on their own — your backend is always the party that initiates verification.

SECURE Storage

Starting with v1.0.0, a Keychain-based encrypted storage tier is available. Store sensitive data such as tokens and sessions using SECURE.

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

// Load (async only)
window.unveilyBridge.loadSecureData("access_token", "onTokenLoaded");

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

loadData(key, "SECURE") always returns an empty value. Always use the async loadSecureData(key, callback) method instead.

Final Check

- [ ] XcodeGen installed (brew install xcodegen)
- [ ] PRODUCT_BUNDLE_IDENTIFIER → changed to your own Bundle ID
- [ ] DEVELOPMENT_TEAM → Apple Developer Team ID entered
- [ ] UnveilyInitialURL → changed to production domain (HTTPS)
- [ ] xcodegen generate → project regenerated
- [ ] license.key → replaced with file downloaded from Dashboard
- [ ] GoogleService-Info.plist → replaced with production Firebase project file (remove .template)
- [ ] Info.plist → social login placeholders replaced with actual values
- [ ] entitlements → aps-environment changed to production
- [ ] config.json → required features enabled
- [ ] Xcode → Product → Archive → Upload to App Store Connect
- [ ] App Store Connect → Confirm app signing certificate SHA-256, then register in Dashboard

The app signing hash registered in the Dashboard must be the App Store Connect distribution certificate SHA-256 — not your local development certificate.