Session Replay API

認証とリクエストの要件

• すべてのエンドポイントでHTTP Basic認証を使用しています。プロジェクトのAPIキーをユーザー名として使用し、シークレットキーをパスワードとして使用してください。
• project_idパラメータは必要ありません。認証済みのAPIキーによってプロジェクトを識別します。
• 事前署名済みファイルのURLは15分後に期限切れになります。
• ページネーションカーソルは不透明な文字列です。構築したり変更したりしないでください。前のレスポンスで返されたnext_page_tokenをそのまま渡してください。
• sort_orderパラメータは、ページネーションリクエストのすべてのページで一貫して同じである必要があります。 ascリクエストからのpage_tokenをsort_order=descとともに渡すと、400エラーが返されます。
• amplitude_idとreplay_idは相互に排他的です。両方を渡すと、400エラーが返されます。
• replay_idとpage_tokenは相互に排他的です。両方を渡すと、400エラーが返されます。
• 各replay_idの値にはdevice_id/session_id形式を使用する必要があります。先頭または末尾にスラッシュを付けると、400エラーが返されます。
• リクエストごとに最大100個のreplay_id値を渡すことができます。101個を超えて渡すと、400エラーが返されます。
• amplitude_idは有効な整数でなければなりません。数値以外の値の場合、400エラーが返されます。
• replay_idを使用する場合、APIはpage_sizeを無視し、next_page_tokenに対して常にnullを返します。

EU域内のデータレジデンシー

EU域内のデータレジデンシーの場合は、https://amplitude.comではなくhttps://analytics.eu.amplitude.comをベースURLとして使用してください。例えば：

• セッションのリプレイをリストアップする：GET https://analytics.eu.amplitude.com/api/1/session-replays
• セッションリプレイファイルを取得する：GET https://analytics.eu.amplitude.com/api/1/session-replays/files

セッションのリプレイをリストアップする

認証済みプロジェクトのセッションリプレイの、ページネーションされたリストを返します。

GET https://amplitude.com/api/1/session-replays

curl --location 'https://amplitude.com/api/1/session-replays' \
-u '{api_key}:{secret_key}'

クエリパラメータ

レスポンス

{
  "session_replays": [
    {
      "replay_id": "string",
      "session_id": "string",
      "device_id": "string",
      "amplitude_id": 123456,
      "start_time": "2024-01-01T00:00:00Z",
      "end_time": "2024-01-01T00:05:00Z",
      "retention_in_days": 90
    }
  ],
  "next_page_token": "string | null"
}

セッションリプレイファイルを取得する

特定のリプレイに属するイベントファイルの、事前署名付きS3 URLのページネーションされたリストを返します。各URLはrrwebイベントのgzip圧縮されたJSON配列を指しています。Amplitudeは開始時間をエンコードするキーで、ファイルを並び替えます。

GET https://amplitude.com/api/1/session-replays/files

curl --location 'https://amplitude.com/api/1/session-replays/files?replay_id={device_id}%2F{session_id}' \
-u '{api_key}:{secret_key}'

クエリパラメータ

レスポンス

{
  "files": [
    "https://s3.amazonaws.com/...presigned-url-1...",
    "https://s3.amazonaws.com/...presigned-url-2..."
  ],
  "next_page_token": "string | null"
}

リプレイファイルを解凍して解析する

各ファイルの形式は、リクエストしたversionによって異なります。

バージョン 3

各ファイルはgzip圧縮を使用します。ファイルを解凍して、rrwebプレーヤーに渡す準備が整ったrrwebイベントのJSON配列を取得します。

async function fetchReplayEvents(fileUrl) {
  const response = await fetch(fileUrl);
  // The response is gzip-compressed; fetch decompresses automatically in browsers.
  // In Node.js 18+, use the DecompressionStream API or the zlib module.
  const buffer = await response.arrayBuffer();
  const text = new TextDecoder().decode(buffer);
  return JSON.parse(text); // array of rrweb events
}

結果はrrwebイベントのJSON配列です：

[
  { "type": 4, "data": { "href": "https://example.com", "width": 1440, "height": 900 }, "timestamp": 1700000000000 },
  { "type": 2, "data": { ... }, "timestamp": 1700000000050 },
  ...
]

バージョン 2

バージョン2ファイルの解凍には、次の2つのステップを実行する必要があります。

1. gzipファイルを解凍し、JSONパースを行うと、パックされた文字列の配列になります。
2. 各文字列をzlibで解凍します。各要素はJSONエンコードされ、zlib圧縮（DEFLATE）されたバイナリペイロードであり、rrwebイベントオブジェクトになります。

const zlib = require("zlib");
async function fetchReplayEventsV2(fileUrl) {
  const response = await fetch(fileUrl);
  const buffer = Buffer.from(await response.arrayBuffer());
  // Step 1: gzip decompress the file, then JSON parse → array of packed strings
  const packedStrings = JSON.parse(zlib.gunzipSync(buffer).toString("utf8"));
  // Step 2: unpack each string
  return packedStrings.map((packed) => {
    // Each packed string is itself a JSON string whose value is a latin1-encoded
    // binary blob of zlib-compressed event data.
    const compressedBinary = JSON.parse(packed);
    const buf = Buffer.from(compressedBinary, "latin1");
    return JSON.parse(zlib.inflateSync(buf).toString("utf8")); // rrweb event
  });
}

イベントをリプレイする

フルセッションをリプレイするには、リプレイ用のすべてのファイルを順番に取得し、各ファイルを解凍し、イベント配列を連結して、その結果をAmplitudeのrrwebプレーヤーに渡します。アップストリーム版のrrwebではなくAmplitudeのforkを使用してください。このforkにはアップストリーム版と互換性がない可能性のある修正が含まれています。

const events = (await Promise.all(fileUrls.map(fetchReplayEvents))).flat();
rrweb.replay({ events, root: document.getElementById("player") });

ステータスとエラーコード