The Data Manager API is in closed beta. To express interest in joining the closed beta, fill out this form.

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

일정 보내기

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

이벤트 데이터는 태그 전환의 추가 데이터 소스로, 광고 상호작용 신호를 극대화하고 데이터와 전반적인 실적을 강화합니다.

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

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

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

대상 준비

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

    {
      "operatingAccount": {
        "product": "GOOGLE_ADS",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "productDestinationId": "CONVERSION_ACTION_1_ID"
    }

operatingAccount의 accountId를 이벤트 데이터를 수신할 Google Ads 계정 ID로 설정합니다. operatingAccount의 product는 GOOGLE_ADS이어야 합니다.
productDestinationId을 이벤트의 전환 액션 ID로 설정합니다. 전환 액션은 type이 WEBPAGE로 설정된 Google Ads 전환 액션이어야 합니다.

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

이벤트 데이터 준비

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

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

첫 번째 이벤트의 데이터는 다음과 같습니다.

이벤트 #1
`conversion_time`	`2025-06-10 15:07:01-05:00`
`conversion_action_id`	`123456789`
`transaction_id`	`ABC798654321`
`conversion_value`	`1.99`
`currency`	`USD`
`gclid`	`GCLID_1`
`emails`
`given_name`	`John`
`family_name`	`Smith-Jones`
`region_code`	`us`
`postal_code`	`94045`

두 번째 이벤트의 데이터는 다음과 같습니다.

이벤트 2
`conversion_time`	`June 10, 2025 11:42:33PM America/New_York`
`conversion_action_id`	`123456789`
`transaction_id`	`DEF999911111`
`conversion_value`	`3.25`
`currency`	`eur`
`gclid`	`GCLID_2`
`emails`	`[email protected]` `[email protected]`
`given_name`	`zoë`
`family_name`	`pérez`
`region_code`	`PT`
`postal_code`	`1229-076`

데이터 형식 지정

형식 지정 가이드에 지정된 대로 필드의 형식을 지정합니다. 형식 지정 후 첫 번째 이벤트의 데이터는 다음과 같습니다.

이벤트 #1
`conversion_time`	`2025-06-10 15:07:01-05:00`
`conversion_action_id`	`123456789`
`transaction_id`	`ABC798654321`
`conversion_value`	`1.99`
`currency`	`USD`
`gclid`	`GCLID_1`
`emails`
`given_name`	`john`
`family_name`	`smith-jones`
`region_code`	`US`
`postal_code`	`94045`

형식 지정 후 두 번째 이벤트의 데이터는 다음과 같습니다.

이벤트 2
`conversion_time`	`2025-06-10T23:42:33-05:00`
`conversion_action_id`	`123456789`
`transaction_id`	`DEF999911111`
`conversion_value`	`3.25`
`currency`	`EUR`
`gclid`	`GCLID_2`
`emails`	`[email protected]` `[email protected]`
`given_name`	`zoë`
`family_name`	`pérez`
`region_code`	`PT`
`postal_code`	`1229-076`

데이터 해싱 및 인코딩

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

이벤트 #1
`conversion_time`	`2025-06-10 15:07:01-05:00`
`conversion_action_id`	`123456789`
`transaction_id`	`ABC798654321`
`conversion_value`	`1.99`
`currency`	`USD`
`gclid`	`GCLID_1`
`emails`
`given_name`	`96D9632F363564CC3032521409CF22A852F2032EEC099ED5967C0D000CEC607A`
`family_name`	`DB98D2607EFFFA28AFF66975868BF54C075ECA7157E35064DCE08E20B85B1081`
`region_code`	`US`
`postal_code`	`94045`

다음은 16진수 인코딩을 사용하여 서식을 지정하고, 해싱하고, 인코딩한 후의 두 번째 이벤트 데이터입니다.

이벤트 2
`conversion_time`	`2025-06-10T23:42:33-05:00`
`conversion_action_id`	`123456789`
`transaction_id`	`DEF999911111`
`conversion_value`	`3.25`
`currency`	`EUR`
`gclid`	`GCLID_2`
`emails`	`3E693CF7E5B67880BFF33B2D2626DADB7BF1D4BC737192E47CF8BAA89ACF2250` `223EBDA6F6889B1494551BA902D9D381DAF2F642BAE055888E96343D53E9F9C4`
`given_name`	`2752B88686847FA5C86F47B94CE652B7B3F22A91C37617D451A4DB9AFA431450`
`family_name`	`6654977D57DDDD3C0329CA741B109EF6CD6430BEDD00008AAD213DF25683D77F`
`region_code`	`PT`
`postal_code`	`1229-076`

데이터를 `Event`로 변환합니다.

각 이벤트의 형식 지정되고 해싱된 데이터를 Event로 변환합니다. 다음 필수 필드를 입력합니다.

event_timestamp: 이벤트가 발생한 시간입니다.
transaction_id: 이벤트의 고유 식별자입니다.
event_source: 이벤트의 소스입니다. 지정된 경우 WEB이어야 합니다.
ad_identifiers 또는 user_data: 이벤트에 광고 식별자 또는 사용자 데이터가 있어야 합니다. 이벤트에 대해 두 가지가 모두 있는 경우 두 가지 모두 전송합니다.

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

다음은 두 번째 이벤트에서 서식이 지정되고, 해싱되고, 인코딩된 데이터의 샘플 Event입니다.

{
   "adIdentifiers": {
      "gclid": "GCLID_2"
   },
   "conversionValue": 3.25,
   "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"
            }
         }
      ]
   }
}

요청 본문 빌드

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

{
  "destinations": [
    {
      "operatingAccount": {
        "product": "GOOGLE_ADS",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "productDestinationId": "CONVERSION_ACTION_1_ID"
    }
  ],
  "encoding": "HEX",
  "events": [
     {
       "adIdentifiers": {
         "gclid": "GCLID_1"
       },
       "conversionValue": 1.99,
       "currency": "USD",
       "eventTimestamp": "2025-06-10T20:07:01Z",
       "transactionId": "ABC798654321",
       "eventSource": "WEB",
       "userData": {
         "userIdentifiers": [
           {
             "address": {
               "givenName": "96D9632F363564CC3032521409CF22A852F2032EEC099ED5967C0D000CEC607A",
               "familyName": "DB98D2607EFFFA28AFF66975868BF54C075ECA7157E35064DCE08E20B85B1081",
               "regionCode": "US",
               "postalCode": "94045"
             }
           }
         ]
       }
     },
     {
       "adIdentifiers": {
         "gclid": "GCLID_2"
       },
       "conversionValue": 3.25,
       "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"
             }
           }
         ]
       }
     }
  ],
  "validateOnly": true
}

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

요청 전송

샘플 오른쪽 상단의 복사 버튼을 사용하여 요청 본문을 복사합니다.
events.ingest 페이지로 이동합니다.
오른쪽의 API 버튼을 클릭한 다음 확장된 섹션에서 직접 해보기 버튼을 클릭합니다.
복사한 요청 본문을 요청 본문 상자에 붙여넣습니다.
실행 버튼을 클릭하고 승인 메시지를 완료한 후 응답을 검토합니다.

성공 응답

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

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

실패 응답

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

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

{
  "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진수로만 인코딩된 email_address는 다음 응답을 생성합니다.

{
  "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": {
        "product": "GOOGLE_ADS",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "productDestinationId": "123456789"
      "reference": "conversion_action_1"
    },
    {
      "operatingAccount": {
        "product": "GOOGLE_ADS",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "productDestinationId": "777111122"
      "reference": "conversion_action_2"
    }
  ]

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

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

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

다음 단계

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

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