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,
  "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

(選用步驟) 這項事件的專屬 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

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

number

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

enum (EventSource)

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

object (DeviceInfo)

(選用步驟) 事件發生時使用的裝置 (如有) 相關資訊。
cartData

object (CartData)

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

object (CustomVariable)

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

object (ExperimentalField)

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

object (UserProperties)

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

AdIdentifiers

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

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

string

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

string

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

string

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

string

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

object (DeviceInfo)

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

DeviceInfo

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

JSON 表示法 
{
  "userAgent": string,
  "ipAddress": string
}
欄位
userAgent

string

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

string

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

注意：Google Ads 不支援為歐洲經濟區、英國或瑞士的使用者比對 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

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

string

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

string

(選用步驟) 與商品 Merchant Center 動態饋給相關聯的 ISO 639-1 語言代碼，也就是商品上傳目的地。
transactionDiscount

number

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

object (Item)

(選用步驟) 與活動相關聯的項目清單。

項目

代表與活動相關聯的購物車項目。

JSON 表示法 
{
  "merchantProductId": string,
  "quantity": string,
  "unitPrice": number
}
欄位
merchantProductId

string

(選用步驟) Merchant Center 帳戶中的產品 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 顧客價值高。