Method: events.ingest

從提供的 Destination 上傳 Event 資源清單。

HTTP 要求

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

這個網址使用 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。使用者 ID 的編碼類型。如果是經雜湊處理的使用者 ID，這是雜湊字串的編碼類型。如果是加密的雜湊使用者 ID，這是外部加密字串的編碼類型，但不一定是內部雜湊字串，也就是說，內部雜湊字串的編碼方式可能與外部加密字串不同。如果上傳的不是 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

(選用步驟) 這個事件的專屬 ID。如要將事件做為代碼轉換的其他資料來源，則必須提供這項資訊。
eventTimestamp

string (Timestamp format)

必填。事件發生的時間。

使用 RFC 3339，產生的輸出內容一律會經過 Z 正規化，並使用 0、3、6 或 9 個小數位數，也接受「Z」以外的偏移量。範例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
lastUpdatedTimestamp

string (Timestamp format)

(選用步驟) 上次更新事件的時間。

使用 RFC 3339，產生的輸出內容一律會經過 Z 正規化，並使用 0、3、6 或 9 個小數位數，也接受「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)

(選用步驟) 用於比對轉換事件與其他線上活動 (例如廣告點擊) 的 ID 和其他資訊。
currency

string

(選用步驟) 與此事件中所有金額相關聯的貨幣代碼。
eventSource

enum (EventSource)

(選用步驟) 事件發生位置 (網站、應用程式、店內等) 的信號。
eventDeviceInfo

object (DeviceInfo)

(選用步驟) 事件發生時，系統收集到的裝置相關資訊 (如有)。
cartData

object (CartData)

(選用步驟) 與事件相關聯的交易和項目資訊。
customVariables[]

object (CustomVariable)

(選用步驟) 要傳送至轉換容器 (轉換動作或 Floodlight 活動) 的其他鍵/值組合資訊。
experimentalFields[]

object (ExperimentalField)

(選用步驟) 實驗性欄位的鍵/值組合清單，這些欄位最終可能會升級為 API 的一部分。
userProperties

object (UserProperties)

(選用步驟) 廣告主在事件發生時評估的使用者相關資訊。
eventName

string

(選用步驟) 事件名稱。GA4 事件的必要參數。
clientId

string

(選用步驟) 這個 GA4 網站串流的網頁用戶端使用者執行個體專屬 ID。
userId

string

(選用步驟) 廣告主定義的使用者專屬 ID。
additionalEventParameters[]

object (EventParameter)

(選用步驟) 一組要納入事件中的事件參數，且尚未透過其他結構化欄位指定。
thirdPartyUserData

object (UserData)

(選用步驟) 與 userData 提供的資料類型相同，但明確標示為第三方提供的資料，而非第一方廣告主資料。
eventLocation

object (EventLocation)

(選用步驟) 發生此事件時，收集到的使用者位置資訊。
appInstanceId

string

(選用步驟) 這個 GA4 應用程式串流的應用程式用戶端使用者執行個體專屬 ID。
callInfo

object (CallInfo)

(選用步驟) 收集到的通話相關資訊 (如果有的話)，這類通話會導致這項事件。
conversionValue

number

(選用步驟) 與事件相關聯的轉換價值 (適用於以價值為準轉換)。
conversionCount

number

(選用步驟) 與事件相關聯的轉換數量 (適用於以計數為基礎的轉換)。

AdIdentifiers

用於比對轉換事件與其他線上活動 (例如廣告點擊) 的 ID 和其他資訊。

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

(選用步驟) 源自搭載 iOS 14 以上版本的 iOS 裝置，且與應用程式事件相關聯的點擊 ID。
wbraid

string

(選用步驟) 源自搭載 iOS 14 以上版本的 iOS 裝置，且與網站事件相關聯的點擊 ID。
landingPageDeviceInfo

object (DeviceInfo)

(選用步驟) 使用者與廣告互動後，到達廣告主網站時所用裝置 (如有) 的相關資訊。
mobileDeviceId

string

(選用步驟) 廣告主行動 ID。例如 iOS 的廣告識別碼、Android 的廣告 ID，或其他平台的廣告主 ID。
dclid

string

(選用步驟) 與此事件相關聯的多媒體點擊 ID。
impressionId

string

(選用步驟) 與這個事件相關聯的曝光 ID。
matchId

string

(選用步驟) 比對 ID 欄位，用於將這個事件與先前的事件彙整。
encryptedUserIds[]

object (EncryptedUserId)

(選用步驟) 任意數量的加密使用者 ID。
ppid

string

(選用步驟) 由發布商定義，用於識別已驗證 (登入) 使用者的專屬 ID。
visitorPpid

string

(選用步驟) 未經驗證使用者 (未登入的使用者) 的專屬 ID，由發布商定義。
leadId

string

(選用步驟) 使用者提交待開發客戶表單時，Google 產生的 ID。

EncryptedUserId

用於歸因的使用者 ID。如要使用，所有欄位均為必填。

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)

必填。說明加密 Cookie 是從廣告放送 (%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

(選用步驟) 與商品相關聯的 Merchant Center ID。
merchantFeedLabel

string

(選用步驟) 與商品動態饋給相關聯的 Merchant Center 動態饋給標籤。
merchantFeedLanguageCode

string

(選用步驟) 與商品 Merchant Center 動態饋給相關聯的 ISO 639-1 語言代碼。
transactionDiscount

number

(選用步驟) 與交易相關聯的所有折扣總和。
items[]

object (Item)

(選用步驟) 與事件相關聯的項目清單。
couponCodes[]

string

(選用步驟) 套用至購物車的優惠碼清單。購物車層級和商品層級的優惠碼各自獨立。

如果事件的目的地是 Google Analytics，請只提供一組優惠碼。Google Analytics 會忽略額外的優惠碼。

項目

代表與事件相關聯的購物車商品。

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

(選用步驟) Merchant Center 帳戶中的產品 ID。
quantity

string (int64 format)

(選用步驟) 與事件相關聯的商品數量。
unitPrice

number

(選用步驟) 單價 (不含稅金、運費和任何交易層級折扣)。
itemId

string

(選用步驟) 參照項目的專屬 ID。
additionalItemParameters[]

object (ItemParameter)

(選用步驟) 一組與項目相關的事件參數，用於納入事件中，且尚未透過其他結構化欄位指定。
merchantId

string

(選用步驟) 與商品相關聯的 Merchant Center ID。如果是商店銷售事件，這項設定會覆寫購物車層級設定的值。其他事件會忽略這個欄位。
merchantFeedLabel

string

(選用步驟) Merchant Center 動態饋給的動態饋給標籤。如果仍要使用國家/地區，可以改用 ISO-3166-1 alpha-2 的雙字母國家/地區代碼。如果是商店銷售事件，這項設定會覆寫購物車層級設定的值。其他事件會忽略這個欄位。
merchantFeedLanguageCode

string

(選用步驟) 上傳商品時所在的 Merchant Center 動態饋給，其相關聯的 ISO 639-1 語言代碼。
customVariables[]

object (ItemCustomVariable)

(選用步驟) 追蹤個別商品轉換時，要傳送至轉換容器 (轉換動作或 Floodlight 活動) 的其他鍵/值組合資訊。
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

(選用步驟) 商店銷售的必要條件。代表事件發生實體商店的 ID。
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)

必填。導致這項事件的通話開始時間。

使用 RFC 3339，產生的輸出內容一律會經過 Z 正規化，並使用 0、3、6 或 9 個小數位數，也接受「Z」以外的偏移量。例如："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。