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,
  "fieldWarnings": [
    {
      object (FieldWarning)
    }
  ]
}
필드
requestId

string

자동 생성된 요청 ID입니다.
fieldWarnings[]

object (FieldWarning)

필드 경로가 포함된 자세한 행 수준 경고입니다.

승인 범위

다음 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,
  "callInfo": {
    object (CallInfo)
  },
  "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 앱 스트림의 앱 클라이언트 사용자 인스턴스에 대한 고유 식별자입니다.
callInfo

object (CallInfo)

선택사항입니다. 이 이벤트를 유발한 통화에 관해 수집된 정보(있는 경우)입니다.
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)
    }
  ],
  "ppid": string,
  "visitorPpid": string,
  "leadId": string
}
필드
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 수입니다.
ppid

string

선택사항입니다. 게시자가 정의한 인증된 사용자(로그인한 사용자)의 고유 식별자입니다.
visitorPpid

string

선택사항입니다. 게시자가 정의한 인증되지 않은 사용자(로그인하지 않은 사용자)의 고유 식별자입니다.
leadId

string

선택사항입니다. 사용자가 리드 양식을 제출할 때 발급되는 Google 생성 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의 두 자리 국가 코드를 대신 사용할 수 있습니다. 매장 판매 이벤트의 경우 장바구니 수준에서 설정된 값이 재정의됩니다. 이 필드는 다른 이벤트에서는 무시됩니다.
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 형식)입니다.

CallInfo

이 이벤트를 유발한 통화에 관해 수집된 정보(있는 경우)입니다.

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

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"