콘텐츠로 건너뛰기

추천 이벤트

추천 이벤트는 정의된 JSON 스키마를 가진 표준화된 커스텀 이벤트를 전송하는 프레임워크를 기반으로 구축됩니다. 추천 이벤트를 전송하면 Braze는 수집 시 해당 스키마에 대해 유효성을 검사하고, 일반 커스텀 이벤트에서는 제공되지 않는 자동 필드 계산이나 장바구니 관리와 같은 특수 처리를 적용합니다. 특정 산업 이벤트 세트의 경우, Braze는 Campaigns 및 Canvases에 대한 전용 액션 기반 트리거와 같은 특별한 처리도 지원합니다.

eCommerce 추천 이벤트는 구매 여정의 여섯 단계인 product_viewed, cart_updated, checkout_started, order_placed, order_cancelled, order_refunded를 다룹니다. 이러한 이벤트를 성공적으로 전송하면 Braze가 데이터의 유효성을 검사하고, 계속 늘어나는 플랫폼 기능에서 해당 데이터를 사용할 수 있게 합니다.

이러한 기능에는 둘러보기 이탈, 장바구니 이탈, 결제 이탈, 주문 확인 플로우를 위한 Canvas 템플릿, eCommerce 보고, 그리고 총 매출, 총 주문, 총 환불에 대한 계산된 고객 프로필 필드가 포함됩니다. 또한 세그먼트 확장을 통해 중첩된 제품 속성정보 필터링으로 Segments를 구축하고, {% shopping_cart %} Liquid 태그로 장바구니 이탈 메시지를 개인화하며, 예측 이벤트, 예측 이탈, 아이템 추천 등 BrazeAITM 기능에 데이터를 제공할 수 있습니다.

이러한 이벤트는 정의된 스키마를 따르기 때문에, 지원되는 각 기능은 커스텀 속성정보 매핑이나 기능별 구성 없이도 구조화된 데이터를 읽을 수 있습니다.

eCommerce 이벤트 작동 방식

eCommerce 이벤트는 미리 정의된 이름과 속성정보 스키마를 갖춘 커스텀 이벤트입니다. Braze SDK, /users/track REST API 엔드포인트 또는 클라우드 데이터 수집(CDI)을 사용하여 이벤트를 전송하면, Braze가 수집 시점에 각 이벤트를 해당 스키마와 대조하여 유효성을 검사합니다. 유효성 검사를 통과하면 Braze는 매출 필드 계산, 고객 프로필의 장바구니 상태 관리 등 해당 이벤트 유형에 맞는 후처리를 자동으로 적용합니다.

eCommerce 이벤트는 수행한 커스텀 이벤트에 대한 트리거 및 필터, 커스텀 이벤트 보고 등 다른 커스텀 이벤트가 작동하는 모든 곳에서 작동합니다. 또한 스키마 유효성 검사를 통해 다음과 같은 추가 기능을 사용할 수 있습니다.

  • Campaigns, Canvases, 작업 경로 단계, 인앱 메시지 트리거, 콘텐츠 카드 제거에서 사용하는 “Places order” 트리거 동작
  • 계산된 eCommerce 고객 프로필 필드(총 매출, 총 주문, 총 환불)
  • 장바구니 이탈 플로우를 위한 장바구니 상태 관리
  • 예측 이벤트, 예측 이탈, 아이템 추천 등 BrazeAITM 기능을 위한 더욱 풍부한 데이터

플랫폼에서 커스텀 이벤트를 지원하는 모든 곳에서 eCommerce 이벤트를 이름으로 참조할 수도 있습니다. 예를 들어 ecommerce.product_viewed 이벤트로 실행 기반 Campaign을 트리거하거나, ecommerce.checkout_started 이벤트를 필터링하는 Segment를 구축하거나, Currents를 통해 ecommerce.order_placed 이벤트를 내보낼 수 있습니다.

이벤트 이름 지정

이벤트 이름은 정확히 일치해야 하며, 대소문자를 구분하고, 점으로 구분됩니다. 항상 표준 형식을 사용하세요. 이벤트 이름이 여섯 가지 표준 이름 중 하나와 정확히 일치하지 않으면 Braze는 해당 이벤트를 일반 커스텀 이벤트로 처리하며, eCommerce 후처리는 수행되지 않습니다.

이벤트를 커스터마이징하거나 이름을 변경할 수 없습니다.

  • 올바른 예: ecommerce.order_placed
  • 잘못된 예: order.placed, eCommerce_order_placed, Order_Placed

이벤트 스키마

여섯 가지 eCommerce 추천 이벤트는 구매 여정의 각 단계에 매핑됩니다. 사용자가 해당 동작을 완료하는 시점에 각 이벤트를 실행하세요.

여섯 가지 eCommerce 추천 이벤트(product_viewed, cart_updated, checkout_started, order_placed, order_cancelled, order_refunded)를 거치는 사용자 여정 다이어그램.

클라이언트 측 로깅의 경우, ecommerce.product_viewed, ecommerce.cart_updated, ecommerce.checkout_started, ecommerce.order_placed는 가능한 경우 SDK eCommerce 이벤트 API를 사용하고, ecommerce.order_cancelled 및 ecommerce.order_refunded는 logCustomEvent를 사용합니다.

환불 및 취소 이벤트는 환불 플로우처럼 서버 측 로직의 완료에 의존하는 경우가 많기 때문에 일반적으로 Braze REST API를 통해 서버에서 전송합니다. 플랫폼별 구현 예시는 Braze SDK를 통해 eCommerce 이벤트 기록하기를 참조하세요.

사용자가 제품 상세 페이지를 조회할 때 트리거합니다. 이 이벤트는 Braze 카탈로그의 재입고 알림 및 가격 인하 알림과 호환됩니다.

클라이언트 측 구현

가능한 경우 SDK eCommerce 이벤트 API를 사용하세요. 플랫폼별 구현 예시는 Braze SDK를 통해 eCommerce 이벤트 기록하기를 참조하세요.

이벤트 속성정보

속성정보 이름 데이터 유형 필수 설명
product_id 문자열 예 고유 제품 식별자(예: SKU 또는 아이템 ID).
product_name 문자열 예 제품 표시 이름.
variant_id 문자열 예 제품 옵션 식별자(예: shirt_medium_blue).
image_url 문자열 아니요 제품 이미지 URL.
product_url 문자열 아니요 자세한 내용을 확인할 수 있는 제품 페이지 URL.
price 플로트 예 조회 시점의 옵션 단가.
currency 문자열 예 세 글자 ISO 4217 코드(예: USD 또는 EUR).
source 문자열 예 이벤트가 발생한 소스(예: web, ios 또는 android).
type 문자열 배열 아니요 재입고 및 가격 인하 알림에 Braze 카탈로그 트리거 기능을 사용하려면 필수입니다. 허용되는 값: "price_drop", "back_in_stock"
metadata 객체 아니요 유연한 키-값 페어(예: category 또는 brand).

REST API 예시




{
  "events": [
    {
      "external_id": "user_98765",
      "name": "ecommerce.product_viewed",
      "time": "2026-04-28T14:22:11Z",
      "properties": {
        "product_id": "SKU-RUN-4821",
        "product_name": "Ultraboost Running Shoe",
        "variant_id": "UB-BLK-11",
        "image_url": "https://cdn.example.com/shoes/ub-blk-11.jpg",
        "product_url": "https://www.example.com/products/ultraboost-running-shoe?variant=UB-BLK-11",
        "price": 189.99,
        "currency": "USD",
        "source": "web",
        "type": ["price_drop", "back_in_stock"],
        "metadata": {
          "category": "Running Shoes",
          "brand": "Shoe Brand"
        }
      }
    }
  ]
}

사용자의 장바구니 내용이 변경될 때마다 트리거합니다.

클라이언트 측 구현

가능한 경우 SDK eCommerce 이벤트 API를 사용하세요. 플랫폼별 구현 예시는 Braze SDK를 통해 eCommerce 이벤트 기록하기를 참조하세요.

이 이벤트는 다음 두 가지 방법 중 하나로 전송할 수 있습니다.

  • 전체 장바구니 교체: action을 생략하거나 action을 replace로 설정합니다. products에 절대 수량(장바구니에 담긴 옵션별 총 수량)과 함께 전체 품목을 포함합니다. total_value를 반드시 포함해야 합니다.
  • 증분 장바구니 업데이트: action을 add 또는 remove로 설정합니다. 변경된 품목만 포함합니다. 각 quantity는 장바구니의 총 수량이 아니라 추가하거나 제거할 수량입니다. add의 경우 Braze는 품목 수량을 늘리거나 새 품목을 추가합니다. remove의 경우 Braze는 품목 수량을 줄이고, 수량이 0에 도달하면 해당 품목을 제거합니다. add 및 remove에서는 total_value가 선택 사항입니다.

이 이벤트로 메시징을 트리거하려면 Canvas 및 Campaigns에서 Perform Cart Updated Event 트리거를 사용하세요. 이 트리거에는 장바구니가 쇼핑 퍼널을 따라 진행되는 것을 중단하는 특수 처리가 포함되어 있습니다.

이벤트 속성정보

속성정보 데이터 유형 필수 설명
cart_id 문자열 예 장바구니의 고유 식별자. 사용자의 장바구니 매핑을 위해 장바구니, 결제, 주문 이벤트 전반에서 공유됩니다.
action 문자열 아니요 add(수량 증가 또는 품목 추가), remove(수량 감소, 0이 되면 품목 제거) 또는 replace(전체 장바구니 교체, action 생략과 동일).
total_value 플로트 조건부 action을 생략하거나 replace인 경우 필수입니다. action이 add 또는 remove인 경우 선택 사항입니다.
subtotal_value 플로트 아니요 장바구니의 소계 금액(할인 적용 후, 세금/배송비 적용 전).
tax 플로트 아니요 장바구니에 적용된 총 세금.
shipping 플로트 아니요 장바구니의 총 배송비.
currency 문자열 예 세 글자 ISO 4217 코드.
products 배열 예 이번 업데이트의 품목. 전체 교체(action 없음 또는 replace)의 경우 절대 수량과 함께 전체 장바구니를 포함합니다. add 또는 remove의 경우 변경된 품목만 포함합니다. 제품 속성정보를 참조하세요.
source 문자열 예 이벤트가 발생한 소스.
metadata 객체 아니요 추가 이벤트 수준 데이터를 위한 유연한 키-값 페어.

제품 속성정보(products[])

속성정보 데이터 유형 필수 설명
product_id 문자열 예 고유 제품 식별자.
product_name 문자열 예 제품 표시 이름.
variant_id 문자열 예 옵션 식별자.
image_url 문자열 아니요 제품 이미지 URL.
product_url 문자열 아니요 제품 페이지 URL.
quantity 정수 예 전체 교체(action 없음 또는 replace)의 경우 이 품목의 장바구니 수량. add 또는 remove의 경우 추가하거나 제거할 수량.
price 플로트 예 옵션 단가.
metadata 객체 아니요 유연한 키-값 페어(예: color 또는 size).

사용자가 결제 플로우를 시작할 때(예: “결제”를 선택하거나 결제 페이지에 도달할 때) 트리거합니다.

클라이언트 측 구현

가능한 경우 SDK eCommerce 이벤트 API를 사용하세요. 플랫폼별 구현 예시는 Braze SDK를 통해 eCommerce 이벤트 기록하기를 참조하세요.

이벤트 속성정보

속성정보 유형 필수 설명
checkout_id 문자열 예 결제 세션의 고유 식별자.
cart_id 문자열 아니요 장바구니 식별자. 사용자의 장바구니 매핑을 위해 장바구니, 결제, 주문 이벤트 전반에서 공유됩니다.
total_value 플로트 예 결제의 총 금액.
subtotal_value 플로트 아니요 소계 금액(할인 적용 후, 세금/배송비 적용 전).
tax 플로트 아니요 결제에 적용된 총 세금.
shipping 플로트 아니요 총 배송비.
currency 문자열 예 세 글자 ISO 4217 코드.
products 배열 예 결제 중인 아이템. 제품 속성정보 하위 표를 참조하세요.
source 문자열 예 이벤트가 발생한 소스.
metadata 객체 아니요 유연한 키-값 페어. 인식되는 하위 속성정보: checkout_url(문자열)

제품 속성정보(products[])

속성정보 데이터 유형 필수 설명
product_id 문자열 예 고유 제품 식별자.
product_name 문자열 예 제품 표시 이름.
variant_id 문자열 예 옵션 식별자.
image_url 문자열 아니요 제품 이미지 URL.
product_url 문자열 아니요 제품 페이지 URL.
quantity 정수 예 장바구니에 담긴 수량.
price 플로트 예 옵션 단가.
metadata 객체 아니요 유연한 키-값 페어(예: color, size).

REST API 예시




{
  "events": [
    {
      "external_id": "user_98765",
      "name": "ecommerce.checkout_started",
      "time": "2026-04-28T14:30:05Z",
      "properties": {
        "checkout_id": "chk_88291",
        "cart_id": "cart_abc123",
        "total_value": 234.96,
        "subtotal_value": 219.97,
        "tax": 9.0,
        "shipping": 5.99,
        "currency": "USD",
        "products": [
          {
            "product_id": "SKU-RUN-4821",
            "product_name": "Ultraboost Running Shoe",
            "variant_id": "UB-BLK-11",
            "image_url": "https://cdn.example.com/shoes/ub-blk-11.jpg",
            "product_url": "https://www.example.com/products/ultraboost-running-shoe?variant=UB-BLK-11",
            "quantity": 1,
            "price": 189.99,
            "metadata": {
              "color": "Core Black",
              "size": "11"
            }
          },
          {
            "product_id": "SKU-SOC-1102",
            "product_name": "Performance Running Socks",
            "variant_id": "SOC-WHT-L",
            "image_url": "https://cdn.example.com/socks/soc-wht-l.jpg",
            "product_url": "https://www.example.com/products/performance-running-socks?variant=SOC-WHT-L",
            "quantity": 2,
            "price": 14.99,
            "metadata": {
              "color": "White",
              "size": "L"
            }
          }
        ],
        "source": "web",
        "metadata": {
          "checkout_url": "https://www.example.com/checkout/chk_88291",
          "checkout_type": "express"
        }
      }
    }
  ]
}

주문이 성공적으로 완료되거나 결제가 확인되었을 때 트리거합니다.

클라이언트 측 구현

가능한 경우 SDK eCommerce 이벤트 API를 사용하세요. 플랫폼별 구현 예시는 Braze SDK를 통해 eCommerce 이벤트 기록하기를 참조하세요.

이벤트 속성정보

속성정보 데이터 유형 필수 설명
order_id 문자열 예 주문의 고유 식별자.
cart_id 문자열 아니요 장바구니 식별자. 사용자의 장바구니 매핑을 위해 장바구니, 결제, 주문 이벤트 전반에서 공유됩니다.
total_value 플로트 예 주문의 총 금액.
subtotal_value 플로트 아니요 소계 금액(할인 적용 후, 세금/배송비 적용 전).
tax 플로트 아니요 주문에 적용된 총 세금.
shipping 플로트 아니요 총 배송비.
currency 문자열 예 세 글자 ISO 4217 코드.
total_discounts 플로트 아니요 주문에 적용된 총 할인 금액.
discounts 배열 아니요 적용된 할인의 상세 목록.
products 배열 예 주문에 포함된 아이템. 제품 속성정보 하위 표를 참조하세요.
source 문자열 예 이벤트가 발생한 소스.
metadata 객체 아니요 유연한 키-값 페어. 인식되는 하위 속성정보: order_status_url(문자열)

제품 속성정보(products[])

속성정보 데이터 유형 필수 설명
product_id 문자열 예 고유 제품 식별자.
product_name 문자열 예 제품 표시 이름.
variant_id 문자열 예 옵션 식별자.
image_url 문자열 아니요 제품 이미지 URL.
product_url 문자열 아니요 제품 페이지 URL.
quantity 정수 예 장바구니에 담긴 수량.
price 플로트 예 옵션 단가.
metadata 객체 아니요 유연한 키-값 페어(예: color 또는 size).

REST API 예시




{
  "events": [
    {
      "external_id": "user_98765",
      "name": "ecommerce.order_placed",
      "time": "2026-04-28T14:35:42Z",
      "properties": {
        "order_id": "ord_77821",
        "cart_id": "cart_abc123",
        "total_value": 224.96,
        "subtotal_value": 209.97,
        "tax": 9.0,
        "shipping": 5.99,
        "currency": "USD",
        "total_discounts": 10.0,
        "discounts": [
          {
            "code": "SPRING10",
            "amount": 10.0,
            "type": "percentage"
          }
        ],
        "products": [
          {
            "product_id": "SKU-RUN-4821",
            "product_name": "Ultraboost Running Shoe",
            "variant_id": "UB-BLK-11",
            "image_url": "https://cdn.example.com/shoes/ub-blk-11.jpg",
            "product_url": "https://www.example.com/products/ultraboost-running-shoe?variant=UB-BLK-11",
            "quantity": 1,
            "price": 189.99,
            "metadata": {
              "color": "Core Black",
              "size": "11"
            }
          },
          {
            "product_id": "SKU-SOC-1102",
            "product_name": "Performance Running Socks",
            "variant_id": "SOC-WHT-L",
            "image_url": "https://cdn.example.com/socks/soc-wht-l.jpg",
            "product_url": "https://www.example.com/products/performance-running-socks?variant=SOC-WHT-L",
            "quantity": 2,
            "price": 14.99,
            "metadata": {
              "color": "White",
              "size": "L"
            }
          }
        ],
        "source": "web",
        "metadata": {
          "order_status_url": "https://www.example.com/orders/ord_77821/status"
        }
      }
    }
  ]
}

주문이 취소되었을 때 트리거합니다.

클라이언트 측 구현

logCustomEvent를 사용하세요. 플랫폼별 구현 예시는 Braze SDK를 통해 eCommerce 이벤트 기록하기를 참조하세요.

이벤트 속성정보

속성정보 유형 필수 설명
order_id 문자열 예 주문의 고유 식별자.
total_value 플로트 예 취소되는 주문의 총 금액. 0 이상이어야 합니다. 절대 금액을 전송하면 Braze가 차감을 처리합니다.
subtotal_value 플로트 아니요 소계 금액(할인 적용 후, 세금/배송비 적용 전).
tax 플로트 아니요 주문에 적용된 총 세금.
shipping 플로트 아니요 총 배송비.
currency 문자열 예 세 글자 ISO 4217 코드.
total_discounts 플로트 아니요 주문에 적용된 총 할인 금액.
discounts 배열 아니요 적용된 할인의 상세 목록.
cancel_reason 문자열 예 주문이 취소된 이유.
products 배열 예 취소된 주문에 포함된 아이템. 제품 속성정보 하위 표를 참조하세요.
source 문자열 예 이벤트가 발생한 소스.
metadata 객체 아니요 유연한 키-값 페어. 인식되는 하위 속성정보: order_status_url(문자열)

제품 속성정보(products[])

속성정보 데이터 유형 필수 설명
product_id 문자열 예 고유 제품 식별자.
product_name 문자열 예 제품 표시 이름.
variant_id 문자열 예 옵션 식별자.
image_url 문자열 아니요 제품 이미지 URL.
product_url 문자열 아니요 제품 페이지 URL.
quantity 정수 예 장바구니에 담긴 수량.
price 플로트 예 옵션 단가.
metadata 객체 아니요 유연한 키-값 페어(예: color 또는 size).

REST API 예시




{
  "events": [
    {
      "external_id": "user_98765",
      "name": "ecommerce.order_cancelled",
      "time": "2026-04-28T16:10:00Z",
      "properties": {
        "order_id": "ord_77821",
        "total_value": 224.96,
        "subtotal_value": 209.97,
        "tax": 9.0,
        "shipping": 5.99,
        "currency": "USD",
        "total_discounts": 10.0,
        "cancel_reason": "customer_request",
        "products": [
          {
            "product_id": "SKU-RUN-4821",
            "product_name": "Ultraboost Running Shoe",
            "variant_id": "UB-BLK-11",
            "quantity": 1,
            "price": 189.99,
            "metadata": {
              "color": "Core Black",
              "size": "11"
            }
          },
          {
            "product_id": "SKU-SOC-1102",
            "product_name": "Performance Running Socks",
            "variant_id": "SOC-WHT-L",
            "quantity": 2,
            "price": 14.99,
            "metadata": {
              "color": "White",
              "size": "L"
            }
          }
        ],
        "source": "web",
        "metadata": {
          "order_status_url": "https://www.example.com/orders/ord_77821/status"
        }
      }
    }
  ]
}

전체 또는 부분 환불이 발생했을 때 트리거합니다.

클라이언트 측 구현

logCustomEvent를 사용하세요. 플랫폼별 구현 예시는 Braze SDK를 통해 eCommerce 이벤트 기록하기를 참조하세요.

이벤트 속성정보

속성정보 데이터 유형 필수 설명
order_id 문자열 예 원래 주문의 고유 식별자.
total_value 플로트 예 환불의 총 금액. 0 이상이어야 합니다. 절대 금액을 전송하면 Braze가 total_refunds 증가를 처리합니다.
currency 문자열 예 세 글자 ISO 4217 코드.
total_discounts 플로트 아니요 원래 적용된 총 할인 금액.
discounts 배열 아니요 할인의 상세 목록.
products 배열 예 환불되는 아이템. 제품 속성정보 하위 표를 참조하세요.
source 문자열 예 이벤트가 발생한 소스.
metadata 객체 아니요 유연한 키-값 페어. 인식되는 하위 속성정보: order_status_url(문자열).

제품 속성정보(products[])

속성정보 데이터 유형 필수 설명
product_id 문자열 예 고유 제품 식별자.
product_name 문자열 예 제품 표시 이름.
variant_id 문자열 예 옵션 식별자.
image_url 문자열 아니요 제품 이미지 URL.
product_url 문자열 아니요 제품 페이지 URL.
quantity 정수 예 장바구니에 담긴 수량.
price 플로트 예 옵션 단가.
metadata 객체 아니요 유연한 키-값 페어(예: color 또는 size).

REST API 예시




{
  "events": [
    {
      "external_id": "user_98765",
      "name": "ecommerce.order_refunded",
      "time": "2026-04-29T10:05:00Z",
      "properties": {
        "order_id": "ord_77821",
        "total_value": 189.99,
        "currency": "USD",
        "total_discounts": 0,
        "products": [
          {
            "product_id": "SKU-RUN-4821",
            "product_name": "Ultraboost Running Shoe",
            "variant_id": "UB-BLK-11",
            "quantity": 1,
            "price": 189.99,
            "metadata": {
              "color": "Core Black",
              "size": "11",
              "refund_reason": "size_mismatch"
            }
          }
        ],
        "source": "web",
        "metadata": {
          "order_status_url": "https://www.example.com/orders/ord_77821/status"
        }
      }
    }
  ]
}






{
  "events": [
    {
      "external_id": "user_98765",
      "name": "ecommerce.order_refunded",
      "time": "2026-05-02T11:08:30Z",
      "properties": {
        "order_id": "ORD-20260428-7891",
        "total_value": 29.98,
        "currency": "USD",
        "products": [
          {
            "product_id": "SKU-SOC-1102",
            "product_name": "Performance Running Socks",
            "variant_id": "SOC-WHT-L",
            "image_url": "https://cdn.example.com/socks/soc-wht-l.jpg",
            "product_url": "https://www.example.com/products/performance-running-socks?variant=SOC-WHT-L",
            "quantity": 2,
            "price": 14.99,
            "metadata": {
              "color": "White",
              "size": "L"
            }
          }
        ],
        "source": "web",
        "metadata": {
          "refund_method": "store_credit",
          "initiated_by": "customer"
        }
      }
    }
  ]
}

eCommerce 이벤트 후처리

eCommerce 이벤트를 전송하면 Braze는 해당 이벤트 이름에 대해 예상되는 스키마와 대조하여 유효성을 검사합니다.

다음 표는 유효성 검사를 통과했을 때 Braze가 각 이벤트에 대해 자동으로 수행하는 작업을 요약한 것입니다. 유효성 검사에 실패했을 때 발생하는 상황은 이벤트 유효성 검사 및 문제 해결을 참조하세요.

이벤트 Braze가 자동으로 수행하는 작업
ecommerce.order_placed 고객 프로필에서 총 매출을 total_value만큼, 총 주문을 1만큼 증가시킵니다.
ecommerce.order_cancelled 총 주문을 1만큼 감소시킵니다.
ecommerce.order_refunded 총 매출을 total_value만큼 감소시키고 총 환불 금액을 증가시킵니다.
ecommerce.cart_updated 고객 프로필에 장바구니 매핑 객체를 생성하거나 업데이트합니다(전체 장바구니 페이로드 또는 선택적 action(add, remove, replace)을 사용한 증분 장바구니 업데이트). 장바구니는 30일 동안 업데이트가 없으면 만료됩니다.
ecommerce.product_viewed 고객 프로필은 변경되지 않습니다. 세분화, 트리거 및 BrazeAITM 기능(예: 아이템 추천)에 사용할 수 있습니다.
ecommerce.checkout_started 고객 프로필은 변경되지 않습니다. 세분화 및 트리거(예: 결제 이탈 플로우)에 사용할 수 있습니다.

구현 세부 정보

데이터 포인트 및 청구

eCommerce 이벤트는 데이터 포인트를 소비하지 않습니다. 데이터 포인트 사용량에 영향을 주지 않고 이벤트를 기록할 수 있습니다.

이벤트 크기 제한

/users/track으로 전송되는 이벤트 속성정보는 이벤트당 102,400바이트(100KB)로 제한됩니다. 트리거된 Campaign 및 Canvas 메시지의 경우, /campaigns/trigger/send 및 /canvas/trigger/send로 전송되는 trigger_properties에는 더 엄격한 기본 제한인 51,200바이트(50KB)가 적용됩니다.

모범 사례로, 이벤트를 트리거하거나 개인화하거나 어트리뷰션하는 데 필요한 제품 정보만 전송하세요. 설명, 전체 배리언트 목록, 재고, 대체 이미지 등 더 풍부한 제품 세부 정보는 Braze 카탈로그에 저장하세요. 메시지를 전송할 때는 product_id 또는 variant_id를 사용하여 이러한 세부 정보를 참조하세요. metadata 객체는 메시징에서 사용할 주문 또는 제품별 컨텍스트에 한해 선택적으로 사용하세요.

통화 처리

Braze는 이벤트가 보고된 날짜의 환율을 사용하여 USD가 아닌 통화 값을 자동으로 USD로 변환합니다. 이렇게 변환된 값이 매출 측정기준에 표시됩니다.

소스 필드

소스 속성정보는 이벤트가 발생한 위치를 식별하는 필수 문자열입니다. 예를 들어 shopify, in-store POS 또는 custom_api가 있습니다. 이를 통해 Currents 내보내기에서 데이터를 분석하거나 유효성 검사 문제를 디버깅할 때 통합 소스를 구분할 수 있습니다.

메타데이터 유연성

이벤트 수준 및 제품 수준 메타데이터 객체는 모두 임의의 키-값 페어를 허용하므로, 핵심 스키마를 수정하지 않고도 커스텀 차원을 추가할 수 있습니다. 일반적인 예로는 order_status_url, gift_wrapped, loyalty_points_earned 또는 warehouse_id가 있습니다. 이러한 속성정보는 Liquid 개인화, Currents 내보내기, 세그먼트 확장을 통한 세분화에서 사용할 수 있습니다.

이벤트 유효성 검사 및 문제 해결

/users/track 또는 Braze SDK를 통해 eCommerce 추천 이벤트를 전송하면, Braze는 추천 이벤트를 처리하는 과정에서 이벤트의 JSON 스키마를 기준으로 페이로드를 검증합니다. 유효성 검사는 이름이 추천 이벤트와 정확히 일치하는 모든 이벤트(예: ecommerce.order_placed 또는 ecommerce.cart_updated)에 대해 자동으로 실행됩니다.

검증 항목

이름이 eCommerce 추천 이벤트와 일치하는 각 이벤트에 대해 Braze는 다음 항목을 확인합니다.

검사 항목 예시
이벤트 이름 정확히 일치해야 합니다. 예를 들어 ecommerce.cart_updated는 올바르지만 ecommerce.Cart_Updated, cartupdated, cart_updated는 올바르지 않습니다.
필수 속성정보 포함 여부 order_placed에는 order_id, total_value, currency, products, source가 필요합니다.
올바른 데이터 유형 total_value는 숫자, currency는 문자열, products는 배열이어야 합니다.
추가 최상위 속성정보 없음 속성정보 아래에 커스텀 필드가 있으면 실패합니다. 대신 metadata 객체를 사용하세요.
값 제약 조건 금액 필드는 0 이상이어야 합니다. currency는 유효한 ISO 4217 문자열이어야 합니다.
제품별 필드 products[]의 각 항목에는 product_id, product_name, variant_id, quantity, price가 포함되어야 합니다.

유효성 검사를 하는 이유

eCommerce 이벤트는 매출 추적, {% shopping_cart %} Liquid 태그, 유기한 장바구니 트리거, 보고 등 일관되고 예측 가능한 데이터에 의존하는 기능을 지원합니다. 페이로드가 스키마와 다르면 이러한 기능에서 눈에 띄지 않는 부정확성(잘못된 매출 합계, 누락된 장바구니, 작동하지 않는 트리거)이 발생합니다. 유효성 검사는 이러한 규약을 사전에 적용하여 다운스트림 기능이 예측 가능하게 작동하도록 합니다.

유효성 검사에 통과한 경우

이벤트는 관련된 모든 후처리와 함께 eCommerce 추천 이벤트로 처리됩니다. 각 이벤트 유형에 따라 트리거되는 동작의 전체 목록은 eCommerce 추천 이벤트를 참조하세요.

성공한 이벤트 확인하기

이벤트를 전송한 후 다음 방법 중 하나를 사용하여 이벤트가 정상적으로 수락되고 처리되었는지 확인할 수 있습니다.

  • 이벤트 사용자 로그: 대시보드에서 사용자 프로필을 열고 활동을 검토합니다. 추천 이벤트는 전체 속성정보 페이로드와 함께 표시되므로, 이벤트가 도착했는지와 값이 전송한 내용과 일치하는지 확인할 수 있습니다.
  • 커스텀 이벤트 보고서: 분석 > 커스텀 이벤트 보고서로 이동하여 시간 경과에 따른 각 추천 이벤트의 총 집계를 확인합니다. 통합이 실시간으로 운영될 때 프로덕션 트래픽이 예상대로 들어오고 있는지 확인하는 데 유용합니다.
  • 테스트 사용자: 개발 워크스페이스에서 사용자를 테스트 사용자로 표시한 다음, 해당 사용자를 대상으로 통합에서 이벤트를 트리거합니다. 테스트 사용자는 대시보드에 별도로 표시되므로 포괄적인 동작을 쉽게 분리하고 검사할 수 있습니다.

유효성 검사에 실패한 경우

이벤트는 추천 이벤트로 처리되지 않습니다. 구체적으로는 다음과 같습니다.

  • 이벤트가 완전히 삭제됩니다. 유효하지 않은 eCommerce 추천 이벤트는 고객 프로필에 기록되지 않고, Currents에 표시되지 않으며, 세분화에도 사용할 수 없습니다.
  • 다음을 포함한 다운스트림 추천 이벤트 기능이 실행되지 않습니다.
    • 매출 추적(매출 보고, total_revenue와 같은 사용자 계산 필드)
    • 고객 프로필의 장바구니 객체 업데이트
    • Canvas 및 Campaigns의 장바구니 업데이트 또는 주문하기 트리거

오류가 보고되는 방식은 수집 경로에 따라 다릅니다.

  • REST API(/users/track): 유효하지 않은 각 이벤트는 응답의 errors 배열에 보고됩니다. 각 항목은 어떤 이벤트가 실패했는지(index)와 그 이유(type)를 알려줍니다. 최상위 message 필드에는 여전히 “success”가 표시되는데, 이는 요청이 Braze에 도달했다는 의미일 뿐 모든 이벤트가 유효하다는 의미는 아닙니다. 응답에 errors 배열이 있는지 항상 확인하세요.
  • Braze SDK: SDK 호출은 즉시 반환되고 유효성 검사는 백그라운드에서 실행되므로, 오류가 앱으로 다시 전송되지 않습니다. eCommerce 이벤트 유효성 검사 실패를 확인하려면 실패 요약 이메일을 확인하세요(실패 찾기 참조).

API 오류 응답 예시

/users/track 엔드포인트는 어떤 속성정보가 실패했는지와 그 이유를 나타내는 필드 수준 오류를 반환합니다. 이벤트가 파이프라인에 수락되었기 때문에 최상위 message는 "success"를 반환할 수 있으며, errors 배열을 통해 어떤 필드가 스키마 유효성 검사에 실패했는지 알 수 있습니다. 다음 오류 응답 예시를 참조하세요.




{
 "message": "success",
 "errors": [{ "index": 0, "input_array": "purchases", "type": "'currency' must be an ISO 4217 currency" }]
}

실패는 내부적으로도 분류되어 실패 요약 이메일에 집계됩니다.

실패 유형 의미 예시
missing_property 필수 필드가 없습니다. order_id 없이 order_placed를 전송한 경우
extra_property 스키마에 정의되지 않은 필드가 추가되었습니다. 커스텀 gift_wrapped 필드를 metadata 내부가 아닌 properties 최상위에 넣은 경우
unexpected_data_type 필드의 유형이 잘못되었습니다. 29.99(숫자) 대신 total_value: "29.99"(문자열)를 보낸 경우

실패 찾기

Braze는 워크스페이스 관리자에게 추천 이벤트 유효성 검사 실패 요약 이메일을 보내므로, 모든 이벤트를 수동으로 모니터링하지 않고도 통합 문제를 파악하고 해결할 수 있습니다.

요약 이메일에는 다음 내용이 포함됩니다.

  • 총 오류 수: 보고 기간 동안의 오류 수
  • 이벤트별 오류: 추천 이벤트 유형별(예: ecommerce.cart_updated 및 ecommerce.order_placed)로 실패한 이벤트 수의 세부 내역. 통합에서 어떤 이벤트를 먼저 살펴봐야 하는지 파악하는 데 활용하세요.
  • 소스별 오류: API와 SDK로 구분된 내역으로, 어떤 통합에서 실패가 발생하고 있는지 정확히 파악할 수 있습니다.

이러한 이메일을 받지 못하고 있거나 수신자 목록을 확인하고 싶다면 Braze 계정 팀에 문의하세요.

실패 진단 및 해결

실패 요약 이메일을 받았다면 다음 단계를 따르세요.

  1. 실패한 이벤트와 소스를 파악합니다. 이메일은 이벤트 이름과 통합 소스(sdk와 rest_api)별로 실패를 구분하므로, 어떤 통합을 수정해야 하는지 정확히 파악할 수 있습니다. 여러 소스에서 동일한 이벤트를 전송하는 경우(예: 스토어프론트 SDK와 백엔드 웹훅이 모두 cart_updated를 전송하는 경우)에는 각각 따로 해결하세요.
  2. 이벤트 스키마의 스키마와 페이로드를 비교합니다. 대부분의 실패는 다음 세 가지 패턴 중 하나에 해당합니다.
    • missing_property: 필수 필드가 없습니다. 필수 필드를 추가하여 해결하세요.
    • extra_property: 커스텀 필드가 properties의 최상위에 있습니다. 커스텀 필드를 metadata(이벤트 수준) 또는 products[].metadata(제품별) 내부로 옮겨 해결하세요.
    • unexpected_data_type: 값의 유형이 잘못되었습니다(예: total_value를 문자열로 전송). 전송하기 전에 값을 변환하여 해결하세요.
  3. 프로덕션에 배포하기 전에 개발 워크스페이스에서 수정한 페이로드를 테스트합니다. 테스트 사용자에 대해 알려진 테스트 이벤트를 전송한 다음, 해당 사용자의 프로필에서 예상되는 추천 이벤트 동작(예: 장바구니 객체 업데이트, 매출 증가, 유기한 장바구니 트리거 실행)을 확인하세요.
  4. 다음 실패 이메일을 모니터링하여 해당 이벤트, 소스, 유형의 실패 수가 0으로 줄었는지 확인합니다.

이벤트별 전체 속성정보 요구 사항은 이벤트 스키마를 참조하세요.

Braze 고객 참여 플랫폼 문서.

리소스
법적 고지
회사
© 2026 Braze, Inc. All rights reserved.
브레이즈 상태 확인
New Stuff!