스플래시 커스터마이징

config.json 하나로 스플래시 모드·배경·레이어 애니메이션을 완전히 제어합니다.

3가지 모드

config.json의 splash.mode로 스플래시 동작 방식을 결정합니다.

mode	동작
`"builtin"` (기본)	SDK 내장 스플래시 — 배경·레이어 엔진을 config만으로 커스터마이즈
`"custom"`	SDK UI 숨김. 앱이 자체 런치 화면을 제공하고, `SdkInitState.onReady`로 초기화 완료를 수신
`"none"`	스플래시 없이 즉시 메인 진입. SDK 초기화는 백그라운드에서 진행

builtin 모드 — 레이어 엔진

최소 설정 (기존 방식 호환)

{
  "splash": {
    "backgroundColor": "#FFFFFF",
    "darkBackgroundColor": "#000000",
    "minDurationMs": 1500
  }
}

기존 config를 그대로 사용하면 splash_logo 이미지가 중앙에 표시됩니다. 변경 사항 없음.

배경 이미지

backgroundImage를 설정하면 단색 배경 대신 이미지가 꽉 채워(fill) 표시됩니다.

{
  "splash": {
    "backgroundImage": {
      "light": "splash_bg_light.png",
      "dark":  "splash_bg_dark.png"
    },
    "minDurationMs": 1500
  }
}

이미지는 Android의 경우 assets/, iOS의 경우 Asset Catalog 또는 번들 파일에 배치합니다.
라이트/다크 중 한쪽만 지정해도 됩니다. 미지정 쪽은 반대편 이미지로 자동 대체됩니다.
이미지가 있으면 backgroundColor는 무시됩니다.

레이어 엔진 (`layers[]`)

여러 이미지를 시차를 두고 차례로 나타내는 멀티레이어 입장 애니메이션입니다.

{
  "splash": {
    "mode": "builtin",
    "backgroundImage": {
      "light": "splash_bg_light.png",
      "dark":  "splash_bg_dark.png"
    },
    "layers": [
      {
        "image": "splash_character.png",
        "scaleType": "fill",
        "appearAtMs": 0,
        "anim": "fade",
        "durationMs": 500
      },
      {
        "image": { "light": "splash_logo_light.png", "dark": "splash_logo_dark.png" },
        "scaleType": "fill",
        "appearAtMs": 700,
        "anim": "fadeUp",
        "durationMs": 500,
        "endsSplash": true
      }
    ],
    "minDurationMs": 2000
  }
}

레이어 필드 레퍼런스

필드	타입	기본값	설명
`image`	`string \| { light, dark }`	—	이미지 파일명. 단일 문자열 또는 라이트/다크 객체
`scaleType`	`"fill" \| "fit" \| "center"`	`"fill"`	이미지 스케일 방식
`appearAtMs`	`number`	`0`	스플래시 시작 후 이 레이어가 나타나기까지의 딜레이(ms)
`anim`	`"fade" \| "fadeUp" \| "fadeDown" \| "scale" \| "none"`	`"fade"`	등장 애니메이션
`durationMs`	`number`	`400`	애니메이션 지속 시간(ms)
`endsSplash`	`boolean`	`false`	`true`면 이 레이어 애니메이션 완료 후 종료 게이트 오픈

`scaleType` 상세

값	Android	iOS	용도
`"fill"` (기본)	`CENTER_CROP`	`.scaleAspectFill`	배경과 동일 캔버스로 디자인된 풀블리드 레이어
`"fit"`	`FIT_CENTER`	`.scaleAspectFit`	작은 아이콘/로고 — 전체 이미지 보임, 여백 발생
`"center"`	`CENTER`	`.center`	원본 크기 중앙 배치, 스케일 없음

배경(backgroundImage)과 레이어를 **동일한 캔버스 크기(예: 1080×2400)**로 디자인하면 scaleType: "fill"로 모든 기기 비율에서 정확히 겹칩니다. 배경도 fill이므로 상하가 같은 비율로 크롭됩니다.

종료 타이밍

스플래시는 아래 세 조건 중 가장 늦게 충족되는 시점에 종료됩니다:

endsSplash: true 레이어의 애니메이션 완료 (appearAtMs + durationMs)
minDurationMs 경과
SDK 초기화(라이선스 확인 + 원격 설정) 완료

endsSplash 레이어가 없으면 조건 1은 건너뜁니다.

Reduce Motion 자동 지원

Android의 animatorDurationScale = 0 또는 iOS의 접근성 모션 줄이기 옵션이 켜져 있으면 레이어 애니메이션이 자동으로 생략되고 최종 상태가 즉시 적용됩니다. 별도 코드 없이 WCAG 2.1 §2.3.3을 자동 준수합니다.

흰 깜빡임 방지 (`carryOverBackground`)

스플래시 종료 후 첫 웹 페이지 렌더링 전까지 배경이 흰색으로 잠깐 보이는 현상을 방지합니다.

기본값 true이므로 backgroundColor를 설정하면 별도 설정 없이 자동 적용됩니다. 원하지 않을 경우에만 비활성화합니다.

{
  "splash": {
    "backgroundColor": "#1A1A2E",
    "carryOverBackground": false
  }
}

carryOverBackground는 mode: "builtin"에서만 동작합니다. custom/none 모드는 앱이 직접 배경을 관리합니다.

custom 모드

SDK가 스플래시 UI를 그리지 않고, 앱이 직접 런치 화면을 제공합니다.

{
  "splash": { "mode": "custom" }
}

SDK 초기화(라이선스 확인) 완료 시점을 수신하려면 SdkInitState를 사용합니다.

Android (Kotlin):

class MyCustomSplashActivity : SplashActivity() {
    override fun onSplashStart() {
        showMySplash()                          // 자체 스플래시 표시
        SdkInitState.onReady { isLicensed ->
            hideMySplash()
            onCustomTaskDone()                  // SplashActivity에 완료 신호
        }
    }
}

iOS (Swift):

SdkInitState.shared.onReady { isLicensed in
    DispatchQueue.main.async {
        self.hideMySplash()
        self.proceedToMain()
    }
}

onCustomTaskDone()(Android) 또는 proceedToMain()(iOS)를 반드시 호출해야 스플래시가 종료됩니다. 미호출 시 앱이 스플래시 화면에서 멈춥니다.

none 모드

스플래시 화면 없이 앱이 즉시 실행됩니다. SDK 초기화는 백그라운드에서 진행됩니다.

{
  "splash": { "mode": "none" }
}

초기화 완료 후 작업이 필요하면 SdkInitState.onReady를 등록합니다.

none 모드에서는 minDurationMs가 무시됩니다.

디자인 가이드

풀블리드 캔버스 레이아웃

레이어를 배경과 동일 캔버스로 제작하면 모든 기기에서 정확히 정렬됩니다.

캔버스 크기 예: 1080 × 2400 (Android) / 1290 × 2796 (iPhone 15 Pro)
┌─────────────────────┐
│ ← 상단 안전 영역 →  │  크롭될 수 있음
│                     │
│   ★ 주요 요소 배치  │  ← 중앙 60–70% 안에 배치
│   (캐릭터, 로고)    │
│                     │
│ ← 하단 안전 영역 →  │  크롭될 수 있음
└─────────────────────┘

scaleType: "fill"은 배경과 레이어를 동일하게 크롭하므로 주요 요소를 캔버스 세로 중앙 안전 영역에 배치하면 어떤 기기에서도 잘리지 않습니다.

이미지 파일 형식 권장

플랫폼	권장 형식
Android	`.png` / `.webp` (assets/ 폴더)
iOS	Asset Catalog (`.imageset`) 또는 번들 `.png`

완전한 config.json 예시

{
  "splash": {
    "mode": "builtin",
    "backgroundColor": "#FFFFFF",
    "darkBackgroundColor": "#000000",
    "backgroundImage": {
      "light": "splash_bg_light.png",
      "dark":  "splash_bg_dark.png"
    },
    "layers": [
      {
        "image": "splash_character.png",
        "scaleType": "fill",
        "appearAtMs": 0,
        "anim": "fade",
        "durationMs": 500
      },
      {
        "image": {
          "light": "splash_logo_dark.png",
          "dark":  "splash_logo_light.png"
        },
        "scaleType": "fill",
        "appearAtMs": 700,
        "anim": "fadeUp",
        "durationMs": 500,
        "endsSplash": true
      }
    ],
    "minDurationMs": 2000,
    "carryOverBackground": true
  }
}