Android Setup Guide

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

At a Glance

Extract the downloaded package (unveily-sdk-{plan}-vX.X.X.zip) — it's a complete Android Studio project ready to open.

unveily-sdk-pro/
├── app/
│   ├── build.gradle.kts          ← App ID, social login keys
│   ├── google-services.json      ← Firebase config (replace required)
│   └── src/
│       ├── main/
│       │   ├── AndroidManifest.xml            ← Permissions (feature perms commented out)
│       │   ├── assets/
│       │   │   ├── config.json                ← Feature ON/OFF
│       │   │   └── config/
│       │   │       └── social_login_config.json
│       │   └── java/.../MainActivity.kt       ← Web URL setting
│       ├── debug/assets/license.key           ← Dev license key (replace required)
│       └── release/assets/license.key         ← Production license key (replace required)
└── libs/
    └── core_bridge_ip.aar        ← SDK binary (do not modify)

Mission 1 — Install License Key

Download the license key file from Dashboard → Downloads and place it here. The SDK reads assets/license.key from the source set matching the build type:

# Development builds (debug key)
app/src/debug/assets/license.key

# Release builds (production key)
app/src/release/assets/license.key

On first launch, the SDK automatically migrates the key to AndroidKeyStore encrypted storage. After that, it no longer reads the file directly.

Mission 2 — Firebase Setup

app/google-services.json   ← Replace

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

Mission 3 — App ID & Web URL

`app/build.gradle.kts`

defaultConfig {
    applicationId = "com.yourcompany.yourapp"  // ★ Change this
    // ...
}

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

private val TRUSTED_WEB_URL = "https://your.domain.com"  // ★ Change this

If TRUSTED_WEB_URL is left as the placeholder value (https://your.customer.web.url), the app will throw an error immediately on launch.

Set deep link and PG callback schemes in build.gradle.kts:

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

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

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

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.

`assets/config/social_login_config.json`

Enter keys only for the providers you use. Unconfigured providers return SDK_NOT_CONFIGURED — the app continues to work normally.

{
  "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 are configured in google-services.json + Firebase Console only.

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

Kakao and Meta require URL schemes in the Manifest — set them in build.gradle.kts:

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

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

Create product IDs in Google Play Console. 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 purchaseToken to your web app. The web app forwards that token 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.

Permissions (AndroidManifest)

AndroidManifest.xml ships with feature permissions commented out. Uncomment only the ones that match the bridge features you actually use. Leave permissions you don't use commented out — for example, if you declare the location permission but never actually collect location, Google Play's automated scan still judges "location collection possible." If that conflicts with your Data Safety form ("not collected"), the app can be rejected as Data Safety form incorrect. (The fix is to remove the unused permission, not to declare "collected" on the form.)

Permissions active by default: INTERNET, POST_NOTIFICATIONS, VIBRATE.

Permissions that ship commented out — uncomment as needed:

Bridge feature	Required permission
QR scan · Camera/Gallery	`CAMERA`
Speech-to-text (STT) · Microphone	`RECORD_AUDIO`, `MODIFY_AUDIO_SETTINGS`
Location	`ACCESS_FINE_LOCATION`, `ACCESS_COARSE_LOCATION`
Biometric auth	`USE_BIOMETRIC`, `USE_FINGERPRINT`

<!-- Uncomment if you use the camera / QR -->
<!-- <uses-permission android:name="android.permission.CAMERA" /> -->

<!-- Uncomment if you use the microphone / STT -->
<!-- <uses-permission android:name="android.permission.RECORD_AUDIO" /> -->

<!-- Uncomment if you use location -->
<!-- <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" /> -->
<!-- <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" /> -->

<!-- Uncomment if you use biometric auth -->
<!-- <uses-permission android:name="android.permission.USE_BIOMETRIC" /> -->
<!-- <uses-permission android:name="android.permission.USE_FINGERPRINT" /> -->

The minimum supported Android version is API 24 (Android 7.0).

Final Check

- [ ] applicationId → changed to your own package name
- [ ] TRUSTED_WEB_URL → changed to production domain (HTTPS)
- [ ] license.key → replaced with file downloaded from Dashboard
- [ ] google-services.json → replaced with production Firebase project file
- [ ] config.json → required features enabled
- [ ] Signed with release build: ./gradlew :app:bundleProRelease

If using Google Play App Signing: Google re-signs your app, so you must register the Google re-signing certificate SHA-256 (not your upload keystore SHA-256) in the Dashboard. Play Console → App → App Integrity → App signing certificate SHA-256 fingerprint.