페이지 URL 강화 플러그인

Page URL Enrichment 플러그인은 브라우저 SDK가 amplitude.track()를 통해 추적하는 모든 이벤트에 페이지 URL 관련 속성을 자동으로 추가합니다. 이 설정은 자동 캡처된 이벤트에는 영향을 주지 않습니다. 이 플러그인은 현재 페이지와 이전 페이지 탐색에 대한 상황별 정보로 이벤트 데이터를 보강하므로 사용자 여정 분석과 페이지 전환을 이해하는 데 도움이 됩니다.

기본적으로 활성화됨

브라우저 SDK 버전 2.x부터 자동 캡처는 기본적으로 이 플러그인을 활성화합니다. 사용자 지정 구성을 원하거나 자동 캡처를 완전히 비활성화한 경우에만 이를 수동으로 설치하십시오.

플러그인을 사용할 때는 다음 사항에 유의하십시오.

플러그인이 활성화되면 페이지 변경 사항을 추적하기 시작합니다.
세션 저장소는 상태를 유지하므로 동일한 세션 내에서 페이지를 새로 고쳐도 이전 페이지 정보가 유지됩니다.
이 플러그인은 기존의 다중 페이지 응용 프로그램과 단일 페이지 응용 프로그램 모두에서 작동합니다.
세션 저장소를 사용할 수 없는 경우에도 플러그인은 계속 작동하지만 이전 페이지 추적에는 제한이 있을 수 있습니다.

설치

npm 또는 yarn를 사용하여 npm 레지스트리에서 이 패키지를 설치하십시오.

bash

# npm
npm install @amplitude/plugin-page-url-enrichment-browser
# yarn
yarn add @amplitude/plugin-page-url-enrichment-browser

사용법

자동 캡처와 함께 기본적으로 활성화

브라우저 SDK 2.x 버전의 자동 캡처는 이 플러그인을 자동으로 활성화합니다. 사용자 지정 구성을 원하거나 자동 캡처를 완전히 비활성화한 경우에만 아래의 수동 설치 단계를 사용하십시오.

이 플러그인은 Amplitude 브라우저 SDK 상에서 작동하며 모든 이벤트에 페이지 URL 보강 속성을 추가합니다. 이 플러그인을 사용하려면 @amplitude/analytics-browser 버전 v2.0.0 이상을 사용해야 합니다.

페이지 URL 보강 비활성화

자동 페이지 URL 보강을 비활성화하려면 autocapture.pageUrlEnrichment를 false로 설정하십시오.

typescript

import * as amplitude from "@amplitude/analytics-browser";
amplitude.init("YOUR_API_KEY", {
  autocapture: {
    pageUrlEnrichment: false,
  },
});

수동 플러그인 설치

사용자 지정 구성이 필요하거나 자동 캡처를 완전히 비활성화한 경우 플러그인을 수동으로 설치하십시오.

1. Amplitude 패키지 가져오기

typescript

import * as amplitude from "@amplitude/analytics-browser";
import { pageUrlEnrichmentPlugin } from "@amplitude/plugin-page-url-enrichment-browser";

2. 페이지 URL 강화 플러그인을 인스턴스화하십시오.

플러그인은 플러그인 구성을 위해 Object 유형의 선택적 매개변수를 허용합니다.

typescript

const pageUrlEnrichment = pageUrlEnrichmentPlugin();

3. Amplitude SDK에 플러그인 설치

typescript

amplitude.add(pageUrlEnrichment);

4. Amplitude SDK 초기화

typescript

amplitude.init("API_KEY");

이벤트 속성

이 플러그인은 모든 이벤트에 다음 속성을 추가합니다.

속성	설명
`[Amplitude] Page Domain`	웹 사이트의 호스트 이름(`location.hostname`).
`[Amplitude] Page Location`	웹 사이트의 전체 URL(`location.href`).
`[Amplitude] Page Path`	웹 사이트의 경로 이름(`location.pathname`).
`[Amplitude] Page Title`	웹 사이트의 제목(`document.title`). 제목을 마스킹 처리하려면 `<title>` 요소에 `data-amp-mask` 속성을 추가합니다.
`[Amplitude] Page URL`	쿼리 매개 변수를 제외한 웹 사이트의 URL입니다.
`[Amplitude] Previous Page Location`	사용자가 방문한 이전 페이지의 URL입니다.
`[Amplitude] Previous Page Type`	이전 페이지 유형의 분류입니다.

이전 페이지 유형 분류

[Amplitude] Previous Page Type 속성은 다음 논리에 따라 이전 페이지를 분류합니다.

direct: 이전 페이지나 리퍼러가 없습니다(사용자가 직접 사이트에 왔음).
internal: 이전 페이지가 동일한 도메인(동일한 호스트 이름)에서 왔습니다.
external: 이전 페이지가 다른 도메인에서 왔습니다.

플러그인 작동 방식

페이지 URL 강화 플러그인:

페이지 변경 추적: pushState, replaceState 및 popstate와 같은 네비게이션 이벤트를 모니터링하여 단일 페이지 애플리케이션의 페이지 변경을 감지합니다.
네비게이션 기록 저장: 세션 저장소를 사용하여 페이지 탐색 전반에 걸쳐 현재 및 이전 페이지 URL을 유지합니다.
모든 이벤트를 강화: 브라우저 SDK가 추적하는 모든 이벤트에 페이지 URL 속성을 추가합니다.
기존 속성 유지: 이벤트에 이미 페이지 URL 속성 중 하나라도 있는 경우 플러그인은 기존 값을 유지합니다.

페이지 제목 마스킹

페이지 URL 강화 플러그인은 페이지 <title> 요소의 data-amp-mask 속성을 통해 페이지 제목 마스킹을 지원합니다. 이 속성은 사용자가 페이지 제목을 위장했으며 [Amplitude] Page Title 속성에서 마스킹된 값을 사용하려고 한다는 것을 플러그인에게 알려줍니다.

예를 들면 다음과 같습니다.

html

<head>
  <!-- Masked page title
  This page title is fully masked in the `[Amplitude] Page Title`
  of all events enriched by the Page URL Enrichment plugin on this page
  Page title: "*****"
  -->
  <title data-amp-mask>Private Dashboard For John Doe</title>
</head>

페이지 URL 강화 플러그인은 플러그인이 강화하는 모든 이벤트에서 실제 페이지 제목을 마스킹된 값(*****)으로 바꿉니다.

세션 스토리지

이 플러그인은 세션 저장소를 사용하여 페이지 변경 사항 간에 탐색 정보를 유지합니다. 플러그인은 다음 키를 사용하여 데이터를 저장합니다.

AMP_URL_INFO: 현재 페이지 URL과 이전 페이지 URL을 저장합니다.

세션 저장소는 동일한 세션 첫 사용 후 단일 페이지 애플리케이션 탐색 또는 페이지 새로 고침 다음 기간동안 이전 페이지 정보가 유지되도록 보장합니다.

예제

Page URL Enrichment 플러그인을 설정하는 방법에 대한 전체 예는 다음과 같습니다.

typescript

import * as amplitude from "@amplitude/analytics-browser";
import { pageUrlEnrichmentPlugin } from "@amplitude/plugin-page-url-enrichment-browser";
// Create the plugin instance
const pageUrlEnrichment = pageUrlEnrichmentPlugin();
// Add the plugin to Amplitude
amplitude.add(pageUrlEnrichment);
// Initialize Amplitude
amplitude.init("YOUR_API_KEY");
// Track an event - it automatically includes page URL properties
amplitude.track("Button Clicked", {
  button_name: "Sign Up",
});

추적되는 이벤트에는 다음과 같은 속성이 포함됩니다.

json

{
  "event_type": "Button Clicked",
  "event_properties": {
    "button_name": "Sign Up",
    "[Amplitude] Page Domain": "example.com",
    "[Amplitude] Page Location": "https://example.com/signup?utm_source=google",
    "[Amplitude] Page Path": "/signup",
    "[Amplitude] Page Title": "Sign Up - Example",
    "[Amplitude] Page URL": "https://example.com/signup",
    "[Amplitude] Previous Page Location": "https://example.com/home",
    "[Amplitude] Previous Page Type": "internal"
  }
}

이 내용이 도움이 되었나요?