For AI agents: a documentation index is available at /docs/llms.txt. Append .md to any page URL for markdown, or send Accept: text/markdown.
SDK 미들웨어
미들웨어를 사용하면 모든 이벤트에서 일련의 사용자 지정 코드를 실행하여 Amplitude를 확장할 수 있습니다. 이 패턴은 유연합니다. 이를 사용하여 이벤트 보강, 트랜스포메이션, 필터링, 타사 대상으로의 라우팅 등을 지원할 수 있습니다.
유지 관리 SDK는 유지 관리 브라우저 SDK 및 기존 Ampli를 제외하고 미들웨어를 지원합니다. 플러그인은 최신 SDK 및 Ampli 버전의 미들웨어를 대체합니다.
미들웨어 구조
함수 시그니처
각 미들웨어는 다음과 같은 서명을 가진 간단한 함수입니다:
/**
* A function to run on the Event stream (each logEvent call)
*
* @param payload The `payload` contains the `event` to send and an optional `extra` that lets you pass custom data to your own middleware implementations.
* @param next Function to run the next middleware in the chain, not calling next will end the middleware chain
*/
function (payload: MiddlewarePayload: next: MiddlewareNext): void;
미들웨어의 유형:
MiddlewarePayload.event- 유형: 이벤트.
- 설명: 전송할 이벤트 데이터입니다. 이벤트는 플랫폼에 따라 다를 수 있습니다.
MiddlewarePayload.extra- 유형: { [x: string]: any }입니다.
- 설명: 사용자가 추가 데이터를 미들웨어에 전달할 수 있도록 해주는 비정형 객체입니다.
MiddlewareNext- 유형: (payload: MiddlewarePayload) => void입니다.
- 설명: 각 미들웨어의 끝에서 실행되어 체인의 다음 미들웨어를 호출하는 함수입니다.
큐의 다음 미들웨어를 호출하려면 next 함수를 사용하십시오. 미들웨어 체인을 계속하려면 next(payload)를 호출해야 합니다. 미들웨어가 next를 호출하지 않는 경우 현재 미들웨어가 완료된 후 이벤트 처리가 중지됩니다.
페이로드 사용자 지정
이벤트 필드에 대한 미들웨어 액세스는 플랫폼에 따라 다를 수 있습니다. 포괄적인 액세스를 위해서는 Amplitude가 최신 Ampli 버전으로 업데이트하고 플러그인 기능을 사용할 것을 권장합니다.
Browser Ampli의 경우 payload 아래에 액세스할 수 있는 키는 다음과 같습니다.
event.event_type- 유형: 문자열.
- 설명: 이벤트 이름입니다.
event.event_properties- 유형: { [key: string]: any }.
- 설명: 이벤트 속성입니다.
event.user_id- 유형: 문자열.
- 설명: 이벤트 수준의 사용자 ID입니다.
event.device_id- 유형: 문자열.
- 설명: 이벤트 수준의 장치 ID입니다.
event.user_properties- 유형: { [key: string]: any }.
- 설명: 이벤트 수준의 사용자 속성입니다.
extra- 유형: { [x: string]: any }입니다.
- 설명: 사용자 지정 데이터를 자체 미들웨어 구현에 전달할 수 있도록 해주는 추가 정보입니다.
다른 플랫폼의 경우 미들웨어는 포괄적인 조정을 위해 전체 Event JSON 객체에 액세스하고 수정할 수 있습니다. 전체 스키마에 대한 이벤트 배열 키 참조로 이동하십시오.
사용
Amplitude에 amplitude.addEventMiddleware()을(를) 사용하여 미들웨어를 추가하십시오. 원하는 만큼 미들웨어를 추가할 수 있습니다. 각 미들웨어는 추가한 순서대로 실행됩니다.
amplitude.addEventMiddleware(yourMiddleware());
미들웨어 예제
미들웨어를 사용하여 이벤트 속성을 수정하고, 데이터를 변환하고, 이벤트를 필터링하고, 타사 대상으로 라우팅하는 등의 작업을 수행할 수 있습니다.
필터링 미들웨어
amplitude.addEventMiddleware((payload, next) => {
const {eventType} = payload.event;
if (shouldSendEvent(eventType)) {
next(payload)
} else {
// event doesn't continue to following middleware or get sent to Amplitude
console.log(`Filtered event: ${eventType}`);
}
});
PII(개인 식별 정보) 제거
amplitude.addEventMiddleware((payload, next) => {
const { event } = payload;
if (hasPii(event.event_properties)) {
payload.event.event_properties = obfuscate(payload.event.event_properties);
}
next(payload);
});
이벤트 속성 강화
amplitude.addEventMiddleware((payload, next) => {
const { event } = payload;
if (needsDeviceId(event)) {
payload.event.deviceId = getDeviceId();
}
next(payload)
});
Ampli v1을 사용하여 이벤트 수준 그룹 전송
이 예제에서는 Ampli v1에서 이벤트 수준 그룹을 전송하는 방법을 보여줍니다. SDK에서 이벤트 수준 그룹을 전송하는 방식(Ampli 제외)은 다르게 작동합니다. 사용 방법에 대한 자세한 내용은 특정 SDK를 확인하십시오.
ampli.addEventMiddleware((payload, next) => {
const {event, extra} = payload;
if (event && extra && event.extra.groups) {
event.groups = event.extra.groups;
}
next(payload);
});
// Pass the event-level groups info through middleware extra when calling the tracking plan.
const extra = {groups: {"test_group_name": "test_group_value"}};
ampli.eventWithGroups({requiredNumber: 1.23, requiredBoolean: false}, extra);
다른 서비스로 데이터 전달
import amplitude from 'amplitude/sdk'
import adroll from 'adroll';
import segment from 'segment';
import snowplow from 'snowplow';
amplitude.addEventMiddleware((payload, next) => {
const { event, extra } = payload;
segment.track(event.event_type, event.event_properties, { extra.anonymousId })
adroll.track();
snowplow.track(event.event_type, event.event_properties, extra.snowplow.context);
// next();
});
클라이언트 측 검증 사용
amplitude.addEventMiddleware((payload, next) => {
if (isDevelopment && !SchemaValidator.isValid(payload.event)) {
throw Error(`Invalid event ${event.event_type}`);
}
next(payload);
});
지원되는 SDK
이 내용이 도움이 되었나요?