行動イベント

ユーザーの行動イベントを送信することで、パーソナライゼーションの精度が向上します。イベント送信は無料（0 クレジット）です。

イベントの送信

POST /v1/events
{
  "events": [
    {
      "type": "click",
      "session_id": "YOUR_SESSION_ID",
      "user_id": "user-12345",
      "tracking_token": "eyJhbGciOi...",
      "occurred_at": "..."
    }
  ]
}

レスポンスは 202 Accepted です（非同期処理）。リクエスト/レスポンスの詳細は API リファレンスの POST /events をご覧ください。

イベント種別と必須フィールド

イベント	説明	`tracking_token`	`user_id`
`session_start`	アプリ起動	-	任意（送信時はユーザー自動作成）
`login`	ログイン	-	必須
`logout`	ログアウト	-	任意
`impression`	記事表示（ビューポート内）	必須	任意（送信時はユーザー自動作成）
`click`	記事タップ	必須	任意（送信時はユーザー自動作成）
`return`	記事から戻る（滞在時間計測）	必須	任意（送信時はユーザー自動作成）
`share`	シェア	必須	任意（送信時はユーザー自動作成）
`like`	高評価	必須	任意（送信時はユーザー自動作成）
`dislike`	低評価	必須	任意（送信時はユーザー自動作成）

tracking_token は GET /v1/feed のレスポンスに含まれる値をそのまま使用してください。

user_id の制約: 最大 128 文字、A-Za-z0-9._:@|+=- のみ使用可能。空白・タブ・絵文字・制御文字・パス区切り (/, \) は不可。UUID/ULID/数値ID 推奨。Auth0 (auth0|abc) やメールアドレス形式も技術的には許容します。違反した場合は 400 Validation Error を返します。

推奨する送信パターン

パーソナライゼーションに特に寄与するイベント：

session_start — アプリ起動時。session_id にセッションを一意に識別する文字列を指定（UUID v4 推奨、ULID 等も可）。同じ session_id を異なるユーザー間で共有しないでください
login — ログイン完了時。user_id 必須
click — 記事タップ時。tracking_token 必須
impression — フィードの各記事がビューポートに表示されたタイミング

バッチ送信

events 配列に最大 100 件のイベントをまとめて送信できます。アプリ側でイベントをバッファリングし、定期的にまとめて送信することを推奨します。

サイズ上限

制約	上限	超過時の挙動
リクエストボディ全体	2 MiB	`413 Payload Too Large`
`events` 配列の件数	100 件	`400 Validation Error`
1イベントの `metadata` JSON バイト長	4096 バイト	`400 Validation Error` (`metadata: must not exceed 4096 bytes`)

metadata の上限はクライアントが送信した JSON のバイト長で評価されます（インデントや改行を含めた送信時のサイズがそのままカウントされます）。

metadata は JSON object である必要があります。object 以外の値（文字列・配列等）は 400 Validation Error（metadata: must be a JSON object）になります（null は省略と同じ扱いで受理されます）。

metadata の JSON に null 文字のエスケープ（\u0000）が現れる場合は 400 Validation Error（metadata: must not contain null bytes）、対になっていない UTF-16 サロゲートエスケープ（\ud800 単独など）が現れる場合は 400 Validation Error（metadata: must not contain unpaired UTF-16 surrogate escapes）になります。いずれも user_attributes の内外を問わず、キー名・入れ子の値も対象です。

session_id も同様に、null 文字を含む場合は 400 Validation Error（session_id: must not contain null bytes）になります。

ボディサイズ上限は HTTP プロトコル層で適用されるため、chunked transfer encoding を用いても回避できません。

`occurred_at` の受理範囲

occurred_at はイベントの発生時刻を RFC 3339 で指定する必須フィールドです。受理されるのは 過去 30 日以内〜未来 1 日以内 の範囲に収まる値のみです。

値	挙動
過去 30 日以内〜未来 1 日以内	受理（`202 Accepted`）
それ以外	`400 Validation Error` (`occurred_at: must be within the last 30 days and no more than 1 days in the future`)

未来側の 1 日はクライアント端末の時計のずれを吸収するための余裕です。範囲外の値がサーバー側で現在時刻に補正されることはありません（分析データを書き換えないため）。

オフライン時にイベントをバッファリングする実装では、次の点に注意してください。

バッファに溜めたイベントは 30 日以内に送信してください。それを超えたイベントは送信しても拒否されます。
タイムスタンプが未設定のまま数値 0 として組み立てられると 1970-01-01T00:00:00Z が送信され、拒否されます。送信前に occurred_at が実際に設定されていることを確認してください。
1 リクエスト内の 1 件でも範囲外だと、そのバッチ全体が 400 になります。
大幅に遅れて届いたイベントは受理・保存されますが、管理画面の日次集計には反映されない場合があります。集計は直近数日分を再計算する方式のため、それより古い日付のイベントは再集計の対象外になります。

login イベントの metadata.user_attributes でユーザー属性を送信できます。送信された属性はユーザープロフィールにマージされ、パーソナライゼーションに活用されます。

user_attributes はユーザー管理 API の properties と同一の制約でバリデーションされます。well-known フィールド（gender / birth_year / area_names / area_level / timezone / registered_at など）の制約違反、object 以外の値、50 を超えるキー数は、イベント種別を問わず 400 Validation Error になります（null は省略と同じ扱いで受理されます）。制約の一覧は API リファレンスの POST /events をご覧ください。未知のキーは自由に追加できます。

{
  "events": [
    {
      "type": "login",
      "session_id": "YOUR_SESSION_ID",
      "user_id": "user-12345",
      "occurred_at": "...",
      "metadata": {
        "user_attributes": {
          "gender": "female",
          "birth_year": 1990,
          "area_names": ["渋谷"],
          "area_level": "station"
        }
      }
    }
  ]
}

注記

user_id を含むあらゆる行動ログ（login / session_start だけでなく click / impression / return / share / like / dislike も含む）で、未登録ユーザーはバックグラウンドで自動作成されます。session_start を送信せずに click 等を送信したケース（イベント順序の race）でも欠損が発生しないことを保証します。詳細はユーザー管理をご覧ください。

イベントの送信​

イベント種別と必須フィールド​

推奨する送信パターン​

バッチ送信​

サイズ上限​

occurred_at の受理範囲​

login イベントでのユーザー属性送信​