세션 리플레이 API

인증 및 요청 요구 사항

• 모든 엔드포인트는 HTTP 기본 인증을 사용합니다. 프로젝트의 API 키를 사용자 이름으로 사용하고 비밀 키를 암호로 사용하십시오.
• 이 project_id 매개변수는 필요하지 않습니다. 인증된 API 키는 프로젝트를 식별합니다.
• 미리 서명된 파일 URL은 15분 후에 만료됩니다.
• 페이지 매기기 커서는 불투명한 문자열입니다. 그것들을 만들거나 수정하지 마십시오. 이전 응답의 next_page_token을(를) 그대로 전달합니다.
• 이 sort_order 매개 변수는 페이지화된 요청의 모든 페이지에서 일관적이어야 합니다. sort_order=desc 가 포함된 asc 요청에서 page_token을(를) 전달하면 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을(를) 무시하고 항상 null을(를) next_page_token(으)로 반환합니다.

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 파일에는 두 가지 압축 해제 단계가 필요합니다.

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의 포크를 사용하십시오. 포크에는 업스트림 버전과 호환되지 않을 수 있는 수정 사항이 포함되어 있기 때문입니다.

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

상태 및 오류 코드