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)

必填。要傳送至指定目的地的事件清單。單一要求最多可傳送 2000 個 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
}
欄位
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
}
欄位
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。
conversionValue

number

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

AdIdentifiers

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

JSON 表示法 
{
  "sessionAttributes": string,
  "gclid": string,
  "gbraid": string,
  "wbraid": string,
  "landingPageDeviceInfo": {
    object (DeviceInfo)
  },
  "mobileDeviceId": string
}
欄位
sessionAttributes

string

(選用步驟) 用於事件歸因和模擬的工作階段屬性。
gclid

string

(選用步驟) 與這個事件相關聯的 Google 點擊 ID (gclid)。
gbraid

string

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

string

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

object (DeviceInfo)

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

string

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

DeviceInfo

事件發生時使用的裝置資訊 (如有)。

JSON 表示法 
{
  "userAgent": string,
  "ipAddress": string,
  "category": string,
  "languageCode": string,
  "screenHeight": integer,
  "screenWidth": integer,
  "operatingSystem": string,
  "operatingSystemVersion": string,
  "model": string,
  "brand": string,
  "browser": string,
  "browserVersion": string
}
欄位
userAgent

string

(選用步驟) 指定情境的裝置使用者代理程式字串。
ipAddress

string

(選用步驟) 指定情境中裝置的 IP 位址。

附註：Google Ads 不支援歐洲經濟區 (EEA)、英國 (UK) 或瑞士 (CH) 境內使用者的 IP 位址比對功能。請加入邏輯，有條件地排除分享來自這些地區使用者的 IP 位址，並確保提供清楚詳盡的資訊，讓使用者瞭解在網站、應用程式及其他資源收集的資料，並在法律或任何適用的 Google 政策要求時，徵得使用者同意聲明。詳情請參閱「關於離線轉換匯入」頁面。
category

string

(選用步驟) 裝置類別。例如「桌機」、「平板電腦」、「行動裝置」、「智慧型電視」。
languageCode

string

(選用步驟) 裝置使用的語言，格式為 ISO 639-1。
screenHeight

integer

(選用步驟) 螢幕高度 (以像素為單位)。
screenWidth

integer

(選用步驟) 螢幕寬度 (以像素為單位)。
operatingSystem

string

(選用步驟) 裝置的作業系統或平台。
operatingSystemVersion

string

(選用步驟) 作業系統或平台版本。
model

string

(選用步驟) 裝置型號。
brand

string

(選用步驟) 裝置品牌。
browser

string

(選用步驟) 瀏覽器的品牌或類型。
browserVersion

string

(選用步驟) 瀏覽器版本。

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)

(選用步驟) 與這個事件相關聯的使用者任何其他使用者屬性的 bucket。

CustomerType

與事件相關聯的顧客類型。

列舉
CUSTOMER_TYPE_UNSPECIFIED 未指定 CustomerType。請一律不使用這個值。
NEW 顧客是廣告主的新客。
RETURNING 顧客回訪廣告主網站。
REENGAGED 顧客重新與廣告主互動。

CustomerValueBucket

廣告主評估的顧客價值。

列舉
CUSTOMER_VALUE_BUCKET_UNSPECIFIED 未指定 CustomerValueBucket。請一律不使用這個值。
LOW 顧客價值偏低。
MEDIUM 顧客價值中等。
HIGH 顧客價值高。

UserProperty

與這個事件相關聯的使用者任何其他使用者屬性的 bucket。

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 格式)。