ECAPI 사양 매핑

이 가이드는 IAB Tech Lab 이벤트 및 전환 API (ECAPI) 사양을 사용하는 개발자가 이벤트 및 전환 데이터를 Data Manager API 이벤트 수집 스키마에 매핑하는 데 도움을 줍니다.

개요

ECAPI는 마케팅 관련 이벤트와 전환이 구성되는 방식을 정의하기 위해 설계된 플랫폼에 구애받지 않는 오픈소스 데이터 표준입니다.

다음 표에서는 ECAPI의 주요 속성 및 설계 원칙이 Data Manager API와 어떻게 비교되는지 간략하게 보여줍니다.

ECAPI Data Manager API
중복 삭제 id (이벤트 ID)에 의존 transaction_id에 의존
이벤트 라우팅 데이터의 대상은 이벤트 페이로드의 data_set_id 필드로 표시됩니다. 요청의 destinations 필드는 이벤트의 대상을 정의합니다.

Data Manager API는 단일 요청에서 여러 대상으로 이벤트를 라우팅하는 것도 지원합니다.

자세한 내용은 대상 가이드를 참고하세요.
개인 정보 보호 및 동의 필드 Global Privacy Platform (GPP) 동의 문자열 Data Manager API는 Global Privacy Platform (GPP) 동의 문자열을 허용하거나 파싱하지 않습니다. 동의 필드는 Consent 객체에 설정해야 합니다.

요청 수준 (요청의 모든 이벤트에 적용됨) 또는 이벤트 수준 (개별 이벤트에 대해 서로 다른 동의 설정을 지정할 수 있음)에서 동의를 설정할 수 있습니다.

구조 필드 매핑

다음 매핑 표에서는 ECAPI 사양의 개별 필드가 Data Manager API에서 허용되는 필드로 변환되는 방식을 정의합니다.

이벤트 객체 매핑

ECAPI (event) Data Manager API (Event) 참고
data_set_id
  • destinations[].product_destination_id (요청 수준)
  • destination_references (이벤트 수준)
 다음 수준에서 정의할 수 있습니다.
  • 요청 수준(필수): IngestEventsRequest에 destinations 목록을 지정합니다.
  • 이벤트 수준: Event 객체에서 destination_references 필드를 사용합니다. destinations 목록에서 어떤 대상이 이벤트를 수신해야 하는지 지정하는 항목을 추가합니다.

Destination를 정의하고 제품 대상 ID를 결정하는 방법에 관한 자세한 내용은 대상 및 헤더 구성을 참고하세요.
id transaction_id 이 값은 전환 이벤트의 중복 삭제에 사용됩니다. 자세히 알아보기
timestamp event_timestamp 필수사항. ECAPI는 타임스탬프에 Unix 에포크 형식 (정수)을 사용합니다. Data Manager API에 매핑할 때 event_timestamp 필드를 다음 형식 중 하나로 변환해야 합니다.
  • JSON 형식을 사용하는 경우 RFC 3339 형식의 값으로 설정합니다.
  • 프로토콜 버퍼를 사용하는 경우 Timestamp을 사용하고 seconds 및 (선택사항) nanoseconds 필드를 설정합니다.

자세한 내용은 타임스탬프 형식을 참고하세요.
event_type/custom_event event_name 추천 이벤트 이름 (예: purchase) 또는 맞춤 이벤트 이름일 수 있습니다. 자세한 내용은 표준 이벤트 이름을 참고하세요.
user_data user_data UserIdentifier 객체 목록을 허용하는 UserData 객체에 매핑됩니다.
value conversion_value 전환의 금전적 가치를 나타내는 double 또는 float로 직접 매핑합니다.
currency_code currency 3자리 대문자 통화 코드 (예: USD)에 매핑합니다.
source event_source EventSource enum의 값으로 설정됩니다.
properties
  • cart_data
  • custom_variables
  • additional_event_parameters
 거래 수준 항목은 CartData 객체의 cart_data.items 배열에 매핑할 수 있습니다. Data Manager API는 판매자 센터 계정에 있는 제품에 대해 여러 선택적 판매자 센터 필드를 지원합니다.

대상 유형이 Google Ads 전환 액션인 경우 custom_variables 필드에 추가 맞춤 매개변수를 CustomVariable 객체 목록으로 포함할 수도 있습니다.

대상 데이터 스트림이 Google 애널리틱스 데이터 스트림인 경우 additional_event_parameters 필드에 추가 이벤트 매개변수를 AdditionalEventParameter 객체 목록으로 포함할 수 있습니다.
ext - 동등한 보고서 없음

사용자 데이터 객체 매핑

Data Manager API에서 Event 객체의 user_data 필드는 UserData 객체를 허용합니다. 여기에는 UserIdentifier 객체 목록이 필요하며, 이 객체에는 이메일 주소, 전화번호, 주소 구성요소와 같은 개별 사용자 식별자가 포함될 수 있습니다.

ECAPI (user_data) Data Manager API (Event) 참고
customer_identifier user_id (Google 애널리틱스) Google 애널리틱스 이벤트의 경우 user_id 필드는 User-ID를 나타냅니다. Data Manager API는 다른 대상의 일반 고객 ID 필드를 지원하지 않습니다.
uids - 동등한 보고서 없음 데이터 관리 도구 API는 에이전트 유형과 도메인이 포함된 구조화된 uids 배열을 지원하지 않습니다.
customer_segments user_properties Event에서 UserProperties에 매핑됩니다.
email_address user_data.user_identifiers[].email_address 형식이 지정되고 해싱된 이메일 주소로 설정됩니다. 해시된 이메일 주소를 암호화할 수도 있습니다.
phone_numbers user_data.user_identifiers[].phone_number 형식화되고 해싱된 전화번호로 설정됩니다. 해싱된 전화번호를 암호화할 수도 있습니다.
utcoffset - 동등한 보고서 없음 JSON 형식을 사용하는 경우 RFC 3339 event_timestamp 문자열에서 직접 시간대 오프셋을 지정할 수 있습니다.
프로토콜 버퍼를 사용하는 경우 Timestamps.parse(String)와 같은 유틸리티 함수를 사용하여 시간대 변환을 초 및 나노초로 처리할 수 있습니다.
자세한 내용은 타임스탬프 형식을 참고하세요.
address user_data.user_identifiers[].address AddressInfo 객체에 매핑됩니다. 주소 객체 매핑을 참고하세요.
gpp_string - 동등한 보고서 없음 동의는 요청 수준 또는 이벤트 수준 Consent 객체에 매핑되어야 합니다. 개인 정보 보호 및 동의 개요를 참고하세요.
gpp_sid - 동등한 보고서 없음 동의는 요청 수준 또는 이벤트 수준 Consent 객체에 매핑되어야 합니다. 개인 정보 보호 및 동의 개요를 참고하세요.
mmt_only - 동등한 보고서 없음
click_id ad_identifiers.gclid Google 클릭 ID (gclid)에 매핑합니다. 자세한 내용은 AdIdentifiers를 참고하세요.
impression_id ad_identifiers.impression_id 자세한 내용은 AdIdentifiers를 참조하세요.
event_ip_address event_device_info.ip_address 사용 가능한 필드는 DeviceInfo을 참고하세요.
event_user_agent event_device_info.user_agent 사용 가능한 필드는 DeviceInfo을 참고하세요.
ifa ad_identifiers.mobile_device_id 광고주용 모바일 식별자 (iOS의 IDFA, Android의 AdID)에 매핑합니다. 자세한 내용은 AdIdentifiers를 참조하세요.
landing_ip_address ad_identifiers.landing_page_device_info.ip_address 사용 가능한 필드는 DeviceInfo을 참고하세요.
landing_user_agent ad_identifiers.landing_page_device_info.user_agent 사용 가능한 필드는 DeviceInfo을 참고하세요.
age_range - 동등한 보고서 없음
gender - 동등한 보고서 없음
ext - 동등한 보고서 없음

주소 객체 매핑

ECAPI (address) Data Manager API (AddressInfo) 참고
first_name given_name AddressInfo의 given_name 필드에 매핑됩니다. 형식 지정 및 해싱 가이드라인을 따릅니다. 주소의 해시된 속성을 암호화할 수도 있습니다.
last_name family_name AddressInfo의 family_name 필드에 매핑됩니다. 형식 지정 및 해싱 가이드라인을 따릅니다. 주소의 해시된 속성을 암호화할 수도 있습니다.
street - 동등한 보고서 없음 Data Manager API에서 지원되지 않음
city - 동등한 보고서 없음 Data Manager API에서 지원되지 않음
state - 동등한 보고서 없음 Data Manager API에서 지원되지 않음
country_code region_code 해싱하지 않음 AddressInfo의 region_code 필드에 매핑됩니다. 형식 지정 가이드라인을 따르세요.
postal_code postal_code 해싱하지 않음 AddressInfo의 postal_code 필드에 매핑됩니다. 형식 지정 가이드라인을 따르세요.
address_type - 동등한 보고서 없음 Data Manager API에서 지원되지 않음
ext - 동등한 보고서 없음

항목 객체 매핑

ECAPI (item) Data Manager API (Item) 참고
id item_id Google 애널리틱스 이벤트에 필수입니다. 상품의 표준 고유 식별자로 설정됩니다.
- 동등한 보고서 없음 merchant_product_id 플러드라이트 전환 및 장바구니 데이터를 사용한 Google Ads 전환에 필수입니다. 판매자 센터 계정 내의 제품 ID로 설정됩니다.
name additional_item_parameters additional_item_parameters 목록에서 item_name로 매핑합니다.
price unit_price
discount additional_item_parameters 또는 custom_variables additional_item_parameters (Google 애널리틱스)에서 discount로 매핑하거나 custom_variables (Google Ads)에서 맞춤 변수로 매핑합니다.
quantity quantity float 값을 정수 (int64)로 변환합니다.
brand additional_item_parameters additional_item_parameters 목록에서 item_brand로 매핑합니다.
affiliation additional_item_parameters additional_item_parameters 목록에서 affiliation로 매핑합니다.
category additional_item_parameters additional_item_parameters 목록에서 item_category로 매핑합니다.
cattax - 동등한 보고서 없음
item_coupon additional_item_parameters additional_item_parameters 목록에서 coupon로 매핑합니다.
item_list_id additional_item_parameters additional_item_parameters 목록에서 item_list_id로 매핑합니다.
item_list_name additional_item_parameters additional_item_parameters 목록에서 item_list_name로 매핑합니다.
item_item_variant additional_item_parameters additional_item_parameters 목록에서 item_variant로 매핑합니다.
item_location_id additional_item_parameters additional_item_parameters에서 location_id로 매핑
ext - 동등한 보고서 없음

표준 이벤트 이름

ECAPI 표준 이벤트는 Google 애널리틱스 이름 지정 규칙과 매우 유사합니다.

대부분의 ECAPI 표준 이벤트 (예: purchase, add_to_cart, begin_checkout, search, refund)의 이벤트 이름은 Google 애널리틱스 권장 이벤트와 동일합니다. 하지만 Google 애널리틱스에서 과거형 대신 현재형을 사용하는 몇 가지 예외가 있습니다.

  • viewed_item는 view_item에 매핑됩니다.
  • viewed_item_list는 view_item_list에 매핑됩니다.
  • viewed_cart는 view_cart에 매핑됩니다.

요청 예

다음 탭에서는 ECAPI 전환 이벤트 페이로드와 유효한 Data Manager API IngestEventsRequest로의 표현을 비교합니다.

ECAPI

다음은 ECAPI 사양을 준수하는 샘플 JSON 페이로드입니다.

{
  "data_set_id": "123456789",
  "id": "ABC798654321",
  "timestamp": 1781035621,
  "event_type": "purchase",
  "value": 30.03,
  "currency_code": "USD",
  "source": "website",
  "user_data": {
    "customer_identifier": "123456789123456789",
    "customer_segments": ["gold_member"],
    "email_addresses": [
      "3E693CF7E5B67880BFF33B2D2626DADB7BF1D4BC737192E47CF8BAA89ACF2250"
    ],
    "address": {
      "first_name": "96d9632f363564cc3032521409cf22a852f2032eec099ed5967c0d000cec607a",
      "last_name": "db98d2607efffa28aff66975868bf54c075eca7157e35064dce08e20b85b1081",
      "country_code": "US",
      "postal_code": "94045"
    },
    "event_ip_address": "192.0.2.1",
    "event_user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36"
  },
  "properties": {
    "items": [
      {
        "id": "SKU_12345",
        "quantity": 3,
        "item_price": 10.01
      }
    ]
  }
}

Data Manager API

다음은 형식이 지정되고, 해싱되고, 인코딩된 이벤트 데이터의 샘플 IngestEventsRequest입니다. 이는 대상의 GOOGLE_ADS 계정 유형에서 알 수 있듯이 Google Ads 대상용입니다.

{
  "destinations": [
    {
      "operating_account": {
        "account_type": "GOOGLE_ADS",
        "account_id": "1234567890"
      },
      "login_account": {
        "account_type": "GOOGLE_ADS",
        "account_id": "1234567890"
      },
      "product_destination_id": "123456789"
    }
  ],
  "encoding": "HEX",
  "events": [
    {
      "event_name": "purchase",
      "transaction_id": "ABC798654321",
      "event_timestamp": "2026-06-10T20:07:01Z",
      "event_source": "WEB",
      "user_properties": {
        "additional_user_properties":[
          {
            "property_name": "customer_segment",
            "value": "gold_member"
          }
        ]
      },
      "user_data": {
        "user_identifiers": [
          {
            "email_address": "3E693CF7E5B67880BFF33B2D2626DADB7BF1D4BC737192E47CF8BAA89ACF2250"
          },
          {
            "address": {
              "given_name": "96D9632F363564CC3032521409CF22A852F2032EEC099ED5967C0D000CEC607A",
              "family_name": "DB98D2607EFFFA28AFF66975868BF54C075ECA7157E35064DCE08E20B85B1081",
              "region_code": "US",
              "postal_code": "94045"
            }
          }
        ]
      },
      "event_device_info": {
        "ip_address": "192.0.2.1",
        "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36"
      },
      "conversion_value": 30.03,
      "currency": "USD",
      "cart_data": {
        "items": [
          {
            "item_id": "SKU_12345",
            "quantity": 3,
            "unit_price": 10.01
          }
        ]
      }
    }
  ]
}