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

# 사용법

> OneS1ght iOS SDK의 빠른 시작 코드, 주요 API, 구역(Zone) 이벤트 수신 방법을 안내합니다.

## 빠른 시작

```swift theme={null}
import OneS1ghtSDK

// ① 앱 시작 시 — 키 검증 + 설정 로드
try await OneS1ghtSDK.shared.initialize(apiKey: "ock_sdk_...")

// ② 매장 화면 진입 시 — 측위 시작 (위치 권한·수집 동의 후)
try await OneS1ghtSDK.shared.start(consent: true)

// 구역 이벤트 수신
OneS1ghtSDK.shared.onZoneEvent = { event in
    if case .enter(let zone, _) = event { print("진입: \(zone.name)") }
}

// ③ 매장 화면 이탈 시
await OneS1ghtSDK.shared.stop()
```

<Note>
  `initialize`는 앱 시작 시 1회, `start`/`stop`은 매장 화면의 진입/이탈에 맞춰 호출하는 것을 권장합니다.
</Note>

## 주요 API

### 함수

| 함수                      | 설명                                                     |
| ----------------------- | ------------------------------------------------------ |
| `initialize(apiKey:)`   | 앱 시작 시 키 검증 + 설정 로드                                    |
| `start(consent:)`       | 측위 시작 (위치 권한·수집 동의 후)                                  |
| `stop()`                | 측위 중지                                                  |
| `identify(customerId:)` | 익명 사용자에 고객 ID 연결 {/* TODO(팀): identify 동작/유효 시점 상세 */} |

### 콜백

| 콜백            | 설명                                     |
| ------------- | -------------------------------------- |
| `onZoneEvent` | 구역 진입·이탈·체류 이벤트 수신                     |
| `onTriggers`  | 트리거 수신 {/* TODO(팀): 트리거 정의·페이로드 상세 */} |
| `onDebugLog`  | 디버그 로그 수신                              |

### 조회

| 프로퍼티                     | 설명                  |
| ------------------------ | ------------------- |
| `isInitialized`          | 초기화 완료 여부           |
| `isPositioningAvailable` | 현재 기기에서 측위 사용 가능 여부 |
| `anonUserId`             | 익명 사용자 ID           |

## 동의 · 위치 권한

<Warning>
  `start(consent:)`를 호출하기 전에 **위치 권한**과 **데이터 수집 동의**를 반드시 받아야 합니다. `consent: true`는 사용자로부터 수집 동의를 받았음을 의미합니다.
</Warning>

측위가 현재 기기에서 가능한지 확인하려면 `isPositioningAvailable`을 조회하세요. 미지원 기기에서는 측위가 비활성화되며 앱은 정상 동작합니다.

## 구역(Zone) 이벤트

`onZoneEvent` 콜백으로 구역 진입·이탈·체류 이벤트를 수신합니다. 아래 예시는 진입(`.enter`) 이벤트에서 구역 이름을 읽는 방법입니다.

```swift theme={null}
OneS1ghtSDK.shared.onZoneEvent = { event in
    if case .enter(let zone, _) = event { print("진입: \(zone.name)") }
}
```

## 문의

SDK 관련 문의는 [onesight-support@onecheck.co.kr](mailto:onesight-support@onecheck.co.kr)로 연락해 주세요.