メインコンテンツへスキップ
このAPIはClient SDKキー（osk_プレフィックス）で認証します。 データ収集API（サーバー→OneSight）とは逆方向で、サーバーがクライアントにプッシュするイベントをポーリングします。

​
エンドポイント

GET /v1/persona/{persona_id}/events

​
概要

イベントポーリングAPIは、バックエンドからクライアントに配信すべきすべてのプッシュ型情報を単一チャネルで提供します。
  • ゾーン進入通知: 店舗内の特定コーナーに進入した際の通知
  • プロモーション: Flash Deal、割引情報
  • 決済ステータス: 決済リクエスト → 処理中 → 完了/失敗

​
リクエスト

​
クエリパラメータ

パラメータタイプ必須説明
zonestringX現在進入した店舗ゾーン（例: wine, meat）。省略時はゾーン無関係のイベントのみ返却

​
ゾーン種類

ゾーン説明
processed_food加工食品
fresh_produce新鮮野菜
meat精肉
wine酒類
bakeryベーカリー
checkoutレジ

​
レスポンス

​
ゾーンプロモーションイベント

{
  "success": true,
  "data": {
    "events": [
      {
        "event_id": "evt_flash_001",
        "event_type": "zone_promo",
        "expires_at": "2026-04-16T12:00:00Z",
        "blocks": [
          {
            "type": "promo_card",
            "header": "Flash Deal",
            "title": "加工食品コーナー",
            "subtitle": "カレーライス特別割引",
            "image_url": "https://cdn.example.com/products/house-curry.jpg",
            "badge": "50% OFF",
            "price": 2450,
            "original_price": 4900,
            "actions": [
              { "id": "claim_coupon", "label": "クーポンを受け取る", "style": "primary" },
              { "id": "dismiss_event", "label": "次回に", "style": "text" }
            ]
          }
        ]
      }
    ]
  }
}

​
ゾーン進入通知

{
  "success": true,
  "data": {
    "events": [
      {
        "event_id": "evt_zone_enter_wine_001",
        "event_type": "zone_entered",
        "zone": "wine",
        "expires_at": "2026-04-16T11:00:00Z",
        "blocks": [
          {
            "type": "text",
            "content": "ワインコーナーへようこそ！カレーに合うワインをお選びしましょうか？"
          },
          {
            "type": "suggestion",
            "content": "コスパの良いカベルネ・ソーヴィニヨンをおすすめできます。",
            "actions": [
              { "id": "recommend_wine", "label": "おすすめして", "style": "primary" },
              { "id": "skip_wine", "label": "大丈夫です", "style": "secondary" }
            ]
          }
        ]
      }
    ]
  }
}

​
決済ステータスイベント

{
  "success": true,
  "data": {
    "events": [
      {
        "event_id": "evt_pay_001",
        "event_type": "payment_state",
        "state": "COMPLETED",
        "order_id": "ORD-2026.04.16-A14:23",
        "amount": 42600,
        "blocks": [
          {
            "type": "result_card",
            "status": "success",
            "title": "決済が完了しました！",
            "message": "注文番号 ORD-2026.04.16-A14:23"
          }
        ]
      }
    ]
  }
}

​
イベントなし

{
  "success": true,
  "data": {
    "events": []
  }
}

​
イベントタイプ

タイプ説明
zone_promoゾーンプロモーション（Flash Dealなど）
zone_enteredゾーン進入通知
payment_state決済ステータス変更

​
決済ステータス

ステータス説明
REQUESTED決済リクエスト受付
PROCESSING決済会社処理中
COMPLETED決済完了
FAILED決済失敗

​
決済失敗コード

コード説明
INSUFFICIENT_BALANCE残高/限度不足
CARD_DECLINEDカード拒否
TIMEOUTタイムアウト
USER_CANCELLEDユーザーキャンセル
UNKNOWN不明なエラー

​
ブロックタイプ

タイプ説明
promo_cardプロモーションカード（画像、価格、割引）
textテキストメッセージ
image画像
product_list商品リスト
suggestionAIおすすめ/提案
result_card結果カード（成功/失敗/情報）
info_box案内ボックス

​
動作方式

  • イベントは一度だけ返されます（取得後に消費済み処理）
  • expires_atを過ぎたイベントは自動的に除外されます
  • event_idでクライアント側の重複排除（dedupe）が可能です
  • 定期的なポーリングを推奨します（2~5秒間隔）

​
コード例

​
curl

# ゾーン指定ポーリング
curl "https://api.ones1ght.com/v1/persona/$PERSONA_ID/events?zone=wine" \
  -H "Authorization: Bearer $SDK_KEY"

# ゾーン未指定ポーリング（汎用イベントのみ）
curl "https://api.ones1ght.com/v1/persona/$PERSONA_ID/events" \
  -H "Authorization: Bearer $SDK_KEY"

​
Swift (iOS) — タイマーベースポーリング

Timer.scheduledTimer(withTimeInterval: 3.0, repeats: true) { _ in
    let url = URL(string: "https://api.ones1ght.com/v1/persona/\(personaId)/events?zone=\(currentZone)")!
    var request = URLRequest(url: url)
    request.setValue("Bearer \(sdkKey)", forHTTPHeaderField: "Authorization")

    URLSession.shared.dataTask(with: request) { data, _, _ in
        guard let data = data,
              let result = try? JSONDecoder().decode(EventsResponse.self, from: data) else { return }

        for event in result.data.events {
            handleEvent(event)  // UI更新
        }
    }.resume()
}