이 페이지는 Cloud Translation API를 통해 번역되었습니다.

일정 보내기

이 빠른 시작을 통해 이벤트 데이터 전송에 익숙해질 수 있습니다.

다음 시나리오 중 하나에 데이터 관리 도구 API를 사용하세요.

Google Ads 태그 전환 또는 Google 애널리틱스 주요 이벤트를 태그 전환의 추가 데이터 소스로 전송하여 광고 상호작용 신호를 극대화하고 데이터와 전반적인 실적을 강화하세요.

이 기능은 허용 목록에 있는 계정에서만 사용할 수 있습니다. Google Ads 계정 또는 Google 애널리틱스 속성을 추가하려면 양식을 작성하세요.

참고: 연결한 추가 데이터 소스의 데이터는 14일 무료 체험 기간 동안 전환 입찰에 반영되지 않습니다. 기존 Google 태그 데이터 소스에는 적용되지 않습니다.
Google Ads 오프라인 전환 또는 리드 확보용 향상된 전환의 이벤트 데이터를 전송합니다.

확인할 가이드 버전을 선택하세요.

이 빠른 시작에서는 다음 단계를 완료합니다.

이벤트 데이터를 수신할 Destination를 준비합니다.
전송할 이벤트 데이터를 준비합니다.
이벤트에 대한 IngestionService 요청을 빌드합니다.
Google API 탐색기로 요청을 보냅니다.
성공 및 실패 응답을 이해합니다.

대상 준비

데이터를 전송하려면 데이터에 사용할 Destination를 하나 이상 준비해야 합니다. 다음은 사용할 수 있는 샘플 Destination입니다.

    {
      "operatingAccount": {
        "accountType": "OPERATING_ACCOUNT_TYPE",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "loginAccount": {
        "accountType": "LOGIN_ACCOUNT_TYPE",
        "accountId": "LOGIN_ACCOUNT_ID"
      },

      "productDestinationId": "PRODUCT_DESTINATION_ID"
    }

다음은 Destination의 필드입니다.

operatingAccount

이벤트를 수신하는 계정입니다.

추가 데이터 소스로 전송된 이벤트의 경우 운영 계정은 Google Ads 계정 또는 Google 애널리틱스 속성일 수 있습니다. accountType를 GOOGLE_ADS 또는 GOOGLE_ANALYTICS_PROPERTY로 설정하고 accountId을 Google Ads 고객 ID 또는 Google 애널리틱스 속성 ID로 설정합니다. accountType이 GOOGLE_ANALYTICS_PROPERTY인 경우 요청의 사용자 인증 정보는 속성에 대한 편집자 또는 관리자 역할이 있는 Google 애널리틱스 사용자의 사용자 인증 정보여야 합니다.

오프라인 전환 및 리드 확보용 향상된 전환의 경우 운영 계정이 Google Ads 계정이어야 하므로 accountType을 GOOGLE_ADS로 설정하고 accountId을 Google Ads 고객 ID로 설정합니다.

loginAccount

사용자가 액세스할 수 있는 사용자 인증 정보의 계정입니다.

OAuth 사용자 인증 정보가 operatingAccount를 하위 계정 중 하나로 사용하는 Google Ads 관리자 계정에 액세스할 수 있는 사용자의 경우 loginAccount가 필요합니다. loginAccount의 accountId를 관리자 계정의 ID로 설정하고 loginAccount의 accountType를 GOOGLE_ADS로 설정합니다.

OAuth 사용자 인증 정보가 operatingAccount에 직접 액세스할 수 있는 사용자의 경우 loginAccount를 설정할 필요가 없으며 기본적으로 operatingAccount로 설정됩니다. 하지만 loginAccount을 operatingAccount과 동일한 accountId 및 accountType로 설정하는 것이 좋습니다. 이렇게 하면 사용자가 액세스할 수 있는 계정 집합이 변경될 때 발생하는 문제를 방지할 수 있습니다.

productDestinationId

이벤트를 수신하는 operatingAccount의 항목 ID입니다.

추가 데이터 소스로 전송된 이벤트의 경우 productDestinationId는 type이 WEBPAGE로 설정된 Google Ads 전환의 ID이거나 Google 애널리틱스 웹 스트림의 측정 ID여야 합니다. Google 애널리틱스 iOS 앱 또는 Android 앱 스트림에 이벤트를 추가 데이터 소스로 전송할 수 없습니다.

오프라인 전환 또는 리드 확보용 향상된 전환의 경우 productDestinationId는 type이 UPLOAD_CLICKS로 설정된 Google Ads 전환 액션의 ID여야 합니다.

이 가이드의 예에서는 모든 이벤트를 동일한 대상으로 전송하는 요청을 구성하는 방법을 보여줍니다. 동일한 요청에서 여러 대상의 이벤트를 전송하려면 여러 대상의 이벤트 전송을 참고하세요.

이벤트 데이터 준비

다음 이벤트 데이터를 고려해 보세요. 각 표는 하나의 전환 이벤트에 해당합니다. 각 전환 이벤트에는 이벤트의 타임스탬프, 전환 액션, 전환 값이 있습니다.

각 이벤트에는 gclid와 같은 광고 식별자 또는 이메일 주소, 전화번호, 주소 정보와 같은 사용자 식별자가 있을 수 있습니다. 이벤트에는 다음 항목도 있을 수 있습니다.

이벤트 시점에 평가된 사용자 정보(예: 고객의 가치, 신규 고객인지, 재방문 고객인지, 재참여 고객인지)
장바구니 데이터입니다.
Google 애널리틱스의 client_id 또는 user_id과 같은 대상의 추가 이벤트 매개변수 또는 사용자 속성입니다.

이벤트 데이터는 다음과 같습니다.

이벤트 1

이벤트 #1
`conversion_time`	`2025-06-10 15:07:01-05:00`
`conversion_action_id`	`123456789`
`transaction_id`	`ABC798654321`
`conversion_value`	`30.03`
`currency`	`USD`
`gclid`	`GCLID_1`
`emails`
`given_name`	`John`
`family_name`	`Smith-Jones`
`region_code`	`us`
`postal_code`	`94045`
`customer_type`	`NEW`
`customer_value_bucket`	`HIGH`
`client_id`	`1234567890.1761581763`
`user_id`	`user_ABC12345`
`ad_unit_name`	`Banner_01`
`event_name`	`purchase`
장바구니 상품
`item_id`	`SKU_12345`
`item_name`	`Stan and Friends Tee`
`item_affiliation`	`Google Merchandise Store`
`item_coupon`	`SUMMER_FUN`
`item_discount`	`2.22`
`item_index`	`0`
`item_brand`	`Google`
`item_category`	`Apparel`
`item_category2`	`Adult`
`item_category3`	`Shirts`
`item_category4`	`Crew`
`item_category5`	`Short sleeve`
`item_list_id`	`related_products`
`item_list_name`	`Related Products`
`item_price`	`10.01`
`item_quantity`	`3`

이벤트 2

이벤트 2
`conversion_time`	`June 10, 2025 11:42:33PM America/New_York`
`conversion_action_id`	`123456789`
`transaction_id`	`DEF999911111`
`conversion_value`	`42.02`
`currency`	`eur`
`gclid`	`GCLID_2`
`emails`	`zoe@EXAMPLE.COM` `cloudy.sanfrancisco@gmail.com`
`given_name`	`zoë`
`family_name`	`pérez`
`region_code`	`PT`
`postal_code`	`1229-076`
`customer_type`	`RETURNING`
`client_id`	`9876543210.1761582117`
`user_id`	`user_DEF9876`
`ad_unit_name`	`Banner_02`
`event_name`	`purchase`
장바구니 상품
`item_id`	`SKU_12346`
`item_name`	`Google Grey Women's Tee`
`item_affiliation`	`Google Merchandise Store`
`item_coupon`	`SUMMER_FUN`
`item_discount`	`3.33`
`item_index`	`1`
`item_brand`	`Google`
`item_category`	`Apparel`
`item_category2`	`Adult`
`item_category3`	`Shirts`
`item_category4`	`Crew`
`item_category5`	`Short sleeve`
`item_list_id`	`related_products`
`item_list_name`	`Related Products`
`item_price`	`21.01`
`item_quantity`	`2`

데이터 형식 지정

형식 지정 가이드에 지정된 대로 필드의 형식을 지정합니다. 다음은 서식 지정 후의 이벤트 데이터입니다.

이벤트 1

이벤트 #1
`conversion_time`	`2025-06-10T15:07:01-05:00`
`conversion_action_id`	`123456789`
`transaction_id`	`ABC798654321`
`conversion_value`	`30.03`
`currency`	`USD`
`gclid`	`GCLID_1`
`emails`
`given_name`	`john`
`family_name`	`smith-jones`
`region_code`	`US`
`postal_code`	`94045`
`customer_type`	`NEW`
`customer_value_bucket`	`HIGH`
`client_id`	`1234567890.1761581763`
`user_id`	`user_ABC12345`
`ad_unit_name`	`Banner_01`
`event_name`	`purchase`
장바구니 상품
`item_id`	`SKU_12345`
`item_name`	`Stan and Friends Tee`
`item_affiliation`	`Google Merchandise Store`
`item_coupon`	`SUMMER_FUN`
`item_discount`	`2.22`
`item_index`	`0`
`item_brand`	`Google`
`item_category`	`Apparel`
`item_category2`	`Adult`
`item_category3`	`Shirts`
`item_category4`	`Crew`
`item_category5`	`Short sleeve`
`item_list_id`	`related_products`
`item_list_name`	`Related Products`
`item_price`	`10.01`
`item_quantity`	`3`

이벤트 2

이벤트 2
`conversion_time`	`2025-06-10T23:42:33-05:00`
`conversion_action_id`	`123456789`
`transaction_id`	`DEF999911111`
`conversion_value`	`42.02`
`currency`	`EUR`
`gclid`	`GCLID_2`
`emails`	`zoe@example.com` `cloudysanfrancisco@gmail.com`
`given_name`	`zoë`
`family_name`	`pérez`
`region_code`	`PT`
`postal_code`	`1229-076`
`customer_type`	`RETURNING`
`client_id`	`9876543210.1761582117`
`user_id`	`user_DEF9876`
`ad_unit_name`	`Banner_02`
`event_name`	`purchase`
장바구니 상품
`item_id`	`SKU_12346`
`item_name`	`Google Grey Women's Tee`
`item_affiliation`	`Google Merchandise Store`
`item_coupon`	`SUMMER_FUN`
`item_discount`	`3.33`
`item_index`	`1`
`item_brand`	`Google`
`item_category`	`Apparel`
`item_category2`	`Adult`
`item_category3`	`Shirts`
`item_category4`	`Crew`
`item_category5`	`Short sleeve`
`item_list_id`	`related_products`
`item_list_name`	`Related Products`
`item_price`	`21.01`
`item_quantity`	`2`

데이터 해싱 및 인코딩

또한 형식이 지정된 이메일 주소, 이름, 성은 SHA-256 알고리즘을 사용하여 해싱하고 16진수 또는 Base64 인코딩을 사용하여 인코딩해야 합니다. 다음은 16진수 인코딩을 사용하여 서식 지정, 해싱, 인코딩한 후의 이벤트 데이터입니다.

이벤트 1

이벤트 #1
`conversion_time`	`2025-06-10T15:07:01-05:00`
`conversion_action_id`	`123456789`
`transaction_id`	`ABC798654321`
`conversion_value`	`30.03`
`currency`	`USD`
`gclid`	`GCLID_1`
`emails`
`given_name`	`96D9632F363564CC3032521409CF22A852F2032EEC099ED5967C0D000CEC607A`
`family_name`	`DB98D2607EFFFA28AFF66975868BF54C075ECA7157E35064DCE08E20B85B1081`
`region_code`	`US`
`postal_code`	`94045`
`customer_type`	`NEW`
`customer_value_bucket`	`HIGH`
`client_id`	`1234567890.1761581763`
`user_id`	`user_ABC12345`
`ad_unit_name`	`Banner_01`
`event_name`	`purchase`
장바구니 상품
`item_id`	`SKU_12345`
`item_name`	`Stan and Friends Tee`
`item_affiliation`	`Google Merchandise Store`
`item_coupon`	`SUMMER_FUN`
`item_discount`	`2.22`
`item_index`	`0`
`item_brand`	`Google`
`item_category`	`Apparel`
`item_category2`	`Adult`
`item_category3`	`Shirts`
`item_category4`	`Crew`
`item_category5`	`Short sleeve`
`item_list_id`	`related_products`
`item_list_name`	`Related Products`
`item_price`	`10.01`
`item_quantity`	`3`

이벤트 2

이벤트 2
`conversion_time`	`2025-06-10T23:42:33-05:00`
`conversion_action_id`	`123456789`
`transaction_id`	`DEF999911111`
`conversion_value`	`42.02`
`currency`	`EUR`
`gclid`	`GCLID_2`
`emails`	`3E693CF7E5B67880BFF33B2D2626DADB7BF1D4BC737192E47CF8BAA89ACF2250` `223EBDA6F6889B1494551BA902D9D381DAF2F642BAE055888E96343D53E9F9C4`
`given_name`	`2752B88686847FA5C86F47B94CE652B7B3F22A91C37617D451A4DB9AFA431450`
`family_name`	`6654977D57DDDD3C0329CA741B109EF6CD6430BEDD00008AAD213DF25683D77F`
`region_code`	`PT`
`postal_code`	`1229-076`
`customer_type`	`RETURNING`
`client_id`	`9876543210.1761582117`
`user_id`	`user_DEF9876`
`ad_unit_name`	`Banner_02`
`event_name`	`purchase`
장바구니 상품
`item_id`	`SKU_12346`
`item_name`	`Google Grey Women's Tee`
`item_affiliation`	`Google Merchandise Store`
`item_coupon`	`SUMMER_FUN`
`item_discount`	`3.33`
`item_index`	`1`
`item_brand`	`Google`
`item_category`	`Apparel`
`item_category2`	`Adult`
`item_category3`	`Shirts`
`item_category4`	`Crew`
`item_category5`	`Short sleeve`
`item_list_id`	`related_products`
`item_list_name`	`Related Products`
`item_price`	`21.01`
`item_quantity`	`2`

데이터를 `Event` 객체로 변환

각 이벤트의 형식 지정되고 해싱된 데이터를 Event로 변환합니다. 다음 필드를 표시된 대로 채웁니다.

eventTimestamp을 이벤트가 발생한 시간으로 설정합니다.

Google 애널리틱스 이벤트는 지난 72시간 이내의 eventTimestamp가 있어야 합니다.

사용 사례에 필요한 필드를 설정합니다.

사용 사례	식별자	`transactionId`	`eventSource`
오프라인 전환 또는 리드 확보용 향상된 전환	필수사항: 다음 중 하나 이상을 설정합니다. `gclid`, `gbraid`, `wbraid` 또는 `sessionAttributes` 중 하나 이상이 설정된 `adIdentifiers` `userData`	선택사항	필수사항: `EventSource`의 열거형 값 중 하나로 설정합니다.
Google Ads 대상으로 전송되는 이벤트(추가 데이터 소스)	필수사항: 다음 중 하나 이상을 설정합니다. `adIdentifiers` `gclid`, `gbraid` 또는 `wbraid`이 하나 이상 설정됨 `userData`	필수	선택사항입니다. 설정된 경우 `WEB`여야 합니다.
Google 애널리틱스 대상으로 전송되는 이벤트(추가 데이터 소스)	필수사항: 다음 중 하나 이상을 설정합니다. `clientId` `adIdentifiers` `gclid` 설정 `userData`	필수	선택사항입니다. 설정된 경우 `WEB`여야 합니다.

이벤트 값이 있는 다른 필드를 채웁니다. 사용 가능한 필드의 전체 목록은 Event 참조 문서를 확인하세요.

Google 애널리틱스 정보 추가

추가 데이터 소스로 전송된 이벤트의 대상에 Google 애널리틱스 속성이 포함된 경우 다음 필드를 표시된 대로 채웁니다.

eventName

필수사항: Google 애널리틱스 이벤트의 이름입니다.

transactionId

필수 이벤트의 고유 식별자입니다.

식별자 1개 이상

다음 필드 중 하나 이상을 설정해야 합니다.

clientId: 웹 클라이언트의 사용자 인스턴스에 대한 고유 식별자입니다. 측정 프로토콜에 이벤트 전송을 참고하세요.
adIdentifiers.gclid: Google 클릭 ID입니다.
userData: 이메일 주소, 전화번호, 주소 정보와 같은 사용자 식별자입니다.

destinationReferences

요청 수준 destinations 목록에 Google 애널리틱스 Destination가 두 개 이상 포함된 경우 필수사항입니다. destinationReferences에 항목을 추가하여 이벤트를 수신해야 하는 Google 애널리틱스 대상 유형을 지정합니다. 대상 참조에 대한 자세한 내용은 여러 대상에 이벤트 전송을 참고하세요.

destinationReferences가 설정되지 않았거나 Google 애널리틱스 대상으로 연결되는 항목이 여러 개 있으면 데이터 관리 도구 API에서 MULTIPLE_DESTINATIONS_FOR_GOOGLE_ANALYTICS_EVENT 오류와 함께 이벤트를 거부합니다.

userId

선택사항입니다. 사용자의 User-ID입니다.

additionalEventParameters

선택사항이지만 권장됩니다. 이 목록을 다른 Event 필드에 포착되지 않는 Google 애널리틱스 이벤트 매개변수로 채웁니다. 매개변수에는 purchase 이벤트의 추가 권장 매개변수 또는 캡처하려는 기타 매개변수가 포함될 수 있습니다. EventParameter의 parameterName에 Google 애널리틱스 매개변수 이름을 사용합니다.

예를 들어 거래와 관련된 세금이 있는 경우 parameterName이 tax로 설정되고 value이 세금 비용으로 설정된 항목을 additionalEventParameters에 추가합니다.

transactionId, currency 또는 value Google 애널리틱스 이벤트 매개변수의 항목을 추가하지 않는 것이 좋습니다. 대신 additionalEventParameters의 항목보다 우선하는 Event의 transactionId, currency, conversionValue를 입력합니다.

구매 이벤트의 장바구니 데이터 추가

구매한 상품에 관한 정보로 Event의 cartData 필드를 채웁니다. 구매한 각 항목에 대해 CartData의 items 목록에 Item 객체를 추가하고 다음 필드를 표시된 대로 채웁니다.

itemId

필수사항. 상품의 고유 식별자입니다.

unitPrice

필수사항: 세금, 배송비, 이벤트 범위(거래 수준) 할인을 제외한 단위 가격입니다.

상품에 상품 범위 할인이 있는 경우 할인된 단위 가격을 사용합니다. 예를 들어 상품의 단가가 27.67이고 단위 할인이 6.66인 경우 unitPrice을 21.01로 설정합니다.

quantity

필수사항: 이 특정 상품에 대해 구매한 단위 수입니다.

additionalItemParameters

다른 Item 필드에서 캡처되지 않은 상품 범위 매개변수를 이 목록에 입력합니다. ItemParameter의 parameterName에 Google 애널리틱스 상품 매개변수 이름을 사용합니다.

예를 들어 상품의 브랜드와 카테고리가 있는 경우 parameterName이 item_brand로 설정되고 value이 브랜드 이름으로 설정된 항목을 상품의 additionalItemParameters에 추가하고 parameterName이 item_category로 설정되고 value이 상품의 카테고리로 설정된 항목을 추가합니다.

quantity, price 또는 item_id Google 애널리틱스 항목 매개변수의 항목을 추가하지 않는 것이 좋습니다. 대신 additionalItemParameters의 항목보다 우선하는 Item의 itemId, unitPrice, quantity를 채웁니다.

다음은 두 번째 이벤트에서 형식화되고, 해싱되고, 인코딩된 데이터의 샘플 Event입니다. Google 애널리틱스를 위한 추가 데이터가 포함되어 있습니다.

{
  "adIdentifiers": {
     "gclid": "GCLID_2"
  },
  "conversionValue": 42.02,
  "currency": "EUR",
  "eventTimestamp": "2025-06-10T23:42:33-05:00",
  "transactionId": "DEF999911111",
  "eventSource": "WEB",
  "userData": {
    "userIdentifiers": [
      {
        "emailAddress": "3E693CF7E5B67880BFF33B2D2626DADB7BF1D4BC737192E47CF8BAA89ACF2250"
      },
      {
        "emailAddress": "223EBDA6F6889B1494551BA902D9D381DAF2F642BAE055888E96343D53E9F9C4"
      },
      {
        "address": {
          "givenName": "2752B88686847FA5C86F47B94CE652B7B3F22A91C37617D451A4DB9AFA431450",
          "familyName": "6654977D57DDDD3C0329CA741B109EF6CD6430BEDD00008AAD213DF25683D77F",
          "regionCode": "PT",
          "postalCode": "1229-076"
        }
      }
    ],
  },
  "userProperties": {
    "customerType": "RETURNING"
  },
  "eventName": "purchase",
  "clientId": "9876543210.1761582117",
  "userId": "user_DEF9876",
  "additionalEventParameters": [
    {
      "parameterName": "ad_unit_name",
      "value": "Banner_02"
    }
  ],
  "cartData": {
    "transactionDiscount": 6.66,
    "items": [
      {
        "itemId": "SKU_12346",
        "quantity": 2,
        "unitPrice": 21.01,
        "additionalItemParameters": [
          {
            "parameterName": "item_name",
            "value": "Google Grey Women's Tee"
          },
          {
            "parameterName": "affiliation",
            "value": "Google Merchandise Store"
          },
          {
            "parameterName": "coupon",
            "value": "SUMMER_FUN"
          },
          {
            "parameterName": "discount",
            "value": "3.33"
          },
          {
            "parameterName": "index",
            "value": "1"
          },
          {
            "parameterName": "item_brand",
            "value": "Google"
          },
          {
            "parameterName": "item_category",
            "value": "Apparel"
          },
          {
            "parameterName": "item_category2",
            "value": "Adult"
          },
          {
            "parameterName": "item_category3",
            "value": "Shirts"
          },
          {
            "parameterName": "item_category4",
            "value": "Crew"
          },
          {
            "parameterName": "item_category5",
            "value": "Short sleeve"
          },
          {
            "parameterName": "item_list_id",
            "value": "related_products"
          },
          {
            "parameterName": "item_list_name",
            "value": "Related Products"
          }
        ]
      }
    ]
  }
}

요청 본문 빌드

요청 본문의 Destination 및 Events을 결합합니다.

{
  "destinations": [
    {
      "operatingAccount": {
        "accountType": "OPERATING_ACCOUNT_TYPE",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "loginAccount": {
        "accountType": "LOGIN_ACCOUNT_TYPE",
        "accountId": "LOGIN_ACCOUNT_ID"
      },

      "productDestinationId": "CONVERSION_ACTION_1_ID"
    }
  ],
  "encoding": "HEX",
  "events": [
     {
       "adIdentifiers": {
         "gclid": "GCLID_1"
       },
       "conversionValue": 30.03,
       "currency": "USD",
       "eventTimestamp": "2025-06-10T20:07:01Z",
       "transactionId": "ABC798654321",
       "eventSource": "WEB",
       "userData": {
         "userIdentifiers": [
           {
             "address": {
               "givenName": "96D9632F363564CC3032521409CF22A852F2032EEC099ED5967C0D000CEC607A",
               "familyName": "DB98D2607EFFFA28AFF66975868BF54C075ECA7157E35064DCE08E20B85B1081",
               "regionCode": "US",
               "postalCode": "94045"
             }
           }
         ]
       },
       "userProperties": {
         "customerType": "NEW",
         "customerValueBucket": "HIGH"
       },
       "eventName": "purchase",
       "clientId": "1234567890.1761581763",
       "userId": "user_ABC12345",
       "additionalEventParameters": [
         {
           "parameterName": "ad_unit_name",
           "value": "Banner_01"
         }
       ],
       "cartData": {
         "transactionDiscount": 6.66,
         "items": [
           {
             "itemId": "SKU_12345",
             "quantity": 3,
             "unitPrice": 10.01,
             "additionalItemParameters": [
               {
                 "parameterName": "item_name",
                 "value": "Stan and Friends Tee"
               },
               {
                 "parameterName": "affiliation",
                 "value": "Google Merchandise Store"
               },
               {
                 "parameterName": "coupon",
                 "value": "SUMMER_FUN"
               },
               {
                 "parameterName": "discount",
                 "value": "2.22"
               },
               {
                 "parameterName": "index",
                 "value": "0"
               },
               {
                 "parameterName": "item_brand",
                 "value": "Google"
               },
               {
                 "parameterName": "item_category",
                 "value": "Apparel"
               },
               {
                 "parameterName": "item_category2",
                 "value": "Adult"
               },
               {
                 "parameterName": "item_category3",
                 "value": "Shirts"
               },
               {
                 "parameterName": "item_category4",
                 "value": "Crew"
               },
               {
                 "parameterName": "item_category5",
                 "value": "Short sleeve"
               },
               {
                 "parameterName": "item_list_id",
                 "value": "related_products"
               },
               {
                 "parameterName": "item_list_name",
                 "value": "Related Products"
               }
             ]
           }
         ]

       }
     },
     {
       "adIdentifiers": {
         "gclid": "GCLID_2"
       },
       "conversionValue": 42.02,
       "currency": "EUR",
       "eventTimestamp": "2025-06-11T04:42:33Z",
       "transactionId": "DEF999911111",
       "eventSource": "WEB",
       "userData": {
         "userIdentifiers": [
           {
             "emailAddress": "3E693CF7E5B67880BFF33B2D2626DADB7BF1D4BC737192E47CF8BAA89ACF2250"
           },
           {
             "emailAddress": "223EBDA6F6889B1494551BA902D9D381DAF2F642BAE055888E96343D53E9F9C4"
           },
           {
             "address": {
               "givenName": "2752B88686847FA5C86F47B94CE652B7B3F22A91C37617D451A4DB9AFA431450",
               "familyName": "6654977D57DDDD3C0329CA741B109EF6CD6430BEDD00008AAD213DF25683D77F",
               "regionCode": "PT",
               "postalCode": "1229-076"
             }
           }
         ]
       },
       "userProperties": {
         "customerType": "RETURNING"
       },
       "eventName": "purchase",
       "clientId": "9876543210.1761582117",
       "userId": "user_DEF9876",
       "additionalEventParameters": [
         {
           "parameterName": "ad_unit_name",
           "value": "Banner_02"
         }
       ],
       "cartData": {
         "transactionDiscount": 6.66,
         "items": [
           {
             "itemId": "SKU_12346",
             "quantity": 2,
             "unitPrice": 21.01,
             "additionalItemParameters": [
               {
                 "parameterName": "item_name",
                 "value": "Google Grey Women's Tee"
               },
               {
                 "parameterName": "affiliation",
                 "value": "Google Merchandise Store"
               },
               {
                 "parameterName": "coupon",
                 "value": "SUMMER_FUN"
               },
               {
                 "parameterName": "discount",
                 "value": "3.33"
               },
               {
                 "parameterName": "index",
                 "value": "1"
               },
               {
                 "parameterName": "item_brand",
                 "value": "Google"
               },
               {
                 "parameterName": "item_category",
                 "value": "Apparel"
               },
               {
                 "parameterName": "item_category2",
                 "value": "Adult"
               },
               {
                 "parameterName": "item_category3",
                 "value": "Shirts"
               },
               {
                 "parameterName": "item_category4",
                 "value": "Crew"
               },
               {
                 "parameterName": "item_category5",
                 "value": "Short sleeve"
               },
               {
                 "parameterName": "item_list_id",
                 "value": "related_products"
               },
               {
                 "parameterName": "item_list_name",
                 "value": "Related Products"
               }
             ]
           }
         ]
       }
     }
  ],
  "validateOnly": true
}

본문의 자리표시자(예: OPERATING_ACCOUNT_ID 및 PRODUCT_DESTINATION_ID)를 계정 및 대상의 값으로 업데이트합니다.
validateOnly을 true로 설정하여 변경사항을 적용하지 않고 요청을 검증합니다. 변경사항을 적용할 준비가 되면 validateOnly을 false로 설정합니다.
이 예에서는 암호화를 사용하지 않습니다.

요청 전송

샘플 오른쪽 상단의 복사 버튼을 사용하여 요청 본문을 복사합니다.
툴바에서 API 버튼을 클릭합니다.
복사한 요청 본문을 요청 본문 상자에 붙여넣습니다.
실행 버튼을 클릭하고 승인 메시지를 완료한 후 응답을 검토합니다.

성공 응답

요청에 성공하면 requestId가 포함된 객체가 있는 응답이 반환됩니다.

{
  "requestId": "126365e1-16d0-4c81-9de9-f362711e250a"
}

요청의 각 대상이 처리될 때 진단을 검색할 수 있도록 반환된 requestId을 기록합니다.

실패 응답

요청이 실패하면 400 Bad Request와 같은 오류 응답 상태 코드와 오류 세부정보가 포함된 응답이 반환됩니다.

예를 들어 16진수 인코딩 값 대신 일반 텍스트 문자열이 포함된 emailAddress는 다음 응답을 생성합니다.

{
  "error": {
    "code": 400,
    "message": "There was a problem with the request.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "INVALID_ARGUMENT",
        "domain": "datamanager.googleapis.com"
      },
      {
        "@type": "type.googleapis.com/google.rpc.BadRequest",
        "fieldViolations": [
          {
            "field": "events.events[0].user_data.user_identifiers",
            "description": "Email is not hex encoded.",
            "reason": "INVALID_HEX_ENCODING"
          }
        ]
      }
    ]
  }
}

해싱되지 않고 16진수로만 인코딩된 emailAddress는 다음 응답을 생성합니다.

{
  "error": {
    "code": 400,
    "message": "There was a problem with the request.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "INVALID_ARGUMENT",
        "domain": "datamanager.googleapis.com"
      },
      {
        "@type": "type.googleapis.com/google.rpc.BadRequest",
        "fieldViolations": [
          {
            "field": "events.events[0]",
            "reason": "INVALID_SHA256_FORMAT"
          }
        ]
      }
    ]
  }
}

여러 대상에 이벤트 전송

데이터에 여러 대상의 이벤트가 포함된 경우 대상 참조를 사용하여 동일한 요청으로 전송할 수 있습니다.

예를 들어 전환 액션 ID 123456789의 이벤트와 전환 액션 ID 777111122의 이벤트가 있는 경우 각 Destination의 reference를 설정하여 단일 요청으로 두 이벤트를 모두 전송합니다. reference은 사용자 정의입니다. 각 Destination에는 고유한 reference가 있어야 합니다. 요청에 맞게 수정된 destinations 목록은 다음과 같습니다.

  "destinations": [
    {
      "operatingAccount": {
        "accountType": "OPERATING_ACCOUNT_TYPE",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "loginAccount": {
        "accountType": "LOGIN_ACCOUNT_TYPE",
        "accountId": "LOGIN_ACCOUNT_ID"
      },

      "productDestinationId": "PRODUCT_DESTINATION_ID",
      "reference": "destination_a"
    },
    {
      "operatingAccount": {
        "accountType": "OPERATING_ACCOUNT_2_TYPE",
        "accountId": "OPERATING_ACCOUNT_2_ID"
      },

      "loginAccount": {
        "accountType": "LOGIN_ACCOUNT_2_TYPE",
        "accountId": "LOGIN_ACCOUNT_2_ID"
      },

      "productDestinationId": "777111122",
      "reference": "destination_b"
    }
  ]

하나 이상의 특정 대상으로 전송되도록 각 Event의 destinationReferences을 설정합니다. 예를 들어 다음은 첫 번째 Destination에만 적용되는 Event입니다. 따라서 destinationReferences 목록에는 첫 번째 Destination의 reference만 포함됩니다.

{
   "adIdentifiers": {
      "gclid": "GCLID_1"
   },
   "conversionValue": 1.99,
   "currency": "USD",
   "eventTimestamp": "2025-06-10T20:07:01Z",
   "transactionId": "ABC798654321",
   "eventSource": "WEB",
   "destinationReferences": [
      "destination_a"
   ]
}

destinationReferences 필드는 목록이므로 이벤트의 대상을 여러 개 지정할 수 있습니다. Event의 destinationReferences를 설정하지 않으면 Data Manager API가 요청의 모든 대상으로 이벤트를 전송합니다.

이벤트에 대상이 여러 개인 경우 데이터 관리 도구 API는 관련 필드를 각 대상으로 전송합니다. 예를 들어 이벤트에 Google Ads 대상과 Google 애널리틱스 대상이 있는 경우 API는 Google 애널리틱스 대상으로 이벤트를 전송할 때 clientId 또는 eventName과 같은 Google 애널리틱스 필드를 포함하고 Google Ads 대상으로 이벤트를 전송할 때 customVariables과 같은 Google Ads 필드를 포함합니다.

다음 단계

클라이언트 라이브러리를 사용하여 인증을 구성하고 환경을 설정합니다.
각 데이터 유형의 형식 지정, 해싱, 인코딩 요구사항을 알아봅니다.
사용자 데이터를 암호화하는 방법을 알아보세요.
요청에 대한 진단을 가져오는 방법을 알아보세요.
권장사항 알아보기
한도 및 할당량에 대해 알아봅니다.

이벤트 개요

일정 보내기 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

대상 준비

이벤트 데이터 준비

이벤트 1

이벤트 2

데이터 형식 지정

이벤트 1

이벤트 2

데이터 해싱 및 인코딩

이벤트 1

이벤트 2

데이터를 Event 객체로 변환

Google 애널리틱스 정보 추가

구매 이벤트의 장바구니 데이터 추가

요청 본문 빌드

요청 전송

성공 응답

실패 응답

여러 대상에 이벤트 전송

다음 단계

일정 보내기

데이터를 `Event` 객체로 변환