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

# Usage

> Quick-start code, the main API, and how to receive Zone events with the OneS1ght iOS SDK.

## Quick start

```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>
  Call `initialize` once at app start, and call `start`/`stop` as the store screen is entered and exited.
</Note>

## Main API

### Functions

| Function                | Description                                                                                          |
| ----------------------- | ---------------------------------------------------------------------------------------------------- |
| `initialize(apiKey:)`   | Verify the key and load configuration at app start                                                   |
| `start(consent:)`       | Start positioning (after location permission and collection consent)                                 |
| `stop()`                | Stop positioning                                                                                     |
| `identify(customerId:)` | Associate a customer ID with the anonymous user {/* TODO(team): identify behavior/timing details */} |

### Callbacks

| Callback      | Description                                                             |
| ------------- | ----------------------------------------------------------------------- |
| `onZoneEvent` | Receive zone enter / exit / dwell events                                |
| `onTriggers`  | Receive triggers {/* TODO(team): trigger definition/payload details */} |
| `onDebugLog`  | Receive debug logs                                                      |

### Queries

| Property                 | Description                                            |
| ------------------------ | ------------------------------------------------------ |
| `isInitialized`          | Whether initialization has completed                   |
| `isPositioningAvailable` | Whether positioning is available on the current device |
| `anonUserId`             | The anonymous user ID                                  |

## Consent · location permission

<Warning>
  Before calling `start(consent:)`, you must obtain **location permission** and **data collection consent**. Passing `consent: true` means the user has granted collection consent.
</Warning>

Query `isPositioningAvailable` to check whether positioning is available on the current device. On unsupported devices, positioning is disabled and the app keeps working normally.

## Zone events

Use the `onZoneEvent` callback to receive zone enter / exit / dwell events. The example below reads the zone name from an enter (`.enter`) event.

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

## Support

For SDK questions, contact [onesight-support@onecheck.co.kr](mailto:onesight-support@onecheck.co.kr).