iOS リファレンス

このドキュメントは v0.1.13 基準です。稼働中のバージョンは OneS1ght.sdkVersion で確認できます。

OneS1ght はアプリ全体で 1 つだけの静的エントリーポイントです — インスタンスは作らず、すべての API を型から直接呼び出します。すべての API は メインアクター（@MainActor） で呼び出します。

import OneS1ght

ライフサイクル

API	説明
`initialize(sdkKey:geoSdkKey:baseURL:) async throws`	アプリ起動時に 1 回。端末チェック → キー検証 → 設定の読み込み。冪等 — 成功後の再呼び出しは無視、失敗後の再呼び出しはリトライ、別のキーで呼び出すとセッションを再構成
`permissions() async -> PermissionStatus`	測位の権限を確認 — 呼び出すとシステムのポップアップが表示されます
`reset() async`	セッションを破棄。以降、別のキーで `initialize` できます（ランタイムでのキー入れ替え用）
`setLanguage(_ code: String?)`	SDK のログ・案内文言の言語 — `"ko"`·`"ja"`·`"en"`。`nil` なら端末の言語（既定）。`0.1.11~`

initialize のパラメーター:

パラメーター	型	説明
`sdkKey`	`String`	OneS1ght コンソールで発行（`ock_sdk_…`）— 認証・ゾーン・収集・イベント・図面
`geoSdkKey`	`String?`（デフォルト `nil`）	暫定パラメーター — ロケーター・セッション・フロア情報の取得用の過渡的な値で、担当者からお渡しします。省略すると測位のみ無効
`baseURL`	`URL`（デフォルトは本番サーバー）	自社サーバーを構築したお客様のみ。開発／本番の区別はこのパラメーターではなくキーで分かれます

デフォルトの baseURL は https://console.ones1ght.com/api/sdk/v1 です。

initialize は建物・フロアを取得しません。 空間の設定は setFloorMap の役割です — 省略すると測位パイプラインは動きますが座標が出ません（E3001）。

測位セッション — FloorSession

SwiftUI
UIKit

.task {
    guard let session = try? OneS1ght.floorSession() else { return }
}

override func viewDidLoad() {
    super.viewDidLoad()
    guard let session = try? OneS1ght.floorSession() else { return }
}

API	説明
`floorSession() throws -> FloorSession`	セッションを取得。常に同じインスタンス — UWB ラジオ・判定エンジン・座標バッファは端末に 1 つだけです
`session.begin() async throws`	測位を開始（店舗への進入時）
`session.begin(provider:) async throws`	カスタム測位の注入 — シミュレーターでのテスト（`MockPositioningProvider`）など特殊な経路向け
`session.end() async`	測位を停止し、残りの座標を送信。初期化の状態は保持されるため `begin` の再呼び出しで再開できます
`session.floor: Floor?`	現在設定されているフロア
`session.isRunning: Bool`	測位が稼働中かどうか

コールバック

セッションのコールバックは FloorSession インスタンスに、デバッグログは OneS1ght 型に設定します。

コールバック	型	説明
`session.onPosition`	`((Coordinates) -> Void)?`	リアルタイム座標（図面ローカルのメートル）— 最大 4 回/秒
`session.onZoneEnter`	`((Zone) -> Void)?`	ゾーン進入 — 端末内の判定と同時（サーバー往復なし）
`session.onZoneExit`	`((Zone) -> Void)?`	ゾーン退出
`session.onZoneDwell`	`((Zone, TimeInterval) -> Void)?`	滞在の発火 —（ゾーン、滞在秒数）
`session.onTriggers`	`((String, [Trigger]) -> Void)?`	(zoneId, トリガー配列) — サーバーがマッチングしたパーソナライズアクション
`OneS1ght.onDebugLog`	`((LogLevel, String) -> Void)?`	SDK 内部の動作ログ。`initialize` より先に登録すると初期化のログを取りこぼしません

0.1.12 から onDebugLog はレベルと文字列の両方を渡します（以前は (String) -> Void）。移行ガイドをご確認ください。

LogLevel

public enum LogLevel { case log, info, warn, error }   // log < info < warn < error

Comparable なので level >= .warn のように絞り込めます。

レベル	意味	例
`.log`	流れの記録 — 普段は読まなくて構いません	座標の送信、エリアの投入
`.info`	知っておくと役立つこと — 正常ですが目に留まると助かります	この階にエリアがない、リアルタイム接続完了
`.warn`	確認が必要 — 不具合ではありませんが、このままでは期待どおりに動きません	集計間隔が座標周期より短く IN が発火しない
`.error`	不具合 — 直さないとその機能が動きません	有効アンカー不足で測位不可、セッション ID 未設定

「この階に登録されたエリアがありません」は、コンソールでまだエリアを作っていない 正常な状態です。不具合ではないため .info です。

サーバー応答は onTriggers だけです — ネットワークが切れると進入判定は届きますが、トリガーは届きません。

空間の取得

エンドポイントごとに 1 メソッドで、一覧と単件が対になっています。

API	説明
`buildings() async throws -> [Building]`	建物の一覧。`geoSdkKey` なしで初期化した場合は空の配列
`building(_:) async throws -> Building`	建物 1 件
`floors(_:) async throws -> [Floor]`	フロアの一覧 — 図面画像なし（`image == nil`。一覧を軽く保つため）
`floor(_:_:) async throws -> Floor`	フロア 1 件 — 図面画像を含む（キャッシュから返るため往復は増えません）
`zones(_:_:) async throws -> [Zone]`	フロアのゾーン一覧
`zone(_:_:_:) async throws -> Zone`	ゾーン 1 件
`locators(_:_:) async throws -> FloorLocators`	フロアのロケーター配置と UWB セッション ID

フロアの指定

API	説明
`setFloorMap(_:buildingID:) async throws`	フロアを指定 — ロケーター・セッション・ゾーンを内部エンジンに注入します。稼働中は即座にフロアを切り替え（セッションは維持）。`nil` で解除
`refreshZones() async -> [Zone]`	現在のフロアのゾーンのみ再取得（軽量 — 図面の再ダウンロードなし）。判定エンジンに即時反映

プロフィール

API	説明
`createProfile(_:) async throws -> String`	プロフィールを作成 — サーバーが発行した `profileId` を返します。アプリが保管して再利用
`getProfile(_:) async throws -> [String: String]`	属性の取得
`putProfile(_:_:) async throws`	属性の全置換（部分更新ではありません）
`deleteProfile(_:) async throws`	プロフィールの削除（蓄積された座標・イベントは保存ポリシーに従います）
`identify(profileId:)`	連携 — 測位の前に必ず実行。ログアウト時は `nil`

お客様の会員 ID はサーバーには届きません — マッピングはお客様側でのみ保持します。

savedProfileId ?? (try await OneS1ght.createProfile(…)) は コンパイルできません。 ?? の右辺は autoclosure のため try await を置けません — if let で書いてください。

データ送信

座標は 300 件または 60 秒 のいずれか早い方で送信されます。バックグラウンドへの遷移時と end() 時にも残りを送信します。

API	説明
`send() async`	バッファを今すぐ送信
`empty()`	バッファを破棄 — 送信しません

状態の取得

API	型	説明
`isInitialized`	`Bool`	初期化に成功したか（端末チェック通過 + キー有効 + 設定読み込み）
`deviceAvailability`	`DeviceAvailability`	測位可否と、不可の理由。`initialize` の前でも呼び出せます（ネットワーク未使用）
`isDeviceAvailable`	`Bool`	上記の簡易版（`== .available`）
`sdkVersion`	`String`	SDK のバージョン（例: `"0.1.13"`）

public enum DeviceAvailability: Equatable {
    case available            // 測位可能
    case osVersionTooLow      // iOS 27 未満 — 「OS を更新すると利用できます」と案内
    case deviceNotSupported   // UWB チップ非対応 — 「iPhone 12 以降が必要です」と案内
}

public enum PermissionStatus: Equatable {
    case authorized           // 測位を開始できる
    case denied               // アプリから再度リクエストできない — 設定アプリへ案内
    case unsupported          // この端末・OS では測位そのものが不可
}

エラー — SdkError

SdkError は SDK 自身が投げる 5 種類です。通信の失敗は ApiError で届きます。どちらの型も .code からエラーコードを取り出せます。

SwiftUI
UIKit

.task {
    do {
        try await OneS1ght.initialize(sdkKey: key)
    } catch let e as SdkError {
        print(e.code.rawValue)                  // "E1003"
    } catch let e as ApiError {
        print(e.code.rawValue, e.description)   // "E5005" · "応答の解析に失敗 — …"
    }
}

Task { @MainActor in
    do {
        try await OneS1ght.initialize(sdkKey: key)
    } catch let e as SdkError {
        print(e.code.rawValue)                  // "E1003"
    } catch let e as ApiError {
        print(e.code.rawValue, e.description)   // "E5005" · "応答の解析に失敗 — …"
    }
}

ケース	コード	発生タイミング	対処
`SdkError.notInitialized`	`E1001`	`initialize` なしで他の API を呼び出した	呼び出し順序を修正
`SdkError.notIdentified`	`E1004`	`identify` なしで測位を開始した	認証直後に `identify(profileId:)`
`SdkError.positioningDisabled`	`E1003`	キーは有効だが測位機能がオフ	コンソール設定を確認・サポートへ問い合わせ
`SdkError.osVersionTooLow`	`E2001`	iOS 27 未満	OS 更新を案内
`SdkError.deviceNotSupported`	`E2002`	UWB チップなし	`deviceAvailability` で事前に分岐
`ApiError.invalidKey`	`E1002`	キーが不正、または破棄済み（401）	コンソールでキーの状態を確認・再発行
`ApiError.forbidden`	`E5004`	他テナントのリソース（403）	キーのスコープを確認
`ApiError.notFound`	`E5003`	対象なし（404）	多くは契約の不一致
`ApiError.unprocessable`	`E5003`	ペイロードの問題（422）	SDK・サーバーのバージョン不一致を疑う
`ApiError.server`	`E5002`	サーバー 5xx	統合管理者に確認
`ApiError.network`	`E5001`	オフライン・タイムアウト	自動でリトライ
`ApiError.decoding`	`E5005`	応答 JSON の形式が不一致	理由は `description` に入ります

測位ランタイム（E4001〜E4003）と空間設定（E3001〜E3004）は throw されず、ログにのみ 残ります — onDebugLog またはコンソールのログ分析でご確認ください。全一覧

モデル

Coordinates — リアルタイム座標

public struct Coordinates: Codable, Equatable {
    public let x: Double   // メートル
    public let y: Double   // メートル
    public let z: Double   // 高さ（2D 測位の場合は 0）
}

Building · Floor — 建物・フロア

型	フィールド	説明
`Building`	`id` · `name`	建物 ID · 名前
	`floorCount: Int?`	フロア数（サーバーが返さない場合は `nil`）
`Floor`	`id` · `name`	フロア ID · 名前
	`image: Data?`	図面 PNG — `floors(_:)` で取得すると `nil`、`floor(_:_:)` で取得すると格納されます
	`hasPlan: Bool`	図面が登録されているか
	`originX` · `originY`	図面原点のオフセット（メートル）
	`widthM` · `heightM`	図面の実サイズ（メートル）
	`minX` · `minY` · `maxX` · `maxY`	配置範囲（原点 + サイズから導出）

Locator · FloorLocators — ロケーター

型	フィールド	説明
`Locator`	`address: Int`	UWB MAC の下位 2 バイト（例: `0x9DD7`）
	`x` · `y` · `z`	図面ローカルのメートル
`FloorLocators`	`locators: [Locator]`	このフロアに設置されたロケーター
	`sessionId: Int?`	UWB セッション — フロアごとに異なります。`nil` なら測位を開始できません
	`positioningReady: Bool`	ロケーターがあり、セッションもあるか（導出値）

Zone — ゾーン

フィールド	型	説明
`id` / `name`	`String`	ゾーンの識別子 · 名前
`polygon`	`[Position]`	頂点（順序どおり）— `Position` は図面ローカルのメートル (x, y)
`inDist`	`Double`	進入判定の距離(m) — デフォルト 3.0
`inCount` / `inCountInterval`	`Int`	進入確定に必要な検知回数 · カウント間隔（秒）
`outPeriod`	`Int`	退出判定の猶予
`priority`	`Int`	エリアが重なった場合の優先度
`callInout`	`Bool`	進入・退出コールバックを発行するか
`dwellSeconds`	`Int?`	滞在の発火周期（秒）— `nil` ならデフォルトの 5 秒

これらの判定パラメーターはサーバーのゾーンメタデータから配信され、コンソールの 空間管理 → ゾーンを選択 → SDK エリア判定 でゾーンごとに設定します（設定方法）。 zone.contains(Position(x:y:)) で任意の座標がゾーンに含まれるかを直接判定することもできます。

inCount が 0 の場合、進入が永久に確定せずゾーンイベントが発生しません。コンソールで登録した新規ゾーンのデフォルトは 1 です。値が 0 の古いゾーンがある場合はコンソールで確認してください。

Trigger — パーソナライズアクション

フィールド	型	説明
`trigger_id`	`String`	トリガーの識別子
`type`	`String`	`signage · coupon · tracking · merch · generic`
`payload`	`[String: String]?`	タイプ別の付加情報

MockPositioningProvider — テスト用

public final class MockPositioningProvider: PositioningProvider {
    public init()
    public func simulateEnter(buildingId: String)
    public func simulatePosition(_ c: Coordinates, floorId: String, at: Date = Date())
    public func simulateZone(_ zoneId: String, status: ZoneEventStatus, floorId: String, at: Date = Date())
}

session.begin(provider:) で注入し、UWB なしで SDK のパイプラインを確認します。 ZoneEventStatus は .enter · .dwell · .exit です。

スレッド

OneS1ght のすべての API は @MainActor です。SwiftUI のビューや .task からはそのまま呼び出せます。バックグラウンドのコンテキストからは await MainActor.run { … } で包んでください。
コールバック（onPosition など）もメインアクターで呼び出されます — UI をそのまま更新しても安全です。

既知の制約

iOS の UWB は フォアグラウンド専用 です。アプリがバックグラウンドに入ると測位が停止してバッファを送信し、復帰すると再開します。プラットフォームの制約のため SDK では回避できません。

座標バッファはメモリ上にあります。アプリが強制終了されると、未送信の座標は失われます（E5006）。

LICENSE ファイルはまだありません。利用条件は別途の契約に従います。

はじめに

測位インフラ（GeoSpace）

OneS1ght コンソール

開発者ガイド（SDK）

iOS リファレンス

ライフサイクル

測位セッション — FloorSession

コールバック

LogLevel

空間の取得

フロアの指定

プロフィール

データ送信

状態の取得

エラー — SdkError

モデル

Coordinates — リアルタイム座標

Building · Floor — 建物・フロア

Locator · FloorLocators — ロケーター

Zone — ゾーン

Trigger — パーソナライズアクション

MockPositioningProvider — テスト用

スレッド

既知の制約

​ライフサイクル

​測位セッション — FloorSession

​コールバック

​LogLevel

​空間の取得

​フロアの指定

​プロフィール

​データ送信

​状態の取得

​エラー — SdkError

​モデル

​Coordinates — リアルタイム座標

​Building · Floor — 建物・フロア

​Locator · FloorLocators — ロケーター

​Zone — ゾーン

​Trigger — パーソナライズアクション

​MockPositioningProvider — テスト用

​スレッド

​既知の制約

ライフサイクル

測位セッション — FloorSession

コールバック

LogLevel

空間の取得

フロアの指定

プロフィール

データ送信

状態の取得

エラー — SdkError

モデル

Coordinates — リアルタイム座標

Building · Floor — 建物・フロア

Locator · FloorLocators — ロケーター

Zone — ゾーン

Trigger — パーソナライズアクション

MockPositioningProvider — テスト用

スレッド

既知の制約