셀프 호스팅 세션 리플레이 SDK

셀프 호스팅을 사용하면 Amplitude SDK 파일을 제공하고 amplitude.com가 아닌 자체 도메인을 통해 API 호출을 라우팅할 수 있습니다. 셀프 호스팅을 선택해야 하는 두 가지 주요 이유는 다음과 같습니다.

• 광고 차단 프로그램 우회: 많은 브라우저 확장 프로그램과 추적 방지 도구는 amplitude.com 도메인에 대한 요청을 차단합니다. 자신의 도메인을 통해 라우팅하면 차단을 피할 수 있습니다.
• 데이터 상주/컴플라이언스: 조직에서는 데이터가 Amplitude에 도달하기 전에 자체 인프라를 떠나지 않도록 요구할 수 있습니다.

셀프 호스팅에는 두 가지 독립적인 부분이 있습니다.

1. SDK 스크립트 호스팅: 자체 CDN 또는 정적 파일 서버에서 SDK .js 파일을 제공하십시오(브라우저만 해당; npm/번들 설치는 이 단계를 건너뛰십시오).
2. 프록시 API 호출: SDK 네트워크 요청이 Amplitude의 수집 엔드포인트에 도달하기 전에 자체 서버를 통해 전달됩니다.

하나 또는 두 부분 모두를 독립적으로 구현할 수 있습니다.

1부: SDK 스크립트를 셀프 호스팅하기

SDK 스크립트의 셀프 호스팅은 <script> 태그를 통해 로드되는 브라우저 기반 SDK에 적용됩니다. npm을 통해 설치하고 직접 SDK를 번들로 구성하는 경우, 2부: 프록시 API 호출로 건너뛰십시오.

SDK 파일 가져오기

옵션 A: Amplitude의 CDN에서 다운로드:

# Session Replay Plugin (latest: 1.28.1)
curl -O https://cdn.amplitude.com/libs/plugin-session-replay-browser-1.28.1-min.js.gz
# Session Replay Standalone SDK (latest: 1.39.0)
curl -O https://cdn.amplitude.com/libs/session-replay-browser-1.39.0-min.js.gz
# Browser SDK (latest: 2.42.0 — only needed if also self-hosting analytics)
curl -O https://cdn.amplitude.com/libs/analytics-browser-2.42.0-min.js.gz

옵션 B: npm에서 가져오기:

pnpm pack @amplitude/plugin-session-replay-browser@1.28.1
# or
pnpm pack @amplitude/session-replay-browser@1.39.0

pnpm pack 명령은 .tgz tar 파일을 생성합니다. tar 파일을 추출하고 package/lib/scripts/ 디렉터리 내에서 UMD 번들을 찾습니다(예: plugin-session-replay-browser-1.28.1.umd.js). 해당 파일을 사용자 고유의 출처에서 제공하십시오.

최신 버전 번호는 다음을 확인하십시오.

• npm: @amplitude/plugin-session-replay-browser
• npm: @amplitude/session-replay-browser

파일 제공

자체 CDN 또는 정적 파일 서버에 파일을 호스팅한 다음 <script> 태그를 업데이트하십시오.

<!-- Before -->
<script src="https://cdn.amplitude.com/libs/analytics-browser-2.42.0-min.js.gz"></script>
<script src="https://cdn.amplitude.com/libs/plugin-session-replay-browser-1.28.1-min.js.gz"></script>
<!-- After -->
<script src="https://assets.yourdomain.com/libs/analytics-browser-2.42.0-min.js.gz"></script>
<script src="https://assets.yourdomain.com/libs/plugin-session-replay-browser-1.28.1-min.js.gz"></script>

2부: 프록시 API 호출

SDK 네트워크 요청을 자체 서버를 통해 라우팅하여 해당 요청이 amplitude.com 엔드포인트로 직접 이동하지 않도록 하십시오. 프록시 서버는 요청을 수신하여 Amplitude의 기본 엔드포인트로 전달한 다음 Amplitude의 응답을 변경하지 않고 반환합니다.

프록시의 작동 방식

최소한의 프록시 구현은 다음과 같아야 합니다.

1. 사용자 지정 URL에서 SDK의 요청을 수락합니다.
2. 전체 요청 본문과 모든 헤더(Host 제외)를 해당 Amplitude 엔드포인트로 전달합니다.
3. 상태 코드, 헤더, 본문을 포함하여 SDK에 대한 Amplitude의 응답을 변경되지 않은 상태로 반환합니다.

프록시는 투명해야 합니다. 요청 또는 응답 페이로드를 제거, 수정 또는 버퍼링하지 마십시오. SDK는 재시도를 처리하므로 프록시가 이를 처리할 필요가 없습니다.

분석 SDK

적용 대상: 브라우저 SDK, Android(Kotlin) SDK, iOS(Swift) SDK, React Native SDK, Node.js SDK, Python SDK, Go SDK.

serverUrl 구성 옵션을 사용하여 SDK가 프록시를 사용하도록 지정하십시오:

amplitude.init('API_KEY', {
  serverUrl: 'https://analytics.yourdomain.com/2/httpapi'
});

프록시는 요청을 적절한 Amplitude 엔드포인트로 전달해야 합니다.

대용량 환경에는 배치 엔드포인트를 사용하십시오. 배치 모드를 활성화하려면 SDK에서 useBatch: true을(를) 설정하고 배치 엔드포인트로 전달되는 프록시 경로를 serverUrl로 지정하십시오:

amplitude.init('API_KEY', {
  useBatch: true,
  serverUrl: 'https://analytics.yourdomain.com/batch'
});

원격 구성 프록시(브라우저 SDK 2에만 해당):

브라우저 SDK 2는 원격 구성을 별도로 가져옵니다. 이러한 요청도 프록시하려면 remoteConfig.serverUrl 옵션을 사용하십시오.

amplitude.init('API_KEY', {
  serverUrl: 'https://analytics.yourdomain.com/2/httpapi',
  remoteConfig: {
    serverUrl: 'https://analytics.yourdomain.com/config'
  }
});

세션 리플레이: 브라우저(플러그인 및 독립형 SDK)

세션 리플레이은 두 개의 별도의 엔드포인트를 사용합니다. 각 항목을 독립적으로 재정의할 수 있습니다.

세션 리플레이 플러그인:

sessionReplayPlugin({
  trackServerUrl: 'https://replay.yourdomain.com/sessions/v2/track',
  configServerUrl: 'https://replay.yourdomain.com/config'
});

세션 리플레이 독립형 SDK:

sessionReplay.init('API_KEY', {
  trackServerUrl: 'https://replay.yourdomain.com/sessions/v2/track',
  configServerUrl: 'https://replay.yourdomain.com/config'
});

세션 리플레이: 모바일(Android, iOS, React Native)

모바일 세션 리플레이 플러그인은 사용자 지정 프록시 URL을 지원하지 않습니다. 유일한 라우팅 옵션은 Amplitude의 미국과 EU 데이터 센터 간을 전환하는 serverZone입니다. 데이터는 여전히 Amplitude의 서버로 직접 흐르며 자체 인프라를 통과하지 않습니다.

// Android — set on the Amplitude SDK configuration
serverZone = ServerZone.EU

// iOS — set on the Amplitude SDK configuration
serverZone: .EU

콘텐츠 보안 정책(CSP)

앱이 콘텐츠 보안 정책을 설정한 경우 자체 호스팅 파일 및 프록시된 엔드포인트로 전환할 때 업데이트하십시오.

예제 CSP(완전 자체 호스팅):

Content-Security-Policy: script-src 'self' https://assets.yourdomain.com; connect-src 'self' https://analytics.yourdomain.com https://replay.yourdomain.com; worker-src 'self' blob:;

귀하의 프록시는 Amplitude의 미국 또는 EU 엔드포인트로의 라우팅을 처리하므로 CSP는 귀하의 고유 도메인만 참조하면 됩니다. 동일한 정책이 두 지역 모두에 적용됩니다.