Android SDK - OneS1ght

インポート

import co.onecheck.ones1ght.android.*           // OneS1ght · FloorSession · SdkError · リスナー
import co.onecheck.ones1ght.android.model.*     // Building · Floor · Zone · Coordinates · Trigger · ConfigChange
import co.onecheck.ones1ght.android.network.ApiError
import co.onecheck.ones1ght.android.runtime.LogLevel

import co.onecheck.ones1ght.android.*;          // OneS1ght · FloorSession · SdkError · Callback · リスナー
import co.onecheck.ones1ght.android.model.*;    // Building · Floor · Zone · Coordinates · Trigger · ConfigChange
import co.onecheck.ones1ght.android.network.ApiError;
import co.onecheck.ones1ght.android.runtime.LogLevel;

初期化

.initialize

OneS1ght API キーで測位エンジンを初期化します。自社サーバーを構築した場合のみ baseUrl を渡します（デフォルトは OneS1ght.DEFAULT_BASE_URL）。

OneS1ght.initialize(context = context.applicationContext, sdkKey = "YOUR_SDK_KEY")

OneS1ght.initialize(context, "YOUR_SDK_KEY", new Callback<Void>() {
    @Override public void onSuccess(Void result) { }
    @Override public void onError(Throwable error) { }
});

.requestPermission

測位エンジンの利用に必要なアプリ権限をリクエストします。

結果	意味
`AUTHORIZED`	測位可能
`DENIED`	権限拒否
`UNSUPPORTED`	測位非対応端末

val status = OneS1ght.requestPermission(activity)

OneS1ght.requestPermission(activity, new Callback<PermissionStatus>() {
    @Override public void onSuccess(PermissionStatus status) { }
    @Override public void onError(Throwable error) { }
});

.setLanguage

SDK のログ文言の言語を設定します。
ko: 韓国語、 ja: 日本語、 en: 英語、 null: システム設定の言語

OneS1ght.setLanguage("ja")

OneS1ght.setLanguage("ja");

.onDebugLog

SDK のログを受信します。
level: ログレベル、 message: ログメッセージ

OneS1ght.onDebugLog = DebugLogListener { level, message ->
    if (level >= LogLevel.WARN) Log.w("OneS1ght", message)
}

OneS1ght.setOnDebugLog((level, message) -> {
    if (level.compareTo(LogLevel.WARN) >= 0) Log.w("OneS1ght", message);
});

.reset

セッションを破棄して測位を止め、保存されたキーと建物情報を消去します。その後は initialize を再度呼んでください（それまでは NotInitialized、E1001）。

OneS1ght.reset()

OneS1ght.reset(new Callback<Void>() {
    @Override public void onSuccess(Void result) { }
    @Override public void onError(Throwable error) { }
});

状態の取得

.isInitialized

初期化に成功したかを返します。

val ready = OneS1ght.isInitialized

boolean ready = OneS1ght.isInitialized();

.deviceAvailability

測位可能な端末かを判定し、非対応の場合はその理由を返します。initialize() の後に読みます — それより前は DEVICE_NOT_SUPPORTED（Android 17 未満は OS_VERSION_TOO_LOW）です。

値	意味
`AVAILABLE`	測位可能
`OS_VERSION_TOO_LOW`	Android 17（API 37）未満
`DEVICE_NOT_SUPPORTED`	UWB 非対応端末

when (OneS1ght.deviceAvailability) {   // initialize() の後に
    DeviceAvailability.AVAILABLE            -> Unit
    DeviceAvailability.OS_VERSION_TOO_LOW   -> Unit
    DeviceAvailability.DEVICE_NOT_SUPPORTED -> Unit
    else                                    -> Unit
}

DeviceAvailability availability = OneS1ght.getDeviceAvailability();
boolean available = OneS1ght.isDeviceAvailable();

.googleMapKey

図面を表示するための Google Maps API キーを返します。

val mapKey = OneS1ght.googleMapKey   // String?

String mapKey = OneS1ght.getGoogleMapKey();

.SDK_VERSION

使用中の SDK バージョンを返します。

val version = OneS1ght.SDK_VERSION   // "0.0.9"

String version = OneS1ght.SDK_VERSION;

プロフィール

.createProfile

新しいパーソナライズプロフィールを作成します。成功すると一意のプロフィール ID を返します。

val profileId = OneS1ght.createProfile(mapOf("gender" to "F", "ageBand" to "20s"))

Map<String, String> attributes = new HashMap<>();
attributes.put("gender", "F");
attributes.put("ageBand", "20s");
OneS1ght.createProfile(attributes, new Callback<String>() {
    @Override public void onSuccess(String profileId) { }
    @Override public void onError(Throwable error) { }
});

.identify

収集する測位データを紐付けるプロフィールを設定します。解除する場合は null を設定してください。

OneS1ght.identify(profileId)

OneS1ght.identify(profileId);

.fetchProfile

プロフィールの属性を取得します。

val attributes = OneS1ght.fetchProfile(profileId)

OneS1ght.fetchProfile(profileId, new Callback<Map<String, String>>() {
    @Override public void onSuccess(Map<String, String> attributes) { }
    @Override public void onError(Throwable error) { }
});

.replaceProfile

プロフィールの属性を置き換えます。以前のデータは削除されます。

OneS1ght.replaceProfile(profileId, mapOf("gender" to "F", "ageBand" to "30s"))

Map<String, String> attributes = new HashMap<>();
attributes.put("gender", "F");
attributes.put("ageBand", "30s");
OneS1ght.replaceProfile(profileId, attributes, new Callback<Void>() {
    @Override public void onSuccess(Void result) { }
    @Override public void onError(Throwable error) { }
});

.deleteProfile

プロフィール情報を完全に削除します。

OneS1ght.deleteProfile(profileId)

OneS1ght.deleteProfile(profileId, new Callback<Void>() {
    @Override public void onSuccess(Void result) { }
    @Override public void onError(Throwable error) { }
});

空間の取得

.buildings

テナントに紐付くすべての建物一覧を取得します。

val buildings = OneS1ght.buildings()
val building = OneS1ght.building(id = buildingId)

OneS1ght.buildings(new Callback<List<Building>>() {
    @Override public void onSuccess(List<Building> buildings) { }
    @Override public void onError(Throwable error) { }
});

.floors

建物のフロア一覧を取得します。

val floors = OneS1ght.floors(buildingId)

OneS1ght.floors(buildingId, new Callback<List<Floor>>() {
    @Override public void onSuccess(List<Floor> floors) { }
    @Override public void onError(Throwable error) { }
});

.floor

選択したフロアの詳細情報を取得します。

val floor = OneS1ght.floor(buildingId, floorId)
val png = floor.image   // ByteArray?

OneS1ght.floor(buildingId, floorId, new Callback<Floor>() {
    @Override public void onSuccess(Floor floor) { byte[] png = floor.getImage(); }
    @Override public void onError(Throwable error) { }
});

.zones

選択したフロアのすべてのゾーンを取得します。

val zones = OneS1ght.zones(buildingId, floorId)
val zone = OneS1ght.zone(buildingId, floorId, zoneId)

OneS1ght.zones(buildingId, floorId, new Callback<List<Zone>>() {
    @Override public void onSuccess(List<Zone> zones) { }
    @Override public void onError(Throwable error) { }
});

.locators

選択したフロアのロケーター情報を取得します。

val floorLocators = OneS1ght.locators(buildingId, floorId)
val ready = floorLocators.positioningReady

OneS1ght.locators(buildingId, floorId, new Callback<FloorLocators>() {
    @Override public void onSuccess(FloorLocators floorLocators) { }
    @Override public void onError(Throwable error) { }
});

フロアの指定

.setFloorMap

ゾーンイベントに使うフロアを指定します（任意）。指定しなくても座標は届きますが、ゾーンイベント・施策を受け取るには必要です。

val floor = OneS1ght.floor(buildingId, floorId)
OneS1ght.setFloorMap(floor, buildingId)

OneS1ght.floor(buildingId, floorId, new Callback<Floor>() {
    @Override public void onSuccess(Floor floor) {
        OneS1ght.setFloorMap(floor, buildingId, new Callback<Void>() {
            @Override public void onSuccess(Void result) { }
            @Override public void onError(Throwable error) { }
        });
    }
    @Override public void onError(Throwable error) { }
});

.refreshZones

最新のゾーン情報を取得します。

val zones = OneS1ght.refreshZones()

OneS1ght.refreshZones(new Callback<List<Zone>>() {
    @Override public void onSuccess(List<Zone> zones) { }
    @Override public void onError(Throwable error) { }
});

測位セッション

.floorSession

測位セッションを返します。フロアに関係なくアプリ全体で 1 つのインスタンスで、initialize 前は NotInitialized を投げます。

val session = OneS1ght.floorSession()

FloorSession session = OneS1ght.floorSession();

.begin

ユーザーの測位を開始します。

session.begin()

session.begin(new Callback<Void>() {
    @Override public void onSuccess(Void result) { }
    @Override public void onError(Throwable error) { }
});

.end

ユーザーの測位を終了します。

session.end()

session.end(new Callback<Void>() {
    @Override public void onSuccess(Void result) { }
    @Override public void onError(Throwable error) { }
});

.pause · .resume

ユーザーの測位を一時停止・再開します。終了とは異なり、SDK 内の測位エンジンは停止しません。

session.pause()
session.resume()

session.pause();
session.resume();

.isRunning · .isPaused

測位中かどうかと、一時停止中かどうかを返します。

val running = session.isRunning
val paused = session.isPaused
val current = session.floor   // Floor?

boolean running = session.isRunning();
boolean paused = session.isPaused();
Floor current = session.getFloor();

セッションイベント

.onPosition

ユーザーの座標をリアルタイムで届けます。エンジンが出す速度のまま届き、サーバー送信だけがコンソールの設定値（デフォルトは毎秒 4 回）に間引かれます。

session.onPosition = PositionListener { coordinates -> Log.d("OneS1ght", "${coordinates.x}, ${coordinates.y}") }

session.setOnPosition(coordinates -> Log.d("OneS1ght", coordinates.getX() + ", " + coordinates.getY()));

.onZoneEnter · .onZoneExit

ゾーンへの進入・退出時にイベントが発生します。

session.onZoneEnter = ZoneListener { zone -> Log.d("OneS1ght", "IN ${zone.name}") }
session.onZoneExit  = ZoneListener { zone -> Log.d("OneS1ght", "OUT ${zone.name}") }

session.setOnZoneEnter(zone -> Log.d("OneS1ght", "IN " + zone.getName()));
session.setOnZoneExit(zone -> Log.d("OneS1ght", "OUT " + zone.getName()));

.onZoneDwell

特定ゾーンの滞在時間が基準（dwellSeconds）を超えるとイベントが発生します。

session.onZoneDwell = DwellListener { zone, seconds -> Log.d("OneS1ght", "DWELL ${zone.name} ${seconds}s") }

session.setOnZoneDwell((zone, seconds) -> Log.d("OneS1ght", "DWELL " + zone.getName() + " " + seconds));

.onTriggers

空間内のイベント（施策）が動作するとイベントが発生します。

session.onTriggers = TriggersListener { zoneId, triggers ->
    triggers.forEach { trigger -> Log.d("OneS1ght", "${trigger.type} ${trigger.payload}") }
}

session.setOnTriggers((zoneId, triggers) -> {
    for (Trigger trigger : triggers) Log.d("OneS1ght", trigger.getType());
});

.onFloorDetected

エンジンがロケーターの BLE 信号でフロアを見つけるとフロア ID で、フロアを見失うと null で呼ばれます。

session.onFloorDetected = SessionFloorListener { floorId ->
    if (floorId == null) return@SessionFloorListener
    lifecycleScope.launch {
        val floor = OneS1ght.floor(buildingId, floorId)
        OneS1ght.setFloorMap(floor, buildingId)
    }
}

session.setOnFloorDetected(floorId -> {
    if (floorId == null) return;
    OneS1ght.floor(buildingId, floorId, new Callback<Floor>() {
        @Override public void onSuccess(Floor floor) {
            OneS1ght.setFloorMap(floor, buildingId, new Callback<Void>() {
                @Override public void onSuccess(Void result) { }
                @Override public void onError(Throwable error) { }
            });
        }
        @Override public void onError(Throwable error) { }
    });
});

.onStopped

ユーザーの測位が停止するとイベントが発生します。

理由	意味
`ENDED`	`end()`・`reset`・キーの変更
`ENGINE_FAILED`	測位エンジンの起動失敗

session.onStopped = SessionStoppedListener { reason ->
    when (reason) {
        FloorSession.StopReason.ENDED         -> Unit
        FloorSession.StopReason.ENGINE_FAILED -> Unit
        else                                  -> Unit
    }
}

session.setOnStopped(reason -> {
    if (reason == FloorSession.StopReason.ENGINE_FAILED) { }
});

.onConfigChanged

コンソール画面で設定が変更されるとイベントが発生します。

シグナル	意味
`ZonesChanged(floorId)`	ゾーン変更
`PlanChanged(floorId)`	図面変更
`RulesChanged(zoneId)`	施策変更
`SdkConfigChanged`	リモート設定変更
`ResyncNeeded`	再接続・イベントの取りこぼし

session.onConfigChanged = ConfigChangeListener { change ->
    when (change) {
        is ConfigChange.ZonesChanged, is ConfigChange.ResyncNeeded -> lifecycleScope.launch { OneS1ght.refreshZones() }
        is ConfigChange.PlanChanged -> redrawFloor()
        else -> Unit
    }
}

session.setOnConfigChanged(change -> {
    if (change instanceof ConfigChange.ZonesChanged || change instanceof ConfigChange.ResyncNeeded) {
        OneS1ght.refreshZones(new Callback<List<Zone>>() {
            @Override public void onSuccess(List<Zone> zones) { }
            @Override public void onError(Throwable error) { }
        });
    }
});

データ送信

座標は 300 件または 60 秒ごと、およびバックグラウンド移行時と end() 時に自動で送信されます。

.uploadPendingPositions

溜めた座標を即時送信します。

OneS1ght.uploadPendingPositions()

OneS1ght.uploadPendingPositions(new Callback<Void>() {
    @Override public void onSuccess(Void result) { }
    @Override public void onError(Throwable error) { }
});

.discardPendingPositions

溜めた座標を破棄します。

OneS1ght.discardPendingPositions()

OneS1ght.discardPendingPositions();

エラー処理

失敗は SdkError（SDK の状態）と ApiError（通信、co.onecheck.ones1ght.android.network.ApiError）で届きます。詳細はエラーコードを参照してください。

try {
    OneS1ght.initialize(context = context.applicationContext, sdkKey = key)
} catch (e: SdkError) {
    Log.w("OneS1ght", e.code.code)                     // "E1003"
} catch (e: ApiError) {
    Log.w("OneS1ght", "${e.code.code} ${e.message}")   // "E5005 …"
}

OneS1ght.initialize(context, key, new Callback<Void>() {
    @Override public void onSuccess(Void result) { }
    @Override public void onError(Throwable error) {
        if (error instanceof SdkError) {
            Log.w("OneS1ght", ((SdkError) error).getCode().getCode());   // "E1003"
        } else if (error instanceof ApiError) {
            Log.w("OneS1ght", ((ApiError) error).getCode().getCode() + " " + error.getMessage());
        }
    }
});

モデル

リストは List<T>、バイト列は ByteArray です。

Coordinates

フィールド	型	説明
`x`・`y`	`Double`	図面ローカルのメートル
`z`	`Double`	高さ

Building · Floor

型	フィールド	説明
`Building`	`id`・`name`	建物 ID・名前
	`floorCount: Int?`	フロア数
`Floor`	`id`・`name`	フロア ID・名前
	`image: ByteArray?`	デコード済みの図面 PNG バイト — 一覧取得では `null`
	`hasPlan: Boolean`	図面登録の有無
	`originX`・`originY`	図面原点（メートル）
	`widthM`・`heightM`	図面サイズ（メートル）
	`minX`・`minY`・`maxX`・`maxY`	配置範囲

Locator · FloorLocators

型	フィールド	説明
`Locator`	`address: Int`	UWB MAC の下位 2 バイト
	`x`・`y`・`z`	図面ローカルのメートル
`FloorLocators`	`locators`	フロアのロケーター一覧
	`sessionId: Int?`	UWB セッション — フロアごとに異なる
	`positioningReady: Boolean`	ロケーターとセッションの両方があるか

Zone

フィールド	型	説明
`id`・`name`	`String`	ゾーン ID・名前
`polygon`	`List<Position>`	頂点（`x`、`y` メートル）
`dwellSeconds`	`Int?`	滞在イベントの基準（秒）

Trigger

フィールド	型	説明
`triggerId`	`String`	トリガー ID
`type`	`String`	`signage`・`coupon`・`tracking`・`merch`・`generic`
`payload`	`Map<String, String>?`	種類ごとの付加情報

列挙型（ConfigChange・StopReason・PermissionStatus・DeviceAvailability・LogLevel）はマイナーバージョンで値が増えることがあります — when に else を置いてください。

制約

suspend API はどのコルーチンからでも呼べます。identify・discardPendingPositions・pause・resume はメインスレッドで使用します。
UWB 測位はフォアグラウンド専用です。バックグラウンドに入ると測位が止まり、滞在中のゾーンは退出（onZoneExit）として扱われ、リアルタイム受信が切れます。復帰すると測位が再開し、ResyncNeeded が届きます。
座標バッファはアプリのメモリ上に一時保存され、強制終了すると未送信の座標は失われます。
エミュレーターでは測位できません。

​インポート

​初期化

​.initialize

​.requestPermission

​.setLanguage

​.onDebugLog

​.reset

​状態の取得

​.isInitialized

​.deviceAvailability

​.googleMapKey

​.SDK_VERSION

​プロフィール

​.createProfile

​.identify

​.fetchProfile

​.replaceProfile

​.deleteProfile

​空間の取得

​.buildings

​.floors

​.floor

​.zones

​.locators

​フロアの指定

​.setFloorMap

​.refreshZones

​測位セッション

​.floorSession

​.begin

​.end

​.pause · .resume

​.isRunning · .isPaused

​セッションイベント

​.onPosition

​.onZoneEnter · .onZoneExit

​.onZoneDwell

​.onTriggers

​.onFloorDetected

​.onStopped

​.onConfigChanged

​データ送信

​.uploadPendingPositions

​.discardPendingPositions

​エラー処理

​モデル

​Coordinates

​Building · Floor

​Locator · FloorLocators

​Zone

​Trigger

​制約