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,
  "eventSource": enum (EventSource),
  "eventDeviceInfo": {
    object (DeviceInfo)
  },
  "cartData": {
    object (CartData)
  },
  "customVariables": [
    {
      object (CustomVariable)
    }
  ],
  "experimentalFields": [
    {
      object (ExperimentalField)
    }
  ],
  "userProperties": {
    object (UserProperties)
  },
  "eventName": string,
  "clientId": string,
  "userId": string,
  "additionalEventParameters": [
    {
      object (EventParameter)
    }
  ],
  "thirdPartyUserData": {
    object (UserData)
  },
  "eventLocation": {
    object (EventLocation)
  },
  "appInstanceId": string,
  "conversionValue": number,
  "conversionCount": number
}
필드
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

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

enum (EventSource)

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

object (DeviceInfo)

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

object (CartData)

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

object (CustomVariable)

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

object (ExperimentalField)

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

object (UserProperties)

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

string

선택사항입니다. 이벤트 이름 GA4 이벤트에 필요합니다.
clientId

string

선택사항입니다. 이 GA4 웹 스트림의 웹 클라이언트 사용자 인스턴스의 고유 식별자입니다.
userId

string

선택사항입니다. 광고주가 정의한 사용자의 고유 식별자입니다.
additionalEventParameters[]

object (EventParameter)

선택사항입니다. 다른 구조화된 필드를 사용하여 아직 지정되지 않은 이벤트 내에 포함할 이벤트 매개변수 버킷입니다.
thirdPartyUserData

object (UserData)

선택사항입니다. userData에 제공된 것과 동일한 유형의 데이터이지만, 퍼스트 파티 광고주 데이터가 아닌 서드 파티가 소유한 데이터로 제공된다고 명시적으로 표시됩니다.
eventLocation

object (EventLocation)

선택사항입니다. 이 이벤트가 발생했을 때 사용자의 위치에 관해 수집된 정보입니다.
appInstanceId

string

선택사항입니다. 이 GA4 앱 스트림의 앱 클라이언트 사용자 인스턴스의 고유 식별자입니다.
conversionValue

number

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

number

선택사항입니다. 카운팅 기반 전환의 경우 이벤트와 관련된 전환 수량입니다.

AdIdentifiers

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

JSON 표현 
{
  "sessionAttributes": string,
  "gclid": string,
  "gbraid": string,
  "wbraid": string,
  "landingPageDeviceInfo": {
    object (DeviceInfo)
  },
  "mobileDeviceId": string,
  "dclid": string,
  "impressionId": string,
  "matchId": string,
  "encryptedUserIds": [
    {
      object (EncryptedUserId)
    }
  ]
}
필드
sessionAttributes

string

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

string

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

string

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

string

선택사항입니다. iOS14 이후의 iOS 기기에서 발생해 웹 이벤트와 연결된 클릭의 클릭 식별자입니다.
landingPageDeviceInfo

object (DeviceInfo)

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

string

선택사항입니다. 광고주의 모바일 식별자입니다. iOS의 경우 IDFA, Android의 경우 AdID, 기타 플랫폼의 경우 광고주 식별자가 이에 해당합니다.
dclid

string

선택사항입니다. 이 이벤트와 연결된 디스플레이 클릭 ID입니다.
impressionId

string

선택사항입니다. 이 이벤트와 연결된 노출 ID입니다.
matchId

string

선택사항입니다. 이 이벤트를 이전 이벤트와 조인하는 데 사용되는 일치 ID 필드입니다.
encryptedUserIds[]

object (EncryptedUserId)

선택사항입니다. 암호화된 사용자 ID의 수입니다.

EncryptedUserId

기여도 분석에 사용하도록 발급된 사용자 식별자입니다. 이 식별자를 사용하는 경우 모든 필드가 필수입니다.

JSON 표현 
{
  "encryptedId": string,
  "entityType": enum (EncryptionEntityType),
  "entityId": string,
  "source": enum (EncryptionSource)
}
필드
encryptedId

string

필수 항목입니다. 영숫자 암호화 ID입니다.
entityType

enum (EncryptionEntityType)

필수 항목입니다. 암호화 엔티티 유형입니다. 이는 광고 게재 또는 데이터 전송의 암호화 구성과 일치해야 합니다.
entityId

string (int64 format)

필수 항목입니다. 암호화 엔티티 ID입니다. 이는 광고 게재 또는 데이터 전송의 암호화 구성과 일치해야 합니다.
source

enum (EncryptionSource)

필수 항목입니다. 암호화된 쿠키가 광고 게재(%m 매크로)에서 수신되었는지 아니면 데이터 전송에서 수신되었는지 설명합니다.

EncryptionEntityType

암호화 엔티티 유형입니다.

열거형
ENCRYPTION_ENTITY_TYPE_UNSPECIFIED 지정되지 않은 암호화 엔티티 유형입니다.
CAMPAIGN_MANAGER_ACCOUNT Campaign Manager 360 계정
CAMPAIGN_MANAGER_ADVERTISER Campaign Manager 360 광고주
DISPLAY_VIDEO_PARTNER Display & Video 360 파트너입니다.
DISPLAY_VIDEO_ADVERTISER Display & Video 360 광고주
GOOGLE_ADS_CUSTOMER Google Ads 고객
GOOGLE_AD_MANAGER_NETWORK_CODE Google Ad Manager 네트워크 코드입니다.

EncryptionSource

암호화 소스입니다.

열거형
ENCRYPTION_SOURCE_UNSPECIFIED 지정되지 않은 암호화 소스입니다.
AD_SERVING 광고 게재 암호화 소스입니다.
DATA_TRANSFER 데이터 전송 암호화 소스입니다.

EventSource

이벤트의 소스입니다.

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

CartData

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

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

string

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

string

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

string

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

number

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

object (Item)

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

string

선택사항입니다. 장바구니에 적용된 쿠폰 코드 목록입니다. 장바구니 수준 및 상품 수준 쿠폰 코드는 독립적입니다.

이벤트가 Google 애널리틱스 대상인 경우 쿠폰 코드를 하나만 제공하세요. Google 애널리틱스에서는 추가 쿠폰 코드를 무시합니다.

항목

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

JSON 표현 
{
  "merchantProductId": string,
  "quantity": string,
  "unitPrice": number,
  "itemId": string,
  "additionalItemParameters": [
    {
      object (ItemParameter)
    }
  ],
  "merchantId": string,
  "merchantFeedLabel": string,
  "merchantFeedLanguageCode": string,
  "customVariables": [
    {
      object (ItemCustomVariable)
    }
  ],
  "conversionValue": number
}
필드
merchantProductId

string

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

string (int64 format)

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

number

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

string

선택사항입니다. 상품을 참조하는 고유 식별자입니다.
additionalItemParameters[]

object (ItemParameter)

선택사항입니다. 다른 구조화된 필드를 사용하여 아직 지정되지 않은 이벤트에 포함할 항목과 관련된 이벤트 매개변수의 버킷입니다.
merchantId

string

선택사항입니다. 상품과 연결된 판매자 센터 ID입니다. 오프라인 매장 판매 이벤트의 경우 장바구니 수준에서 설정된 값이 재정의됩니다. 다른 이벤트에서는 이 필드가 무시됩니다.
merchantFeedLabel

string

선택사항입니다. 판매자 센터 피드의 피드 라벨입니다. 국가가 계속 사용되는 경우 ISO-3166-1 alpha-2의 2자리 국가 코드를 대신 사용할 수 있습니다. 오프라인 매장 판매 이벤트의 경우 장바구니 수준에서 설정된 값이 재정의됩니다. 다른 이벤트에서는 이 필드가 무시됩니다.
merchantFeedLanguageCode

string

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

object (ItemCustomVariable)

선택사항입니다. 상품별 전환을 추적할 때 전환 컨테이너 (전환 액션 또는 플러드라이트 활동)로 전송할 추가 키/값 쌍 정보입니다.
conversionValue

number

선택사항입니다. 전환 가치가 항목마다 다른 경우 이벤트 내에서 이 항목과 연결된 전환 가치입니다.

ItemParameter

다른 구조화된 필드를 사용하여 아직 지정되지 않은 이벤트에 포함할 항목과 관련된 이벤트 매개변수의 버킷입니다.

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

string

필수 항목입니다. 사용할 매개변수의 이름입니다.
value

string

필수 항목입니다. 설정할 매개변수 값의 문자열 표현입니다.

ItemCustomVariable

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

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

string

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

string

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

string

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

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),
  "additionalUserProperties": [
    {
      object (UserProperty)
    }
  ]
}
필드
customerType

enum (CustomerType)

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

enum (CustomerValueBucket)

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

object (UserProperty)

선택사항입니다. 이 이벤트와 연결된 사용자의 추가 사용자 속성 버킷입니다.

CustomerType

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

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

CustomerValueBucket

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

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

UserProperty

이 이벤트와 연결된 사용자의 추가 사용자 속성 버킷입니다.

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

string

필수 항목입니다. 사용할 사용자 속성의 이름입니다.
value

string

필수 항목입니다. 사용할 사용자 속성 값의 문자열 표현입니다.

EventParameter

GA4 이벤트의 이벤트 매개변수입니다.

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

string

필수 항목입니다. 사용할 매개변수의 이름입니다.
value

string

필수 항목입니다. 설정할 매개변수 값의 문자열 표현입니다.

EventLocation

이벤트가 발생한 위치입니다.

JSON 표현 
{
  "storeId": string,
  "city": string,
  "subdivisionCode": string,
  "regionCode": string,
  "subcontinentCode": string,
  "continentCode": string
}
필드
storeId

string

선택사항입니다. 오프라인 매장 판매에 필요합니다. 이벤트가 발생한 오프라인 상점을 나타내는 식별자입니다.
city

string

선택사항입니다. 이벤트가 발생한 도시의 이름입니다.
subdivisionCode

string

선택사항입니다. 이벤트가 발생한 ISO 3166-2 하위 행정 구역 코드입니다.
regionCode

string

선택사항입니다. 사용자 주소의 2자리 CLDR 지역 코드입니다.
subcontinentCode

string

선택사항입니다. 이벤트가 발생한 아대륙 코드로, UN M49 형식입니다.
continentCode

string

선택사항입니다. 이벤트가 발생한 대륙 코드(UN M49 형식)입니다.