커스텀 Enrichment 플러그인

Custom Enrichment 플러그인은 브라우저 SDK가 추적하는 모든 이벤트에 대해 SDK가 이벤트를 업로드하기 전에 보강 기능을 실행합니다. Amplitude는 해당 기능을 프로젝트의 원격 구성에 저장하므로, 사이트의 새 빌드를 출시하지 않고도 해당 기능의 동작을 변경할 수 있습니다.

이 플러그인은 기본적으로 꺼져 있습니다. customEnrichment 구성 옵션을 사용하여 이를 활성화하세요.

이 플러그인은 사용자가 작성한 플러그인에는 영향을 주지 않습니다

이 플러그인은 사용자가 amplitude.add()로 추가하는 커스텀 플러그인과는 별개입니다. customEnrichment의 활성화 또는 비활성는 사용자 고유의 플러그인에는 아무런 영향을 주지 않으며, 사용자 고유의 플러그인은 이 플러그인을 활성화했는지 여부에 관계없이 계속 작동합니다.

요구 사항

@amplitude/analytics-browser 버전 2.37.0 이상.
원격 구성이 활성화되었습니다. SDK는 기본적으로 원격 구성을 가져옵니다. remoteConfig.fetchRemoteConfig를 false로 설정하면 플러그 인은 로드되지만 함수를 수신하지 않으므로 모든 이벤트는 변경되지 않습니다. 원격 구성을 참조하십시오.
프로젝트의 원격 구성에 정의된 보강 기능입니다. SDK는 로컬 구성에서 함수를 읽지 않습니다.

플러그인 활성화

SDK를 초기화할 때 customEnrichment를 true로 설정하세요.

import * as amplitude from "@amplitude/analytics-browser";
amplitude.init(AMPLITUDE_API_KEY, {
  customEnrichment: true,
});

이름	설명	기본값
`customEnrichment`	`boolean`. SDK가 Custom Enrichment 플러그인을 추가하는지 여부입니다.	`false`

Amplitude의 원격 설정은 플러그인을 활성화할 수도 있습니다. 단, 한 가지 예외가 있습니다. 초기화 시 customEnrichment: false로 설정하면 원격 설정으로 이를 재활성화할 수 없습니다. 원격 구성으로 플러그인을 제어하려면 false로 설정하는 대신 생략해 놓으세요.

SDK는 원격 구성에서만 보강 기능을 읽습니다. 로컬 설정에서 함수 본문을 전달해도 아무런 효과가 없습니다.

플러그인 작동 방식

설치 시 플러그인은 프로젝트의 원격 구성에서 configs.analyticsSDK.browserSDK.customEnrichment 키를 구독합니다.
원격 구성이 함수 본문을 제공하면 플러그인은 이를 이벤트를 받아 이벤트를 반환하는 함수로 평가합니다.
이 플러그인은 이벤트가 SDK의 보강 단계를 통과할 때 자동으로 캡처된 이벤트를 포함하여 모든 이벤트에 대해 해당 기능을 실행합니다.
원격 구성이 유효한 함수 본문을 제공하지 않을 경우 플러그인은 모든 이벤트를 변경 없이 전달합니다.

플러그인은 원격 구성을 한 번 읽는 것이 아니라 구독하므로 보강 기능에 대한 업데이트는 페이지를 다시 로드하지 않고 활성 세션에 도달합니다.

반환 값

보강 함수가 반환하는 내용에 따라 Amplitude가 수신하는 내용이 결정됩니다.

이벤트를 반환: SDK는 반환된 이벤트를 업로드합니다. 이 방법은 함수가 속성을 추가, 변경 또는 제거하는 방법입니다.
아무것도 반환하지 않습니다. SDK는 이벤트를 삭제하고 이벤트는 Amplitude에 도달하지 않습니다. 이벤트를 반환하지 않는 보강 함수는 별도의 알림 없이 모든 트래픽을 삭제합니다.
오류가 발생합니다. SDK는 오류를 기록하고 원래의 강화되지 않은 이벤트를 업로드합니다.

구성된 함수 본문이 함수로 평가되지 않을 경우 플러그인은 오류를 기록하고 모든 이벤트를 변경되지 않은 채로 전달합니다.

콘텐츠 보안 정책

플러그인은 런타임 시 원격 구성에서 보강 기능을 평가합니다. 사이트에서 script-src를 제한하는 콘텐츠 보안 정책을 설정한 경우 해당 정책은 플러그인이 기능을 빌드할 수 있도록 unsafe-eval을 허용해야 합니다. 그렇지 않으면, 브라우저가 평가를 차단하고 플러그인이 오류를 기록하며 이벤트는 변경되지 않고 전달됩니다.

브라우저 SDK에 필요한 다른 정책 조정에 대해서는 콘텐츠 보안 정책(CSP)을 참조하십시오.

문제 해결

플러그인의 작업을 기록하려면 logLevel을 Debug로 설정하세요.

import * as amplitude from "@amplitude/analytics-browser";
amplitude.init(AMPLITUDE_API_KEY, {
  customEnrichment: true,
  logLevel: amplitude.Types.LogLevel.Debug,
});

로그 메시지	IT가 의미하는 것
`Adding custom enrichment plugin`	SDK가 플러그인을 활성화하고 추가했습니다.
`Installing @amplitude/plugin-custom-enrichment-browser`	플러그인이 설정을 시작했습니다.
`Remote config client is not provided, skipping remote config fetch`	플러그인은 원격 구성에 도달할 수 없으므로 이벤트를 변경하지 않은 채로 유지합니다. 원격 구성이 켜져 있는지 확인하십시오.
`Custom enrichment body did not evaluate to a function`	원격 구성은 기능이 아닌 본문을 제공했습니다. 이벤트는 변경되지 않고 전달됩니다.
`Could not create custom enrichment function`	플러그인은 본문(body)을 평가할 수 없습니다. 콘텐츠 보안 정책을 확인하십시오.
`Could not execute custom enrichment function`	보강 기능에서 오류가 발생했습니다. SDK는 원본 이벤트를 업로드합니다.

로그에서 Adding custom enrichment plugin을 찾을 수 없다면, SDK가 플러그인을 활성화하지 않은 것입니다. 초기화 옵션에서 customEnrichment가 false로 설정되어 있지 않은지 확인하세요.

구글 태그 관리자

Amplitude 브라우저 SDK GTM 템플릿은 이 플러그인을 init 태그에 사용자 지정 Enrichment 플러그인 활성화 확인란으로 표시합니다. Google 태그 관리자(클라이언트)를 참조하십시오.

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