SDK 마이그레이션 가이드

2026-08-21, 저장소 주소가 바뀌었습니다.

onecheck-inc/onesight-mobile-swift  →  onecheck-inc/OneS1ght-iOS-SDK

옛 주소는 GitHub 이 리다이렉트해 주므로 당장 깨지지는 않습니다. 다만 그 이름으로 누가 새 저장소를 만들면 리다이렉트가 끊기므로, 지금 옮겨 두시는 편이 안전합니다. → 아래 절차

두 가지를 나눠 둡니다

	무엇	어디에
변경 이력	각 판에 무엇이 추가·수정됐는지 — 사람이 읽는 요약	릴리즈 노트 · CHANGELOG.md
업그레이드 지침	버전을 올릴 때 코드를 어떻게 고치나	`Migrations/ios.json`

업그레이드 지침을 따로 두는 이유는 읽는 쪽이 사람이 아니기 때문입니다. 코딩 에이전트(MCP)가 이 파일을 받아 여러분의 코드를 직접 고칩니다. 그래서 “무엇이 바뀌었나”가 아니라 “이 코드를 이렇게 바꿔라” 형태로 쓰여 있습니다.

버전 규칙

유의적 버전을 따릅니다.

0.x 동안은 마이너 판올림에도 깨지는 변경이 들어갈 수 있습니다. 그때는 변경 이력에 Breaking 으로 표시하고, 업그레이드 지침에 고치는 방법을 함께 싣습니다.from: "0.1.0" 처럼 Up to Next Major Version 으로 고정해 두면 0.x 안에서는 자동으로 올라갑니다 — 판올림 전에 이 페이지를 확인하세요.

저장소 주소 옮기기

Package.swift
Xcode 프로젝트

URL 과 package: 식별자를 함께 고칩니다.

dependencies: [
    .package(url: "https://github.com/onecheck-inc/OneS1ght-iOS-SDK", from: "0.1.0"),
],
targets: [
    .target(name: "YourApp", dependencies: [
        .product(name: "OneS1ght", package: "OneS1ght-iOS-SDK"),
    ])
]

URL 만 고치면 빌드가 깨집니다. SPM 은 패키지 식별자를 저장소 이름에서 뽑으므로, package: 를 옛 이름으로 두면 다음 에러가 납니다.

error: unknown package 'onesight-mobile-swift' in dependencies of target 'YourApp';
       valid packages are: 'ones1ght-ios-sdk'

package: 에 들어갈 값은 모듈 이름(OneS1ght)이 아니라 저장소 이름(OneS1ght-iOS-SDK) 입니다.

옛 의존성 제거

프로젝트 설정 → Package Dependencies 에서 onesight-mobile-swift 를 선택하고 [−] 로 지웁니다.

새 주소로 추가

[+] → 아래 주소를 입력하고 추가합니다.

https://github.com/onecheck-inc/OneS1ght-iOS-SDK

타깃에 라이브러리 다시 붙이기

앱 타깃의 Frameworks, Libraries, and Embedded Content 에 OneS1ght 가 들어 있는지 확인합니다.

Package.resolved 정리

File → Packages → Reset Package Caches 후 빌드합니다.

업그레이드하는 법

코딩 에이전트에게 맡기기
직접 하기

MCP 를 연결했다면 그냥 물어보면 됩니다.

SDK를 최신 버전으로 올려 줘.

에이전트가 onesight_migrate 로 지침을 받아 버전 사이를 순서대로 밟으며 코드를 고칩니다. 깨지는 변경이 있으면 무엇을 왜 바꾸는지 함께 알려줍니다.

에이전트가 만든 변경은 반드시 검토하세요. 지침은 정확하지만, 여러분의 앱 구조에 맞추는 과정에서 에이전트가 판단을 섞습니다.

변경 이력 확인

릴리즈 노트에서 지금 쓰는 버전과 올리려는 버전 사이를 읽습니다.

업그레이드 지침 확인

Migrations/ios.json 의 migrations 배열에서 해당 구간을 찾습니다.⚠️ 칸을 건너뛰지 마세요. 0.1.0 에서 0.3.0 으로 한 번에 뛰면 중간 판의 변경이 통째로 누락됩니다. 순서대로 밟으세요.

의존성 갱신

Xcode 에서 File → Packages → Update to Latest Package Versions.

확인

빌드가 통과하면 앱을 한 번 실행해 로그를 봅니다 — I1001 → I1002 → I3001 → I4001 이 순서대로 찍히면 정상입니다 (트러블슈팅).

버전별 조치 요약

버전	코드 수정	조치
0.1.12	필요	`onDebugLog`·`onLog` 클로저 인자가 둘로 늘었습니다 (아래)
0.1.11	없음	의존성 갱신만. 앱에 자체 언어 설정이 있다면 `setLanguage(_:)` 로 알려주세요
0.1.10	없음	의존성 갱신만
0.1.9	필요할 수 있음	`initialize` 의 성공을 “측위 가능” 으로 읽고 있었다면 고쳐야 합니다 (아래)
0.1.8	없음	의존성 갱신만
0.1.7	없음	의존성 갱신만
0.1.6	없음	의존성 갱신만
0.1.5	없음	저장소 주소·`package:` 식별자 교체 (위 절차)
0.1.4	없음	의존성 갱신만. 필수 판올림 — `0.1.3` 이하는 현재 서버와 초기화되지 않습니다
0.1.3	없음	의존성 갱신만
0.1.2	없음	의존성 갱신만
0.1.1	없음	의존성 갱신만

0.1.3 이하를 쓰고 있다면 지금 올리세요. 서버가 설정 자루에 정수·불리언 값을 담기 시작하면서 옛 판은 /auth/verify 응답을 읽지 못해 initialize 가 통째로 실패합니다.

0.1.12 — 로그에 등급이 생겼습니다

onDebugLog 와 onLog 가 등급과 글자를 함께 줍니다.

OneS1ght.onDebugLog = { line in
    print("[OneS1ght] \(line)")
}

OneS1ght.onDebugLog = { level, line in
    print("[OneS1ght][\(level)] \(line)")
}

이모지로 등급을 가르던 코드가 있다면 걷어내세요. 그게 이 변경의 이유입니다 — 문구가 바뀌면 조용히 오분류됐고, 실제로 “이 층에 구역이 없다”는 정상 상태가 오류로 표시되고 있었습니다.

let isError = line.hasPrefix("⚠️")

let isError = level == .error

UwbPositioningProvider.onLog 와 note(_:) 도 같은 모양입니다. note 는 등급 없는 형태(note("...") → .log)도 그대로 씁니다.

0.1.9 — `initialize` 가 기기 미지원으로 실패하지 않습니다

UWB 칩이 없는 기기에서도 initialize 가 성공합니다. 도면·존은 받아서 그릴 수 있고, 막히는 것은 측위뿐입니다.

do {
    try await OneS1ght.initialize(sdkKey: key)
} catch SdkError.deviceNotSupported {
    showUnsupportedScreen()      // 이제 여기로 오지 않습니다
}

try await OneS1ght.initialize(sdkKey: key)

// 측위 가능 여부는 따로 묻습니다 (초기화 전에도 호출 가능, throw 없음)
if OneS1ght.deviceAvailability != .available {
    disablePositioningButton()   // 지도·구역은 그대로 보여줍니다
}

initialize 의 catch 에서 E2001·E2002 를 다루던 분기는 이제 도달하지 않습니다. 차단은 FloorSession.begin() 한 곳이 맡습니다.

자주 걸리는 것

unknown package 'onesight-mobile-swift'

저장소 주소만 바꾸고 .product(name:package:) 의 package: 를 그대로 둔 경우입니다. package: "OneS1ght-iOS-SDK" 로 고치세요.

unknown package 'OneS1ght'

package: 에 모듈 이름을 넣은 경우입니다. SPM 이 요구하는 값은 저장소 이름입니다 — package: "OneS1ght-iOS-SDK".

판올림 후 초기화가 실패한다

onDebugLog 를 initialize 앞에 붙이고 코드를 확인하세요. E5005(응답 해석 실패)라면 SDK·서버 버전 불일치입니다 — 최신 판으로 올리세요.

Package.resolved 충돌

File → Packages → Reset Package Caches 후 다시 해석합니다. 팀 저장소라면 Package.resolved 를 커밋해 전원이 같은 판을 받게 하세요.

릴리즈 노트

각 판에 무엇이 바뀌었나.

코딩 에이전트 (MCP)

업그레이드를 에이전트에게 맡기려면.

시작하기

측위 인프라 (GeoSpace)(모바일)

측위 인프라 (GeoSpace)(태그)

OneS1ght 콘솔

개발자 가이드 (SDK)

SDK 마이그레이션 가이드

두 가지를 나눠 둡니다

버전 규칙

저장소 주소 옮기기

업그레이드하는 법

버전별 조치 요약

0.1.12 — 로그에 등급이 생겼습니다

0.1.9 — `initialize` 가 기기 미지원으로 실패하지 않습니다

자주 걸리는 것

관련 문서

릴리즈 노트

코딩 에이전트 (MCP)

​두 가지를 나눠 둡니다

​버전 규칙

​저장소 주소 옮기기

​업그레이드하는 법

​버전별 조치 요약

​0.1.12 — 로그에 등급이 생겼습니다

​0.1.9 — initialize 가 기기 미지원으로 실패하지 않습니다

​자주 걸리는 것

​관련 문서

릴리즈 노트

코딩 에이전트 (MCP)

두 가지를 나눠 둡니다

버전 규칙

저장소 주소 옮기기

업그레이드하는 법

버전별 조치 요약

0.1.12 — 로그에 등급이 생겼습니다

0.1.9 — `initialize` 가 기기 미지원으로 실패하지 않습니다

자주 걸리는 것

관련 문서