> ## 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.

# 모바일 데모 (2026.07.26)

> 실제 적용 전에 연습해 보는 패키지 가이드 — 키 발급부터 데모 앱 빌드, 실내 측위·쿠폰 체험까지 한 번에 따라 합니다.

<Info>
  이 문서는 **실제 서비스 적용 전에 전체 흐름을 연습**해 보기 위한 데모 가이드입니다.
  아무것도 준비되지 않은 상태를 기준으로, 키 발급 → 인프라 확인 → 앱 빌드 → 체험까지
  순서대로 안내합니다. (빌드 소요 약 5분)
</Info>

## 전체 흐름

| 단계          | 하는 일                | 데모에서는                   |
| ----------- | ------------------- | ----------------------- |
| 1. 키 준비     | SDK 키·GeoSpace 키 발급 | **담당자가 전달** (직접 발급도 가능) |
| 2. 측위 인프라   | 공간 구축·로케이터 설치       | ✅ 준비되어 있음 (데모 현장)       |
| 3. 영역(존) 생성 | 콘솔에서 이벤트 영역 등록      | 직접 해 볼 수 있음             |
| 4. 데모 앱 빌드  | 클론 → 키 입력 → 실기기 설치  | 직접 진행                   |
| 5. 체험       | 측위 → 존 진입 → 쿠폰 수신   | 직접 진행 (데모 현장)           |

***

## 1. 키 준비

데모 실행에는 키 **3종**이 필요합니다. 데모 참여자는 담당자에게 전달받는 것이 가장 빠릅니다.

| 키             | 발급 위치                                                                | 용도                          |
| ------------- | -------------------------------------------------------------------- | --------------------------- |
| `ock_sdk_...` | OneS1ght 콘솔 → **모바일 SDK 키 관리** 메뉴 ([발급 상세](/locator/sdk-keys))       | OneS1ght 서버 인증 (측위 데이터·이벤트) |
| `gsk_...`     | GeoSpace Intelligence Hub → 온보딩·설정 → **모바일** → SDK 키                 | GeoSpace 측위 데이터 접근          |
| `gpk_...`     | GeoSpace Intelligence Hub → [파트너 API](/geospace/onboarding#파트너-키-발급) | 건물·도면·존 연동                  |

<Warning>
  **OneS1ght의 SDK 키(`ock_`)와 GeoSpace의 SDK 키(`gsk_`)는 서로 다른 키입니다.**
  두 콘솔 모두 "SDK 키" 메뉴가 있어 혼동하기 쉬우니, 접두사로 구분하세요.
</Warning>

<Note>
  파트너 키(`gpk_`)는 발급 후 **OneS1ght 콘솔 → 설정 → 측위 연결**에 등록해야
  실제 도면·존 데이터가 연결됩니다.
</Note>

## 2. 측위 인프라 (데모: 준비 완료)

측위가 동작하려면 공간(건물·층·도면)과 로케이터(UWB 앵커)가 구축되어 있어야 합니다.
**데모 현장에는 이미 구축되어 있으므로 이 단계는 건너뜁니다** — 전체 과정이 궁금하다면:

<CardGroup cols={2}>
  <Card title="공간 구축" icon="building" href="/geospace/spaces">
    건물·층 생성과 도면(배경도) 업로드
  </Card>

  <Card title="로케이터 설정" icon="location-dot" href="/geospace/locators">
    하드웨어 등록 → 현장 설치·측정 → 도면 배치
  </Card>
</CardGroup>

**데모 현장 구성**

* 한국: **금정역 skv1 · 607호** (측위 동작 확인용)
* 일본: **赤坂第35興和ビル · 304** — 실측 약 5.6 × 11.3 m 대회의실, 앵커 4대 사각 배치

<Note>
  **그 외 새로운 장소를 등록해야 하는 경우** — 대상 공간의 **내부 실측 확인** 후,
  [공간 구축](/geospace/spaces)(건물·층·도면 업로드) → [로케이터 설정](/geospace/locators)(앵커 설치·측정·배치)
  단계를 거쳐 도면 구성이 필요합니다.
</Note>

## 3. 영역(존) 생성

이벤트 영역은 두 가지 방법으로 만들 수 있습니다.

| 방법           | 경로                                                       | 설명                                                                                                 |
| ------------ | -------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| **직접 그리기**   | OneS1ght 콘솔 → **공간 관리**                                  | 도면(구역 관리 화면) 위에 폴리곤을 직접 그려 등록 — [상세](/locator/areas)                                               |
| **에이전트로 생성** | OneS1ght 콘솔 → **자연어 질의** → [시책 관리](/agent/action-agents) | 질의 답변과 함께 표시되는 **제언 카드**를 \*\*\[시책관리에 추가하기]\*\*로 등록 → 시책 관리에서 해당 목록을 **실행(활성화)하면 공간 관리에 자동 매핑**됩니다 |

### 직접 그리기 (공간 관리)

<Steps>
  <Step title="구역(빌딩) · 층 선택">
    GeoSpace Intelligence 에 등록된 건물·층 목록에서 대상 층을 선택합니다.
  </Step>

  <Step title="존 그리기">
    **\[존 그리기]** 를 누른 뒤 도면을 클릭해 그립니다 —
    **클릭: 꼭짓점 추가 · 더블클릭: 닫기 · ESC: 취소** (최소 4점).
    그린 존에 이름을 붙이고 **\[저장]** 하면 ZONE 목록에 추가됩니다.
  </Step>

  <Step title="선택 · 삭제">
    **\[선택]** 으로 선택 모드에 들어가 생성된 존을 고르고, **\[삭제]** 로 지웁니다.
  </Step>

  <Step title="저장">
    **\[저장]** 을 누르면 변경 내용이 **GeoSpace Intelligence 로 저장**됩니다.
  </Step>
</Steps>

<Frame caption="공간 관리 — 존 그리기: ① 빌딩·층 선택 ② 존 그리기 ③ 선택 ④ 삭제 ⑤ 저장 ⑥ 도면에서 그리기">
  <img src="https://mintcdn.com/onecheck/rP3yO-pt3RJPc-aX/images/demo/zone-draw.png?fit=max&auto=format&n=rP3yO-pt3RJPc-aX&q=85&s=fbb92bca197c42344927953b32bce78c" alt="공간 관리에서 존을 그리는 화면 (단계 표시)" width="1400" height="892" data-path="images/demo/zone-draw.png" />
</Frame>

<Tip>
  데모 앱은 **존이 없는 층에서 1초 간격으로 존 등록을 감시**합니다 — 어느 방법으로 만들든
  몇 초 안에 앱 지도에 자동으로 나타납니다. 시연 중 실시간으로 만들어 보세요.
</Tip>

***

## 4. 데모 앱 빌드

### 준비물

| 항목                        | 비고                                        |
| ------------------------- | ----------------------------------------- |
| Mac + **Xcode 27 (베타)**   | developer.apple.com 에서 설치 — iOS 27 SDK 필요 |
| **iPhone 12 이상** (UWB 지원) | **iOS 27 이상** 설치 필요                       |
| **USB 연결 케이블**            | 실기기 설치는 케이블 연결로만 진행합니다                    |
| 키 3종                      | 위 1번 — 담당자 전달                             |

### 4-1. 저장소 받기

```bash theme={null}
git clone https://github.com/onecheck-inc/oneSight2.0-SDK-DEMO.git
cd oneSight2.0-SDK-DEMO
```

### 4-2. 키 파일 만들기

전달받은 `secrets.sqlite` 파일이 있으면 아래 위치에 복사하면 끝입니다.

```
oneS1ghtSdk/App/Resources/secrets.sqlite
```

키 **값**만 받았다면, 저장소 폴더에서 아래 명령의 `<…>` 자리에 키를 넣어 실행합니다.
(Mac 기본 내장 `sqlite3` — 별도 설치 불필요)

```bash theme={null}
sqlite3 oneS1ghtSdk/App/Resources/secrets.sqlite \
  "CREATE TABLE config (key TEXT PRIMARY KEY, value TEXT); \
   INSERT INTO config VALUES ('sdk_key','<SDK 키>'); \
   INSERT INTO config VALUES ('geospace_key','<GeoSpace 키>'); \
   INSERT INTO config VALUES ('partner_key','<Partner 키>');"
```

<Warning>
  전달받은 키는 저장소·공개 채널에 올리지 마세요.
</Warning>

### 4-3. Xcode 로 열기

```bash theme={null}
open oneS1ghtSdk.xcodeproj
```

<Note>
  **iOS 개발 경험이 있다면 4-4·4-5는 건너뛰어도 됩니다** — 평소 하던 서명·실기기 설정
  그대로입니다. (요약: Personal Team 서명 + 기기 개발자 모드)
</Note>

### 4-4. 서명 설정 (처음 한 번)

**Apple ID 를 Xcode 에 등록** — 유료 개발자 등록 필요 없음, 평소 쓰는 Apple ID 그대로 됩니다.

<Steps>
  <Step title="계정 등록">
    메뉴 막대 **Xcode → Settings…** (`Cmd+,`) → **Accounts** 탭 → 왼쪽 아래 **+** →
    **Apple ID** 로그인 (이중 인증 코드가 아이폰으로 옵니다)
  </Step>

  <Step title="프로젝트에 서명 지정">
    왼쪽 파일 목록 맨 위 파란 아이콘(**oneS1ghtSdk**) → **TARGETS → oneS1ghtSdk** →
    **Signing & Capabilities** 탭 → **Team** 에서 방금 등록한 계정(`이름 (Personal Team)`) 선택
  </Step>

  <Step title="Bundle ID 충돌 시">
    *"Bundle identifier is not available"* 오류가 나오면 **Bundle Identifier** 뒤에
    아무 글자나 붙여 바꿉니다 (예: `…demo` → `…demo2`). 오류가 사라지면 완료.
  </Step>
</Steps>

### 4-5. 아이폰 준비 (처음 한 번)

<Steps>
  <Step title="컴퓨터 신뢰">
    케이블로 iPhone 연결 → 아이폰에 뜨는 **"이 컴퓨터를 신뢰하시겠습니까?"** → **신뢰** + 암호 입력
  </Step>

  <Step title="개발자 모드 켜기">
    아이폰 **설정 → 개인정보 보호 및 보안 → 개발자 모드** → 켬 → **재시동**

    ※ "개발자 모드" 항목은 iPhone 을 Mac 에 한 번 연결한 뒤에 나타납니다.
  </Step>
</Steps>

<Warning>
  개발자 모드를 켜지 않으면 Xcode 에 기기가 "사용 불가"로 표시되고 실행이 안 됩니다.
</Warning>

### 4-6. 실행

1. Xcode 상단 기기 선택에서 **내 iPhone** 선택 (시뮬레이터 아님)
2. **▶ Run** (`Cmd+R`) — 첫 빌드는 몇 분 걸릴 수 있음
3. "Untrusted Developer" 로 막히면: 아이폰 **설정 → 일반 → VPN 및 기기 관리 → 개발자 앱 → 신뢰** 후 다시 Run

<Note>
  무료 계정 서명은 **7일 후 만료**됩니다 — 만료되면 케이블 연결 후 다시 Run 으로 재설치하면 됩니다.
</Note>

***

## 5. 체험 시나리오

1. 앱 실행 → 권한 요청 **모두 허용** (위치 · 근거리 상호작용)
2. 상단에서 **빌딩 / 층** 선택 → 도면 로드 — 이 목록에는 [측위 인프라(GeoSpace)](/geospace/spaces)
   단계를 거쳐 **등록된 건물·층이 표시**됩니다. 아래는 현재 데모 환경에 등록된 예시입니다.
   (시스템 언어에 따라 기본 선택: 한국어 → 금정역 skv1 · 607호 / 日本語 → 赤坂第35興和ビル · 304)
3. 상태가 **준비 완료**가 되면 **\[내 위치 확인 시작]** 탭
4. 도면 위 **빨간 점** = 실시간 내 위치
5. 파란 영역(존)에 **걸어 들어가면** 영역이 빨갛게 바뀌고, 서버에 이벤트가 있으면 **쿠폰 팝업**이 뜹니다

<Note>
  **쿠폰 이벤트는 시연 시 담당자가 서버에 적재합니다** — 존에 들어가 있는 동안 앱이 서버를
  1초 간격으로 확인하고, 이벤트가 있으면 즉시 팝업으로 표시합니다 (1회 수령하면 종료).
  존에 들어갔는데 쿠폰이 안 뜨면 담당자에게 적재 여부를 확인하세요.
</Note>

### 정상 동작 화면

<CardGroup cols={2}>
  <Frame caption="① 준비 완료 — 층 로드 + 이벤트 존(파란 영역) 표시, 시작 버튼 활성화 (금정역 skv1 · 607호)">
    <img src="https://mintcdn.com/onecheck/rP3yO-pt3RJPc-aX/images/demo/demo-ready.png?fit=max&auto=format&n=rP3yO-pt3RJPc-aX&q=85&s=1706b913ad59aa183c5f8a24e02c6232" alt="준비 완료 화면 — 존이 표시된 도면과 시작 버튼" width="416" height="900" data-path="images/demo/demo-ready.png" />
  </Frame>

  <Frame caption="② 위치 확인 중 — 빨간 점 = 실시간 내 위치, 우상단 ↻ 새로고침 (赤坂第35興和ビル · 304)">
    <img src="https://mintcdn.com/onecheck/rP3yO-pt3RJPc-aX/images/demo/demo-tracking.png?fit=max&auto=format&n=rP3yO-pt3RJPc-aX&q=85&s=649520f8cf995fba63b94a792734b642" alt="위치 확인 중 화면 — 도면 위 빨간 점과 좌표" width="416" height="900" data-path="images/demo/demo-tracking.png" />
  </Frame>
</CardGroup>

<Note>
  앱 UI는 시스템 언어를 따릅니다 — 위 화면은 일본어 설정 기기의 예입니다.
  앵커가 없는 층에서는 도면만 열람되고 시작 버튼이 비활성화됩니다("이 층은 위치 확인이 안 돼요") — 정상 동작입니다.
</Note>

### 화면·기능 설명

| 기능           | 설명                                                                                         |
| ------------ | ------------------------------------------------------------------------------------------ |
| **빌딩**       | 한국향 금정역 skv1 · 일본향 赤坂第35興和ビル — 두 현장 모두 앵커 설치로 측위 가능                                        |
| **층**        | = **스페이스(space)** — 한 빌딩 안에 여러 스페이스 (도면·앵커·영역 별도 구성)                                       |
| **빨간 점**     | 실시간 내 위치 — 시작하면 표시, 움직이면 따라오고, 종료하면 사라짐                                                    |
| **영역(존)**    | 콘솔에서 생성한 존 — 파란 폴리곤, 진입하면 빨강                                                               |
| **↻ 새로고침**   | 존 변경·삭제를 지도에 반영 — 존 감시 폴링은 첫 존이 나타나면 종료되므로, **이후 변경은 이 버튼으로** 반영합니다 (시책 실행으로 추가된 존 확인도 동일) |
| **시작/종료 버튼** | 시작(내 위치 확인 시작) · 종료(위치 확인 종료) — 측위 불가 층에서는 비활성                                             |
| **상태 표시줄**   | 준비 완료 · 위치 확인 중(+좌표) · 위치 확인 불가                                                            |

<Note>
  빌딩·층을 바꾸면 도면·설정을 새로 받아옵니다 — 서버 응답에 따라 **수 초 걸릴 수 있으니**
  로딩이 떠 있으면 잠시 기다려 주세요.
</Note>

## 잘 안 될 때

| 증상               | 해결                                           |
| ---------------- | -------------------------------------------- |
| 상태가 **"연결 실패"**  | `secrets.sqlite` 를 4-2 위치에 넣었는지 확인 후 다시 빌드   |
| 시작해도 빨간 점이 안 나옴  | 측위 앵커가 켜진 층인지 확인 — 몇 초 뒤 자동 진단 로그가 표시됩니다     |
| 존에 들어갔는데 쿠폰이 안 뜸 | 담당자에게 이벤트 적재 여부 확인 · 이미 1회 수령했으면 정상 (세션당 1회) |
| 앱 설치 실패 (서명 오류)  | 4-4 다시 확인 (Team 선택 + Bundle ID 변경)           |
| 기기가 "사용 불가"로 표시  | 4-5 개발자 모드 켜기 + 재시동                          |
| 7일 뒤 앱이 안 열림     | 케이블 연결 후 다시 Run (무료 서명 만료)                   |

## 언어

앱은 시스템 언어를 따릅니다: **한국어 · 日本語 · English** (그 외 언어는 한국어)

<Tip>
  **다른 언어로 시연하려면** — 아이폰 **설정 → 일반 → 언어 및 지역 → iPhone 언어**에서
  변경 후 앱을 다시 실행하세요. 일본어로 바꾸면 기본 빌딩도 일본 현장(赤坂)으로 선택됩니다.
</Tip>

<Warning>
  iPhone 언어는 **기기 전체**에 적용됩니다 — 시연이 끝나면 원래 언어로 되돌리는 것을 잊지 마세요.
</Warning>

***

## 다음 단계

<CardGroup cols={2}>
  <Card title="SDK 연동 (정식)" icon="code" href="/sdk/overview">
    데모로 흐름을 확인했다면, 내 앱에 SDK를 연동합니다.
  </Card>

  <Card title="공간 관리 (구역·존)" icon="draw-polygon" href="/locator/areas">
    도면 위에서 이벤트 영역을 편집합니다.
  </Card>
</CardGroup>