> ## 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)までご連絡ください。