이 빠른 시작을 통해 이벤트 데이터 전송에 익숙해질 수 있습니다.
다음 시나리오 중 하나에 데이터 관리 도구 API를 사용하세요.
온라인 이벤트: 태그 전환의 추가 데이터 소스로 이벤트 데이터를 전송하여 광고 상호작용 신호를 극대화하고 데이터와 전반적인 실적을 강화합니다.
오프라인 이벤트: 오프라인 전환 또는 리드 확보용 향상된 전환의 이벤트 데이터를 전송합니다.
확인할 가이드 버전을 선택하세요.
이 빠른 시작에서는 다음 단계를 완료합니다.
- 이벤트 데이터를 수신할
Destination을 준비합니다. - 전송할 이벤트 데이터를 준비합니다.
- 이벤트에 대한
IngestionService요청을 빌드합니다. - Google API 탐색기로 요청을 보냅니다.
- 성공 및 실패 응답을 이해합니다.
대상 준비
데이터를 전송하려면 먼저 데이터를 전송할 대상을 준비해야 합니다. 다음은 사용할 수 있는 샘플 Destination입니다.
{
"operatingAccount": {
"accountType": "GOOGLE_ADS",
"accountId": "OPERATING_ACCOUNT_ID"
},
"productDestinationId": "CONVERSION_ACTION_1_ID"
}
operatingAccount의accountId를 이벤트 데이터를 수신할 Google Ads 계정 ID로 설정합니다.operatingAccount의accountType는GOOGLE_ADS이어야 합니다.productDestinationId을 이벤트의 전환 액션 ID로 설정합니다. 온라인 이벤트의 경우 전환 액션이type이WEBPAGE로 설정된 Google Ads 전환 액션이어야 합니다. 오프라인 이벤트의 경우 전환 액션은type이UPLOAD_CLICKS로 설정된 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 |
customer_type |
NEW |
customer_value_bucket |
HIGH |
두 번째 이벤트의 데이터는 다음과 같습니다.
| 이벤트 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 |
|
given_name |
zoë |
family_name |
pérez |
region_code |
PT |
postal_code |
1229-076 |
customer_type |
RETURNING |
데이터 형식 지정
형식 지정 가이드에 지정된 대로 필드의 형식을 지정합니다. 형식 지정 후 첫 번째 이벤트의 데이터는 다음과 같습니다.
| 이벤트 #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 |
customer_type |
NEW |
customer_value_bucket |
HIGH |
형식 지정 후 두 번째 이벤트의 데이터는 다음과 같습니다.
| 이벤트 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 |
|
given_name |
zoë |
family_name |
pérez |
region_code |
PT |
postal_code |
1229-076 |
customer_type |
RETURNING |
데이터 해싱 및 인코딩
또한 형식이 지정된 이메일 주소, 이름, 성은 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 |
customer_type |
NEW |
customer_value_bucket |
HIGH |
다음은 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 |
|
given_name |
2752B88686847FA5C86F47B94CE652B7B3F22A91C37617D451A4DB9AFA431450 |
family_name |
6654977D57DDDD3C0329CA741B109EF6CD6430BEDD00008AAD213DF25683D77F |
region_code |
PT |
postal_code |
1229-076 |
customer_type |
RETURNING |
데이터를 Event로 변환합니다.
각 이벤트의 형식 지정되고 해싱된 데이터를 Event로 변환합니다. 다음 필수 필드를 입력합니다.
event_timestamp: 이벤트가 발생한 시간입니다.event_source: 이벤트의 소스입니다. 오프라인 이벤트에 필요합니다. 온라인 이벤트의 경우 선택사항입니다. 온라인 이벤트에 지정된 경우WEB이어야 합니다.ad_identifiers또는user_data: 이벤트에 광고 식별자 또는 사용자 데이터가 있어야 합니다. 이벤트에 대해 두 가지가 모두 있는 경우 두 가지 모두 전송합니다.
실적과 데이터 강도를 높이기 위해 오프라인 전환을 추가 데이터 소스로 전송하는 경우 transaction_id가 필요합니다. 그렇지 않으면 transaction_id는 선택사항이지만 권장됩니다.
사용 가능한 필드의 전체 목록은 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"
}
}
],
"userProperties": {
"customerType": "RETURNING"
}
}
}
요청 본문 빌드
요청 본문의 Destination 및 Events을 결합합니다.
{
"destinations": [
{
"operatingAccount": {
"accountType": "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"
}
}
]
},
"userProperties": {
"customerType": "NEW",
"customerValueBucket": "HIGH"
}
},
{
"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"
}
}
]
},
"userProperties": {
"customerType": "RETURNING"
}
}
],
"validateOnly": true
}
- 본문의 자리표시자(예:
OPERATING_ACCOUNT_ID및CONVERSION_ACTION_1_ID)를 계정 및 대상의 값으로 업데이트합니다. validateOnly을true로 설정하여 변경사항을 적용하지 않고 요청을 검증합니다. 변경사항을 적용할 준비가 되면validateOnly을false로 설정합니다.- 이 예에서는 암호화를 사용하지 않습니다.
요청 전송
- 샘플 오른쪽 상단의 복사 버튼을 사용하여 요청 본문을 복사합니다.
- 툴바에서 API 버튼을 클릭합니다.
- 복사한 요청 본문을 요청 본문 상자에 붙여넣습니다.
- 실행 버튼을 클릭하고 승인 메시지를 완료한 후 응답을 검토합니다.
성공 응답
요청에 성공하면 requestId가 포함된 객체가 있는 응답이 반환됩니다.
{
"requestId": "126365e1-16d0-4c81-9de9-f362711e250a"
}
요청의 각 대상이 처리될 때 진단을 검색할 수 있도록 반환된 requestId을 기록합니다.
실패 응답
요청이 실패하면 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": {
"accountType": "GOOGLE_ADS",
"accountId": "OPERATING_ACCOUNT_ID"
},
"productDestinationId": "123456789",
"reference": "conversion_action_1"
},
{
"operatingAccount": {
"accountType": "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가 요청의 모든 대상으로 이벤트를 전송합니다.
다음 단계
- 클라이언트 라이브러리를 사용하여 인증을 구성하고 환경을 설정합니다.
- 각 데이터 유형의 형식 지정, 해싱, 인코딩 요구사항을 알아봅니다.
- 사용자 데이터를 암호화하는 방법을 알아보세요.
- 요청에 대한 진단을 가져오는 방법을 알아보세요.
- 권장사항 알아보기
- 한도 및 할당량에 대해 알아봅니다.