목차
고객 거래를 충성도 챌린지에 적용하려면 먼저 챌린지 서비스가 인식하는 Adobe 충성도 이벤트 형식이어야 합니다. POS 시스템, 모바일 앱, 전자 상거래 플랫폼 또는 기타 소스의 고객 이벤트는 일반적으로 고객의 데이터 스키마를 사용합니다. 이벤트 변환기 업스트림 시스템을 변경하지 않고 이 간격을 메웁니다.
개요
이벤트 정의은(는) 플랫폼에 다음 두 가지를 알려줍니다.
- 청구할 이벤트 - 들어오는 이벤트가 이 정의에 속함을 인식하는 방법(일치)
- 모양을 변경하는 방법 — 고객의 필드를 고객 충성도 이벤트 형식(변환)에 매핑하는 JSONata 식
조직당 여러 이벤트 정의를 구성할 수 있습니다. 플랫폼은 이를 순서대로 평가하고 일치하는 첫 번째 항목을 적용합니다. 정의와 일치하지 않는 이벤트는 기본 수집으로 전달됩니다(대체 — 기본 충성도 이벤트 참조).
Adobe 충성도 이벤트 형식
모든 이벤트 정의는 다음 형식의 JSON 개체를 생성해야 합니다. Challenge Service 프로세스에 대한 입력입니다.
{
"_id": "string — optional; used for duplicate detection if enabled",
"event_name": "string — used for internal metrics and reporting only (e.g. 'purchase', 'visit')",
"timestamp": "ISO 8601 date-time string — when the event occurred",
"utc_offset": "string — UTC offset of the store or device (e.g. '-07:00'); required for daypart matching",
"location_id": "string — optional; store or location identifier",
"transaction_id": "string — optional; dedup key for the transaction",
"loyalty_identity": {
"id": "string — the member's loyalty ID"
},
"item_list": [
{
"item_set": ["string", "..."], // one or more identifiers — SKU, category, event code, etc.
"item_name": "string — optional human-readable label",
"quantity": 1, // integer; how many units
"unit_price": 4.99, // float; price per unit
"sub_total": 4.99 // float; line total (quantity × unit_price)
}
]
}
필드 노트
loyalty_identityid을(를) 포함해야 합니다. 멤버의 충성도 ID입니다.item_listitem_settimestamputc_offset_idsub_total이벤트 정의 필드
guidname"Starbucks POS Purchase").xdmSchemaIdtransformer일치 작동 방식
데이터 수집 핵심 서비스(DCCS)를 통해 도착하는 이벤트는 XDM 스키마 참조를 봉투에 포함합니다. 플랫폼은 /body/xdmMeta/schemaRef/id에서 스키마 ID를 읽고 각 정의의 xdmSchemaId과(와) 비교합니다.
플랫폼은 조직의 이벤트 정의를 순서대로하고 첫 번째 일치를 적용합니다. 일치 항목이 발견되면 xdmEntity 본문이 변환기에 전달됩니다.
변환기에 쓰기
transformer 필드는 JSONata 식입니다. 수신 이벤트 JSON을 입력으로 받으며 유효한 Adobe 충성도 이벤트 개체를 반환해야 합니다.
대상 형식의 각 최상위 필드를 소스 이벤트의 해당 경로에 매핑합니다.
| code language-jsonata |
|---|
|
이 정의와 일치하는 모든 이벤트가 동일한 논리 활동을 나타내는 경우 event_name을(를) 하드코딩하십시오.
| code language-jsonata |
|---|
|
event_name은(는) 내부 지표 및 보고에 사용됩니다. 작업 필터로 사용되지 않습니다. 작업 자격은 이벤트 이름이 아닌 item_set 내용으로 결정됩니다.
DCCS 경로를 통해 도착하는 이벤트의 경우 멤버의 ID는 일반적으로 사용자 지정 테넌트 속성이 아닌 표준 XDM identityMap 필드에 전달됩니다. identityMap은(는) 네임스페이스로 처리된 맵입니다. 키 자체는 네임스페이스 이름이고 값은 id 개체 배열입니다.
| code language-jsonata |
|---|
|
-
네임스페이스 대체:
Email을(를) 조직이 충성도 멤버에 사용하는 네임스페이스(Loyalty,ECID,CRMID등)로 바꿉니다. 기본 충성도 프로필 ID가 있는 네임스페이스에서 항상 읽습니다. -
항상
[0]사용:identityMap.Email은(는) 배열입니다. 인덱스가 없으면 JSONata는 둘 이상의 ID가 있는 경우 단일 값이 아닌 시퀀스를 반환하며loyalty_identity.id은(는) 목록이 됩니다.[0]을(를) 사용하여 첫 번째 요소에 고정합니다. -
ID에 대한 사용자 지정 테넌트 필드를 사용하지 않음: 사용자 지정 필드 그룹은 전자 메일 형식 필드(예:
_yourtenant.identification.core.email)를 표시하는 경우가 있습니다. 샘플 데이터에서 값을 반환하고 올바른 것처럼 보이지만 프로덕션 이벤트에서는 비어 있는 경우가 많습니다. 신뢰할 수 있는 ID 원본은 항상identityMap입니다.
item_set 빌드 중item_set은(는) 문자열 식별자의 배열입니다. 과제 작업이 필터링할 수 있는 모든 필드 포함:
| code language-jsonata |
|---|
|
트랜잭션이 아닌 이벤트(체크 인, 설문 조사 완료, 사용자 지정 트리거)의 경우, 하나의 식별자로 충분합니다.
| code language-jsonata |
|---|
|
unit_price 매핑unit_price은(는) 단위당 가격이어야 합니다. 일부 소스 스키마에는 라인 합계(가격 × 수량)가 대신 저장됩니다. 출처 필드가 라인 합계인 경우 수량을 기준으로 나누어 단가를 구합니다.
| code language-jsonata |
|---|
|
소스 필드가 라인 합계인 경우에만 나눕니다. 이미 단가를 저장하고 있다면 직접 매핑해서 단가를 수량으로 나누면 묵묵히 잘못된 값이 나온다.
transaction_id 가져오기소스 이벤트에 거래 식별자가 포함되지 않은 경우 타임스탬프에서 안정적인 식별자를 파생할 수 있습니다.
| code language-jsonata |
|---|
|
이렇게 하면 ISO 타임스탬프가 에포크 밀리초로 변환되고 주어진 이벤트에 대한 결정적 값을 생성합니다. 사용 가능한 경우 플랫폼의 자체 ID 생성 기능을 사용하십시오.
전체 JSONata 함수 라이브러리를 사용할 수 있습니다. 유용한 예:
| code language-jsonata |
|---|
|
예
시나리오: 모바일 앱에서 체크 인 이벤트를 보냅니다. 라인 항목이 없습니다. 이벤트 자체가 자격을 갖춘 활동입니다.
들어오는 이벤트:
| code language-json |
|---|
|
이벤트 정의:
| code language-json |
|---|
|
서식 있는 변환기(가독성):
| code language-jsonata |
|---|
|
출력 Adobe 충성도 이벤트:
| code language-json |
|---|
|
포함/제외 제한이 없는 과제 작업은 이 이벤트를 자격 있는 방문으로 계산합니다. 단일 item_set 항목 ["store-checkin"]이(가) 모든 항목을 허용하는 모든 작업과 일치합니다.
시나리오: 판매 지점 시스템에서 트랜잭션 페이로드를 보냅니다. 각 라인 항목은 SKU를 포함하며 범주에 속합니다. 과제 작업은 SKU 및 범주를 사용하여 적합한 항목을 결정합니다.
들어오는 이벤트:
| code language-json |
|---|
|
이벤트 정의:
| code language-json |
|---|
|
서식 있는 변환기:
| code language-jsonata |
|---|
|
출력 Adobe 충성도 이벤트:
| code language-json |
|---|
|
include: ["BEVERAGE"]이(가) 있는 과제 작업에서는 커피 라인 항목의 자격을 확인하고(item_set에 "BEVERAGE"이(가) 포함되어 있음) 해당 작업에 대한 9.00달러의 지출을 누적합니다. 머핀 라인 항목은 제외됩니다.
시나리오: 이벤트가 Adobe Journey Optimizer을 통해 흐릅니다. 들어오는 이벤트는 알려진 스키마 ID가 있는 XDM 경험 이벤트입니다. 플랫폼은 경로/값 검사가 아닌 일치에 스키마 ID를 사용합니다.
들어오는 XDM 엔터티 본문(AJO 이벤트에서 추출된 xdmEntity):
| code language-json |
|---|
|
이벤트 정의:
| code language-json |
|---|
|
서식 있는 변환기:
| code language-jsonata |
|---|
|
참고: 이벤트가 XDM 스키마 ID로 일치하는 경우 변환기는 이벤트의
xdmEntity부분만 수신합니다(외부 AJO 봉투 아님). 변환기 표현식의 모든 경로는 XDM 엔티티 본문을 기준으로 합니다.
JSON 스키마 유효성 검사 추가(선택 사항)
플랫폼에서 변환을 시도하기 전에 들어오는 이벤트의 구조를 확인하도록 하려면 schema 필드를 JSON 문자열로 인코딩된 JSON 스키마 문서로 설정하십시오.
스키마 유효성 검사에 실패한 이벤트는 변환이 실행되기 전에 거부됩니다. 오류 응답에는 특정 유효성 검사 실패가 포함되므로 잘못된 업스트림 이벤트를 쉽게 진단할 수 있습니다.
| code language-json |
|---|
|
이벤트 정의의 schema 필드에 축소된 JSON 문자열로 이 스키마를 전달합니다.
대체 — 기본 충성도 이벤트
수신되는 이벤트와 일치하는 이벤트 정의가 없는 경우 플랫폼은 이를 기본 Adobe 충성도 이벤트로 직접 수집하려고 합니다. 페이로드가 이미 위에서 설명한 충성도 이벤트 형식을 준수하는 경우 변환기가 필요하지 않으며 이벤트가 그대로 적용됩니다. 이렇게 하면 이벤트의 형식을 미리 지정한 고객이 변형을 완전히 우회할 수 있습니다.
API 참조
모든 이벤트 정의 작업에서 기본 경로 /loyalty/metadata/config/events을(를) 사용합니다.
| code language-http |
|---|
|
| code language-http |
|---|
|
| code language-http |
|---|
|
| code language-http |
|---|
|
변환기 유효성 검사
이벤트 정의가 저장될 때 JSONata 표현식의 구문 유효성이 검사됩니다. 표현식이 잘못된 경우 API가 구문 분석 실패에 대한 설명과 함께 422 오류를 반환합니다.
배포하기 전에 변환기를 테스트하려면 JSONata Exerciser — 소스 이벤트를 입력으로 붙여넣고 변환기 표현식을 적용하여 출력이 예상 충성도 이벤트 형식과 일치하는지 확인합니다.
일반적인 함정
이러한 실수는 모두 간단한 단일 항목 테스트 페이로드에서 오류 없이 실행되므로 감지되지 않은 상태로 슬쩍 넘어갑니다. 배포하기 전에 항상 두 개 이상의 제품을 사용하여 페이로드에 대해 변환기를 테스트하십시오.
가장 빈번한 실수. productListItems.SKU에서 단일 개체 리터럴을 사용하면 제품당 하나의 라인 항목을 생성하는 대신 모든 SKU와 모든 수량을 묶은 시퀀스로 가져옵니다.
✗이(가) 모든 항목을 하나로 축소:
| code language-jsonata |
|---|
|
두 제품을 사용하면 item_set은(는) SKU를 모두 보유하며 quantity은(는) [1, 4]과(와) 같은 배열이 됩니다.
✓제품당 하나의 라인 항목:
| code language-jsonata |
|---|
|
.{ } 맵은 제품당 한 번 실행되므로 각각 고유한 항목이 됩니다.
identityMap.Email은(는) 배열입니다. [0]이(가) 없으면 프로필에 해당 네임스페이스에 둘 이상의 ID가 있는 경우 id은(는) 단일 문자열 대신 값 목록이 됩니다.
✗ identityMap.Email.id
✓ identityMap.Email[0].id
_yourtenant.identification.core.email과(와) 같은 전자 메일 모양 필드를 노출합니다. 샘플 데이터에서 값을 반환하고 올바른 것처럼 보이지만 프로덕션 이벤트에서는 빈 경우가 많기 때문에 loyalty_identity.id이(가) null로 표시됩니다. 항상 identityMap을(를) ID의 소스로 사용합니다.item_set(으)로 누출되는 중첩 배열item_set에 범주 필드를 추가하는 것은 간단해 보이지만 productCategories이(가) 배열 자체일 경우 결과는 예상할 수 없이 확장됩니다.
✗이(가) 예상보다 많은 항목을 생성할 수 있음:
| code language-jsonata |
|---|
|
범주가 세 개인 제품에서 네 개의 값이 있는 item_set을(를) 생성합니다.
✓중첩된 배열을 인덱싱하여 정확히 하나의 값을 가져옵니다.
| code language-jsonata |
|---|
|
item_list이(가) 비어 있거나 없습니다.비어 있거나 없는 item_list이(가) 있는 이벤트가 잘못된 이벤트로 거부되었습니다. 트랜잭션이 아닌 이벤트(체크인, 사용자 지정 트리거)의 경우 자연어 라인 항목이 없으므로 합성 라인 항목을 생성합니다.
| code language-jsonata |
|---|
|
timestamp을(를) ISO 8601 대신 Unix Epoch 정수로 사용플랫폼에는 ISO 8601 문자열이 필요합니다. epoch 이후 소스 이벤트가 밀리초로 전달되면 변환하십시오.
| code language-jsonata |
|---|
|
utc_offset 생략됨utc_offset이(가) 없으면 날짜 범위 창 일치 및 연속 일 연속 계산을 모두 건너뜁니다. 소스 이벤트의 저장소 또는 장치 UTC 오프셋을 사용할 수 있는 위치에 매핑합니다.xdmEntity 본문만 받습니다. 모든 경로는 XDM 엔티티 루트에 상대적이어야 합니다. 식이 외부 봉투(예: /body/xdmMeta/...)에 있는 필드를 참조하는 경우 해당 필드를 찾을 수 없으며 자동으로 null이 생성됩니다.