> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ones1ght.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SDK 마이그레이션 가이드

> OneS1ght iOS SDK 버전을 올릴 때 코드를 어떻게 고치는지 안내합니다. 저장소 주소 변경과 판별 규칙을 포함합니다.

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

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

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

## 두 가지를 나눠 둡니다

|              | 무엇                            | 어디에                                                                                                                       |
| ------------ | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| **변경 이력**    | 각 판에 무엇이 추가·수정됐는지 — 사람이 읽는 요약 | [릴리즈 노트](/sdk/release-note/ios) · [CHANGELOG.md](https://github.com/onecheck-inc/OneS1ght-iOS-SDK/blob/main/CHANGELOG.md) |
| **업그레이드 지침** | 버전을 올릴 때 **코드를 어떻게 고치나**      | [`Migrations/ios.json`](https://github.com/onecheck-inc/OneS1ght-iOS-SDK/blob/main/Migrations/ios.json)                   |

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

## 버전 규칙

[유의적 버전](https://semver.org/lang/ko/)을 따릅니다.

<Warning>
  **`0.x` 동안은 마이너 판올림에도 깨지는 변경이 들어갈 수 있습니다.**
  그때는 변경 이력에 **Breaking** 으로 표시하고, 업그레이드 지침에 고치는 방법을 함께 싣습니다.

  `from: "0.1.0"` 처럼 `Up to Next Major Version` 으로 고정해 두면 `0.x` 안에서는 자동으로
  올라갑니다 — 판올림 전에 이 페이지를 확인하세요.
</Warning>

## 저장소 주소 옮기기

<Tabs>
  <Tab title="Package.swift">
    URL 과 **`package:` 식별자를 함께** 고칩니다.

    ```swift theme={null}
    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"),
        ])
    ]
    ```

    <Warning>
      **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`)** 입니다.
    </Warning>
  </Tab>

  <Tab title="Xcode 프로젝트">
    <Steps>
      <Step title="옛 의존성 제거">
        프로젝트 설정 → **Package Dependencies** 에서 `onesight-mobile-swift` 를 선택하고 **\[−]** 로 지웁니다.
      </Step>

      <Step title="새 주소로 추가">
        **\[+]** → 아래 주소를 입력하고 추가합니다.

        ```
        https://github.com/onecheck-inc/OneS1ght-iOS-SDK
        ```
      </Step>

      <Step title="타깃에 라이브러리 다시 붙이기">
        앱 타깃의 **Frameworks, Libraries, and Embedded Content** 에 `OneS1ght` 가 들어 있는지 확인합니다.
      </Step>

      <Step title="Package.resolved 정리">
        `File → Packages → Reset Package Caches` 후 빌드합니다.
      </Step>
    </Steps>
  </Tab>
</Tabs>

## 업그레이드하는 법

<Tabs>
  <Tab title="코딩 에이전트에게 맡기기">
    [MCP 를 연결](/sdk/mcp)했다면 그냥 물어보면 됩니다.

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

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

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

  <Tab title="직접 하기">
    <Steps>
      <Step title="변경 이력 확인">
        [릴리즈 노트](/sdk/release-note/ios)에서 지금 쓰는 버전과 올리려는 버전 사이를 읽습니다.
      </Step>

      <Step title="업그레이드 지침 확인">
        [`Migrations/ios.json`](https://github.com/onecheck-inc/OneS1ght-iOS-SDK/blob/main/Migrations/ios.json) 의
        `migrations` 배열에서 해당 구간을 찾습니다.

        ⚠️ **칸을 건너뛰지 마세요.** `0.1.0` 에서 `0.3.0` 으로 한 번에 뛰면 중간 판의 변경이
        통째로 누락됩니다. 순서대로 밟으세요.
      </Step>

      <Step title="의존성 갱신">
        Xcode 에서 **File → Packages → Update to Latest Package Versions**.
      </Step>

      <Step title="확인">
        빌드가 통과하면 앱을 한 번 실행해 로그를 봅니다 —
        `I1001 → I1002 → I3001 → I4001` 이 순서대로 찍히면 정상입니다
        ([트러블슈팅](/sdk/integration/ios/trouble-shooting)).
      </Step>
    </Steps>
  </Tab>
</Tabs>

## 버전별 조치 요약

| 버전         | 코드 수정        | 조치                                                                                           |
| ---------- | ------------ | -------------------------------------------------------------------------------------------- |
| **0.1.12** | **필요**       | `onDebugLog`·`onLog` 클로저 인자가 둘로 늘었습니다 ([아래](#0-1-12-로그에-등급이-생겼습니다))                          |
| **0.1.11** | 없음           | 의존성 갱신만. 앱에 자체 언어 설정이 있다면 `setLanguage(_:)` 로 알려주세요                                          |
| **0.1.10** | 없음           | 의존성 갱신만                                                                                      |
| **0.1.9**  | **필요할 수 있음** | `initialize` 의 성공을 "측위 가능" 으로 읽고 있었다면 고쳐야 합니다 ([아래](#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**  | 없음           | 의존성 갱신만                                                                                      |

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

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

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

<CodeGroup>
  ```swift 전 (~0.1.11) theme={null}
  OneS1ght.onDebugLog = { line in
      print("[OneS1ght] \(line)")
  }
  ```

  ```swift 후 (0.1.12~) theme={null}
  OneS1ght.onDebugLog = { level, line in
      print("[OneS1ght][\(level)] \(line)")
  }
  ```
</CodeGroup>

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

<CodeGroup>
  ```swift 전 theme={null}
  let isError = line.hasPrefix("⚠️")
  ```

  ```swift 후 theme={null}
  let isError = level == .error
  ```
</CodeGroup>

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

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

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

<CodeGroup>
  ```swift 전 (~0.1.8) theme={null}
  do {
      try await OneS1ght.initialize(sdkKey: key)
  } catch SdkError.deviceNotSupported {
      showUnsupportedScreen()      // 이제 여기로 오지 않습니다
  }
  ```

  ```swift 후 (0.1.9~) theme={null}
  try await OneS1ght.initialize(sdkKey: key)

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

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

## 자주 걸리는 것

<AccordionGroup>
  <Accordion title="unknown package 'onesight-mobile-swift'">
    저장소 주소만 바꾸고 `.product(name:package:)` 의 `package:` 를 그대로 둔 경우입니다.
    `package: "OneS1ght-iOS-SDK"` 로 고치세요.
  </Accordion>

  <Accordion title="unknown package 'OneS1ght'">
    `package:` 에 **모듈 이름**을 넣은 경우입니다. SPM 이 요구하는 값은 **저장소 이름**입니다 —
    `package: "OneS1ght-iOS-SDK"`.
  </Accordion>

  <Accordion title="판올림 후 초기화가 실패한다">
    `onDebugLog` 를 `initialize` 앞에 붙이고 코드를 확인하세요.
    `E5005`(응답 해석 실패)라면 SDK·서버 버전 불일치입니다 — 최신 판으로 올리세요.
  </Accordion>

  <Accordion title="Package.resolved 충돌">
    `File → Packages → Reset Package Caches` 후 다시 해석합니다.
    팀 저장소라면 `Package.resolved` 를 커밋해 전원이 같은 판을 받게 하세요.
  </Accordion>
</AccordionGroup>

## 관련 문서

<CardGroup cols={2}>
  <Card title="릴리즈 노트" icon="tag" href="/sdk/release-note/ios">
    각 판에 무엇이 바뀌었나.
  </Card>

  <Card title="코딩 에이전트 (MCP)" icon="robot" href="/sdk/mcp">
    업그레이드를 에이전트에게 맡기려면.
  </Card>
</CardGroup>