Method: events.ingest

제공된 Destination에서 Event 리소스 목록을 업로드합니다.

HTTP 요청

POST https://datamanager.googleapis.com/v1/events:ingest

URL은 gRPC 트랜스코딩 구문을 사용합니다.

요청 본문

요청 본문에는 다음과 같은 구조의 데이터가 포함됩니다.

JSON 표현 
{
  "destinations": [
    {
      object (Destination)
    }
  ],
  "events": [
    {
      object (Event)
    }
  ],
  "consent": {
    object (Consent)
  },
  "validateOnly": boolean,
  "encoding": enum (Encoding),
  "encryptionInfo": {
    object (EncryptionInfo)
  }
}
필드
destinations[]

object (Destination)

필수입니다. 이벤트를 보낼 대상 목록입니다.
events[]

object (Event)

필수입니다. 지정된 대상에 전송할 이벤트 목록입니다. 단일 요청에서 최대 2,000개의 Event 리소스를 전송할 수 있습니다.
consent

object (Consent)

선택사항입니다. 요청의 모든 사용자에게 적용되는 요청 수준 동의입니다. 사용자 수준 동의는 요청 수준 동의보다 우선하며 각 Event에서 지정할 수 있습니다.
validateOnly

boolean

선택사항입니다. 테스트 목적으로 사용됩니다. true인 경우 요청이 검증되지만 실행되지는 않습니다. 결과가 아닌 오류만 반환됩니다.
encoding

enum (Encoding)

선택사항입니다. UserData 업로드에 필요합니다. 사용자 식별자의 인코딩 유형입니다. 해싱된 사용자 식별자의 경우 해싱된 문자열의 인코딩 유형입니다. 암호화된 해시 사용자 식별자의 경우 이는 외부 암호화된 문자열의 인코딩 유형이지만 내부 해시 문자열은 아닐 수 있습니다. 즉, 내부 해시 문자열은 외부 암호화된 문자열과 다른 방식으로 인코딩될 수 있습니다. UserData이 아닌 업로드의 경우 이 필드는 무시됩니다.
encryptionInfo

object (EncryptionInfo)

선택사항입니다. UserData 업로드의 암호화 정보입니다. 설정되지 않은 경우 업로드된 식별 정보가 해싱되었지만 암호화되지 않은 것으로 간주됩니다. UserData이 아닌 업로드의 경우 이 필드는 무시됩니다.

응답 본문

IngestEventsRequest의 응답입니다.

성공한 경우 응답 본문은 다음과 같은 구조의 데이터를 포함합니다.

JSON 표현 
{
  "requestId": string
}
필드
requestId

string

요청의 자동 생성 ID입니다.

승인 범위

다음 OAuth 범위가 필요합니다.

  • https://www.googleapis.com/auth/datamanager

이벤트

사용자와 광고주의 웹사이트 또는 앱 간의 상호작용을 나타내는 이벤트입니다.

JSON 표현 
{
  "destinationReferences": [
    string
  ],
  "transactionId": string,
  "eventTimestamp": string,
  "lastUpdatedTimestamp": string,
  "userData": {
    object (UserData)
  },
  "consent": {
    object (Consent)
  },
  "adIdentifiers": {
    object (AdIdentifiers)
  },
  "currency": string,
  "conversionValue": number,
  "eventSource": enum (EventSource),
  "eventDeviceInfo": {
    object (DeviceInfo)
  },
  "cartData": {
    object (CartData)
  },
  "customVariables": [
    {
      object (CustomVariable)
    }
  ],
  "experimentalFields": [
    {
      object (ExperimentalField)
    }
  ],
  "userProperties": {
    object (UserProperties)
  }
}
필드
destinationReferences[]

string

선택사항입니다. 대상을 결정하는 데 사용되는 참조 문자열입니다. 비어 있으면 이벤트가 요청의 모든 destinations에 전송됩니다.
transactionId

string

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

string (Timestamp format)

필수입니다. 이벤트가 발생한 시간입니다.

생성된 출력은 항상 Z-정규화되고 소수점 이하 0, 3, 6 또는 9자리인 RFC 3339를 사용합니다. 'Z' 이외의 오프셋도 허용됩니다. 예를 들면 "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" 또는 "2014-10-02T15:01:23+05:30"입니다.
lastUpdatedTimestamp

string (Timestamp format)

선택사항입니다. 이벤트가 마지막으로 업데이트된 시간입니다.

생성된 출력은 항상 Z-정규화되고 소수점 이하 0, 3, 6 또는 9자리인 RFC 3339를 사용합니다. 'Z' 이외의 오프셋도 허용됩니다. 예를 들면 "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" 또는 "2014-10-02T15:01:23+05:30"입니다.
userData

object (UserData)

선택사항입니다. 이벤트와 연결된 사용자를 나타내는 사용자 제공 데이터입니다.
consent

object (Consent)

선택사항입니다. 연결된 사용자가 다양한 유형의 동의를 제공했는지 여부에 관한 정보입니다.
adIdentifiers

object (AdIdentifiers)

선택사항입니다. 전환 이벤트를 광고 클릭과 같은 다른 온라인 활동과 일치시키는 데 사용되는 식별자 및 기타 정보입니다.
currency

string

선택사항입니다. 이 이벤트 내의 모든 금전적 가치와 연결된 통화 코드입니다.
conversionValue

number

선택사항입니다. 가치 기반 전환의 경우 이벤트와 연결된 전환 가치입니다.
eventSource

enum (EventSource)

선택사항입니다. 이벤트가 발생한 위치 (웹, 앱, 매장 등)를 나타내는 신호입니다.
eventDeviceInfo

object (DeviceInfo)

선택사항입니다. 이벤트가 발생했을 때 사용 중인 기기에 관해 수집된 정보입니다 (있는 경우).
cartData

object (CartData)

선택사항입니다. 거래 및 이벤트와 연결된 상품에 대한 정보입니다.
customVariables[]

object (CustomVariable)

선택사항입니다. 전환 컨테이너 (전환 액션 또는 FL 활동)로 전송할 추가 키/값 쌍 정보입니다.
experimentalFields[]

object (ExperimentalField)

선택사항입니다. 실험용 필드의 키-값 쌍 목록입니다. 실험용 필드는 결국 API의 일부로 승격될 수 있습니다.
userProperties

object (UserProperties)

선택사항입니다. 이벤트가 발생한 시점에 광고주가 평가한 사용자에 관한 정보입니다.

AdIdentifiers

전환 이벤트를 광고 클릭과 같은 다른 온라인 활동과 일치시키는 데 사용되는 식별자 및 기타 정보입니다.

JSON 표현 
{
  "sessionAttributes": string,
  "gclid": string,
  "gbraid": string,
  "wbraid": string,
  "landingPageDeviceInfo": {
    object (DeviceInfo)
  }
}
필드
sessionAttributes

string

선택사항입니다. 이벤트 기여 분석 및 모델링을 위한 세션 속성입니다.
gclid

string

선택사항입니다. 이 이벤트와 연결된 Google 클릭 ID (gclid)입니다.
gbraid

string

선택사항입니다. iOS14부터 iOS 기기에서 발생하고 앱 이벤트와 연결된 클릭의 클릭 식별자입니다.
wbraid

string

선택사항입니다. iOS14부터 웹 이벤트와 연결되고 iOS 기기에서 발생한 클릭의 클릭 식별자입니다.
landingPageDeviceInfo

object (DeviceInfo)

선택사항입니다. 광고와 상호작용한 후 광고주의 사이트에 방문할 때 사용 중인 기기에 관해 수집된 정보입니다 (있는 경우).

DeviceInfo

이벤트가 발생했을 때 사용 중인 기기에 관한 정보입니다 (있는 경우).

JSON 표현 
{
  "userAgent": string,
  "ipAddress": string
}
필드
userAgent

string

선택사항입니다. 지정된 컨텍스트의 기기 사용자 에이전트 문자열입니다.
ipAddress

string

선택사항입니다. 지정된 컨텍스트의 기기 IP 주소입니다.

참고: Google Ads는 유럽 경제 지역 (EEA), 영국 (UK), 스위스 (CH)의 최종 사용자에 대한 IP 주소 일치를 지원하지 않습니다. 이러한 지역의 사용자의 IP 주소 공유를 조건부로 제외하는 로직을 추가하고, 사이트, 앱, 기타 속성에서 수집하는 데이터에 대해 명확하고 포괄적인 정보를 사용자에게 제공하고 법률 또는 관련 Google 정책에서 요구하는 경우 동의를 얻어야 합니다. 자세한 내용은 오프라인 전환 가져오기 정보 페이지를 참고하세요.

EventSource

이벤트의 소스입니다.

열거형
EVENT_SOURCE_UNSPECIFIED 지정되지 않은 EventSource입니다. 절대로 사용하지 마세요.
WEB 이 이벤트는 웹브라우저에서 생성되었습니다.
APP 앱에서 생성된 이벤트입니다.
IN_STORE 이 이벤트는 오프라인 거래에서 생성되었습니다.
PHONE 이 이벤트는 전화 통화에서 생성되었습니다.
OTHER 이 이벤트는 다른 소스에서 생성되었습니다.

CartData

이벤트와 연결된 장바구니 데이터입니다.

JSON 표현 
{
  "merchantId": string,
  "merchantFeedLabel": string,
  "merchantFeedLanguageCode": string,
  "transactionDiscount": number,
  "items": [
    {
      object (Item)
    }
  ]
}
필드
merchantId

string

선택사항입니다. 상품과 연결된 판매자 센터 ID입니다.
merchantFeedLabel

string

선택사항입니다. 상품 피드와 연결된 판매자 센터 피드 라벨입니다.
merchantFeedLanguageCode

string

선택사항입니다. 상품이 업로드된 판매자 센터 피드와 연결된 ISO 639-1의 언어 코드입니다.
transactionDiscount

number

선택사항입니다. 거래와 관련된 모든 할인 금액의 합계입니다.
items[]

object (Item)

선택사항입니다. 이벤트와 연결된 항목 목록입니다.

항목

이벤트와 연결된 장바구니의 상품을 나타냅니다.

JSON 표현 
{
  "merchantProductId": string,
  "quantity": string,
  "unitPrice": number
}
필드
merchantProductId

string

선택사항입니다. 판매자 센터 계정 내 제품 ID입니다.
quantity

string (int64 format)

선택사항입니다. 이 이벤트와 연결된 상품의 수입니다.
unitPrice

number

선택사항입니다. 세금, 배송비, 거래별 할인 금액을 제외한 단위 가격입니다.

CustomVariable

광고 전환의 맞춤 변수입니다.

JSON 표현 
{
  "variable": string,
  "value": string,
  "destinationReferences": [
    string
  ]
}
필드
variable

string

선택사항입니다. 설정할 맞춤 변수의 이름입니다. 지정된 대상에 변수가 없으면 무시됩니다.
value

string

선택사항입니다. 맞춤 변수에 저장할 값입니다.
destinationReferences[]

string

선택사항입니다. 맞춤 변수를 전송할 Event.destination_references를 결정하는 데 사용되는 참조 문자열입니다. 비어 있으면 Event.destination_references가 사용됩니다.

ExperimentalField

비공식 필드를 나타내는 실험용 필드입니다.

JSON 표현 
{
  "field": string,
  "value": string
}
필드
field

string

선택사항입니다. 사용할 필드의 이름입니다.
value

string

선택사항입니다. 설정할 필드의 값입니다.

UserProperties

이벤트가 발생한 시점에 광고주가 평가한 사용자에 관한 정보입니다. 자세한 내용은 https://support.google.com/google-ads/answer/14007601을 참고하세요.

JSON 표현 
{
  "customerType": enum (CustomerType),
  "customerValueBucket": enum (CustomerValueBucket)
}
필드
customerType

enum (CustomerType)

선택사항입니다. 이벤트와 연결된 고객 유형입니다.
customerValueBucket

enum (CustomerValueBucket)

선택사항입니다. 광고주가 평가한 고객의 가치입니다.

CustomerType

이벤트와 연결된 고객 유형입니다.

열거형
CUSTOMER_TYPE_UNSPECIFIED 지정되지 않은 CustomerType입니다. 절대로 사용하지 마세요.
NEW 고객이 광고주를 처음 이용합니다.
RETURNING 고객이 광고주에게 반품합니다.
REENGAGED 고객이 광고주와 다시 상호작용했습니다.

CustomerValueBucket

광고주가 평가한 고객의 가치입니다.

열거형
CUSTOMER_VALUE_BUCKET_UNSPECIFIED 지정되지 않은 CustomerValueBucket입니다. 절대로 사용하지 마세요.
LOW 고객의 가치가 낮습니다.
MEDIUM 고객이 중간 가치입니다.
HIGH 고객의 가치가 높습니다.