Method: adEvents.ingest

將 AdEvent 資源清單上傳至 Google Analytics。

這項功能僅適用於已加入許可清單的帳戶。

授權標頭：

這個方法也需要下列標頭，定義 API 如何授權要求存取權：

  • login-account：(必要) 憑證的 Google 帳戶所屬資料合作夥伴帳戶的資源名稱。格式：accountTypes/DATA_PARTNER/accounts/{loginAccountId}

HTTP 要求

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

這個網址使用 gRPC 轉碼語法。

要求主體

要求主體會包含結構如下的資料：

JSON 表示法 
{
  "adEvents": [
    {
      object (AdEvent)
    }
  ],
  "encryptionInfo": {
    object (EncryptionInfo)
  },
  "validateOnly": boolean
}
欄位
adEvents[]

object (AdEvent)

必填。必要 (至少 1 個)。廣告事件清單。
encryptionInfo

object (EncryptionInfo)

(選用步驟) 用於加密資料的加密金鑰相關資訊。如果廣告事件包含 UserData，則必須提供這個欄位。
validateOnly
(deprecated)

boolean

(選用步驟) 如果是 True，系統會驗證要求，但不會執行要求。

回應主體

如果成功，回應主體會是空白。

授權範圍

需要下列 OAuth 範圍：

  • https://www.googleapis.com/auth/datamanager

AdEvent

廣告事件。

JSON 表示法 
{
  "advertiserId": string,
  "eventType": enum (EventType),
  "timestamp": string,
  "eventId": string,
  "userData": {
    object (UserData)
  },
  "deviceInfo": {
    object (DeviceInfo)
  },
  "ipAddress": string,
  "mobileDeviceId": string,
  "campaignId": string,
  "campaignName": string,
  "adGroupId": string,
  "adId": string,
  "adHeight": integer,
  "adWidth": integer,
  "regionCode": string,
  "source": string,
  "medium": string,
  "attributionHint": enum (AttributionHint),
  "viewabilityInfo": {
    object (ViewabilityInfo)
  },

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "eventSubtype": enum (EventSubtype),
  "eventSubtypeString": string
  // End of mutually exclusive fields.

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "adType": enum (AdType),
  "adTypeString": string
  // End of mutually exclusive fields.

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "adFormat": enum (AdFormat),
  "adFormatString": string
  // End of mutually exclusive fields.

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "adPlacement": enum (AdPlacement),
  "adPlacementString": string
  // End of mutually exclusive fields.

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "targetingType": enum (TargetingType),
  "targetingTypeString": string
  // End of mutually exclusive fields.

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "platformType": enum (PlatformType),
  "platformTypeString": string
  // End of mutually exclusive fields.

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "platform": enum (Platform),
  "platformString": string
  // End of mutually exclusive fields.
  "measurementAllowed": boolean
}
欄位
advertiserId

string

必填。廣告事件的廣告主 ID。

必須與連結流程中傳送的 ID 相符。
eventType

enum (EventType)

必填。事件的類型。
timestamp

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"。
eventId

string

(選用步驟) 由呼叫端建立及管理的 ID，可專屬識別這個事件。

如要為多個請求中包含的廣告事件去重複，則為必要欄位。否則，這個欄位為選填。
userData

object (UserData)

(選用步驟) 多筆使用者提供的資料，代表與事件相關聯的使用者。

您可以提供相同類型資料的多個執行個體 (例如電子郵件地址)。提供的資料越多，就越有可能找到相符的資料。
deviceInfo

object (DeviceInfo)

必填。廣告事件發生時所用裝置的相關資訊。
ipAddress

string

(選用步驟) 用於評估的 IP 位址。此值必須與 DeviceInfo.ip_address 相同。如不想分享 IP 進行評估，請將此欄位留空。
mobileDeviceId

string

(選用步驟) 放送廣告的裝置 ID。
campaignId

string

必填。相關聯廣告活動的 ID。
campaignName

string

必填。相關聯廣告活動的名稱。
adGroupId

string

(選用步驟) 相關聯廣告群組的 ID。
adId

string

(選用步驟) 群組中相關聯廣告的 ID。
adHeight

integer

(選用步驟) 廣告高度 (以像素為單位)。
adWidth

integer

(選用步驟) 廣告寬度 (以像素為單位)。
regionCode

string

(選用步驟) ISO 3166-2 國家/地區和子區域。
source

string

必填。廣告的平台來源，類似於 Google Analytics 來源。
medium

string

必填。廣告的媒介，類似於 Google Analytics 媒介。
attributionHint

enum (AttributionHint)

(選用步驟) 合作夥伴為這個廣告事件假設的歸因狀態。

這項資訊僅做為合作夥伴假設歸因結果的信號，不會強制最終報表顯示特定結果。
viewabilityInfo

object (ViewabilityInfo)

必填。已放送廣告的可視度詳細資料。

(選用步驟) 廣告事件類型的額外分類。

系統會接受原始字串，以處理純列舉以外的值。如果可以，建議使用列舉。以下列出互斥欄位。回應中最多會設定一個欄位：
eventSubtype

enum (EventSubtype)

活動子類型的列舉值。
eventSubtypeString

string

活動子類型的字串值。
互斥欄位的結尾。

(選用步驟) 放送的廣告類型。

系統會接受原始字串，以處理純列舉以外的值。如果可以，建議使用列舉。以下列出互斥欄位。回應中最多會設定一個欄位：
adType

enum (AdType)

廣告類型的列舉值。
adTypeString

string

廣告類型的字串值。
互斥欄位的結尾。

(選用步驟) 放送的廣告類型。

系統會接受原始字串，以處理純列舉以外的值。如果可以，建議使用列舉。以下列出互斥欄位。回應中最多會設定一個欄位：
adFormat

enum (AdFormat)

廣告格式的列舉值。
adFormatString

string

廣告格式的字串值。
互斥欄位的結尾。

(選用步驟) 放送廣告的刊登位置。

系統會接受原始字串，以處理純列舉以外的值。如果可以，建議使用列舉。以下列出互斥欄位。回應中最多會設定一個欄位：
adPlacement

enum (AdPlacement)

廣告刊登位置的列舉值。
adPlacementString

string

廣告刊登位置的字串值。
互斥欄位的結尾。

(選用步驟) 用於放送廣告的指定目標類型。

系統會接受原始字串，以處理純列舉以外的值。如果可以，建議使用列舉。以下列出互斥欄位。回應中最多會設定一個欄位：
targetingType

enum (TargetingType)

指定類型的列舉值。
targetingTypeString

string

指定類型的字串值。
互斥欄位的結尾。

(選用步驟) 放送廣告的平台類型。

系統會接受原始字串，以處理純列舉以外的值。如果可以，建議使用列舉。以下列出互斥欄位。回應中最多會設定一個欄位：
platformType

enum (PlatformType)

平台類型的列舉值。
platformTypeString

string

平台類型的字串值。
互斥欄位的結尾。

(選用步驟) 放送廣告的平台詳細資料。

系統會接受原始字串，以處理純列舉以外的值。如果可以，建議使用列舉。以下列出互斥欄位。回應中最多會設定一個欄位：
platform

enum (Platform)

平台的列舉值。
platformString

string

平台的字串值。
互斥欄位的結尾。
measurementAllowed

boolean

(選用步驟) 表示是否允許將資料列用於評估用途，這類用途受區域管轄範圍內適用的隱私權法律規範。

EventType

事件的類型。

列舉
EVENT_TYPE_UNSPECIFIED 未指定的事件類型。
EVENT_TYPE_VIEW 查看活動。
EVENT_TYPE_CLICK 點擊事件。

EventSubtype

廣告事件類型的額外分類。

列舉
EVENT_SUBTYPE_UNSPECIFIED 未指定事件子類型。
EVENT_SUBTYPE_IMPRESSION 曝光事件。
EVENT_SUBTYPE_ENGAGED_VIEW 參與收視事件。
EVENT_SUBTYPE_ONSITE_CLICK 網站點擊事件。
EVENT_SUBTYPE_OUTBOUND_CLICK 外連點擊事件。

AdType

放送的廣告類型。

列舉
AD_TYPE_UNSPECIFIED 未指定廣告類型。
AD_TYPE_DISPLAY 多媒體廣告。
AD_TYPE_TEXT 。
AD_TYPE_IMAGE 圖像廣告。
AD_TYPE_RICH_MEDIA 互動式多媒體廣告。
AD_TYPE_HTML HTML 廣告。
AD_TYPE_AUDIO 音訊廣告。
AD_TYPE_VIDEO 影片廣告。

AdFormat

放送的廣告格式。

列舉
AD_FORMAT_UNSPECIFIED 未指定廣告格式。
AD_FORMAT_AR AR 廣告。
AD_FORMAT_AUDIO 音訊廣告。
AD_FORMAT_BANNER 橫幅廣告。
AD_FORMAT_BUMPER 串場廣告。
AD_FORMAT_COLLECTION 集合廣告。
AD_FORMAT_IMAGE 圖像廣告。
AD_FORMAT_INTERACTIVE 互動式廣告。
AD_FORMAT_INTERSTITIAL 插頁式廣告。
AD_FORMAT_IN_FEED 動態內廣告。
AD_FORMAT_IN_STREAM 串流內廣告。
AD_FORMAT_IN_STREAM_SKIPPABLE 可略過的串流內廣告。
AD_FORMAT_IN_STREAM_NON_SKIPPABLE 不可略過的串流內廣告。
AD_FORMAT_NATIVE 原生廣告。
AD_FORMAT_SHORTS Shorts 廣告。
AD_FORMAT_STORY 故事廣告。
AD_FORMAT_SPONSORED 贊助廣告。
AD_FORMAT_VIDEO 影片廣告。

AdPlacement

放送廣告的刊登位置。

列舉
AD_PLACEMENT_UNSPECIFIED 未指定廣告刊登位置。
AD_PLACEMENT_DISCOVER 探索刊登位置。
AD_PLACEMENT_FEED 動態饋給刊登位置。
AD_PLACEMENT_HEADER 標頭位置。
AD_PLACEMENT_HOME 首頁刊登位置。
AD_PLACEMENT_IN_CONTENT 內容中刊登位置。
AD_PLACEMENT_PROMOTED 宣傳刊登位置。
AD_PLACEMENT_STORY 故事刊登位置。

TargetingType

用於放送廣告的指定目標類型。

列舉
TARGETING_TYPE_UNSPECIFIED 未指定指定類型。
TARGETING_TYPE_AUDIENCE 指定目標對象。
TARGETING_TYPE_CONTEXTUAL 內容比對。
TARGETING_TYPE_DEMOGRAPHIC 指定客層。
TARGETING_TYPE_DEVICE 指定裝置。
TARGETING_TYPE_GEO 指定地理區域。
TARGETING_TYPE_INTEREST 指定興趣。
TARGETING_TYPE_PURCHASE_INTENT 購買意願指定目標。
TARGETING_TYPE_REMARKETING 再行銷指定目標。

平台類型

放送廣告的平台類型。

列舉
PLATFORM_TYPE_UNSPECIFIED 未指定平台類型。
PLATFORM_TYPE_MOBILE 行動平台。
PLATFORM_TYPE_DESKTOP 桌機平台。
PLATFORM_TYPE_CTV 連網電視平台。
PLATFORM_TYPE_PHONE 手機平台。
PLATFORM_TYPE_TABLET 平板電腦平台。

平台

放送廣告的平台詳細資料。

列舉
PLATFORM_UNSPECIFIED 未指定平台。
PLATFORM_IOS iOS 平台。
PLATFORM_ANDROID Android 平台。
PLATFORM_WEB 網路平台。

AttributionHint

合作夥伴為這個廣告事件假設的歸因狀態。

列舉
ATTRIBUTION_HINT_UNSPECIFIED 歸因狀態不明。
ATTRIBUTION_HINT_CONVERTED 轉換狀態。
ATTRIBUTION_HINT_NOT_CONVERTED 未轉換狀態。

ViewabilityInfo

已放送廣告的可視度詳細資料。

JSON 表示法 
{
  "viewType": enum (ViewType),
  "viewablePercent": integer,
  "viewableDuration": string,
  "mediaSkippable": boolean,
  "mediaQuartile": enum (MediaQuartile),
  "mediaDuration": string,
  "mediaVolumePercent": integer,
  "playbackDuration": string
}
欄位
viewType

enum (ViewType)

必填。事件的類型。
viewablePercent

integer

(選用步驟) 可視像素的百分比 (0 到 100)。
viewableDuration

string (Duration format)

(選用步驟) 廣告可視時間長度。

以秒為單位的時間長度，最多 9 個小數位數，結尾為「s」。示例："3.5s"。
mediaSkippable

boolean

(選用步驟) 廣告媒體是否可略過。
mediaQuartile

enum (MediaQuartile)

(選用步驟) 媒體播放量 (以四分位數表示)。
mediaDuration

string (Duration format)

(選用步驟) 廣告媒體的時間長度。

以秒為單位的時間長度，最多 9 個小數位數，結尾為「s」。示例："3.5s"。
mediaVolumePercent

integer

(選用步驟) 媒體播放音量的百分比 (0 到 100)。
playbackDuration

string (Duration format)

(選用步驟) 廣告媒體的播放時間長度，無論廣告是否可視。

以秒為單位的時間長度，最多 9 個小數位數，結尾為「s」。示例："3.5s"。

ViewType

事件的類型。

列舉
VIEW_TYPE_UNSPECIFIED 未指定檢視畫面類型。
VIEW_TYPE_MRC_VIEWED 已查看 MRC。
VIEW_TYPE_MRC_RENDERED MRC 呈現。

MediaQuartile

媒體播放量 (以四分位數表示)。

列舉
MEDIA_QUARTILE_UNSPECIFIED 未指定媒體四分位數。
MEDIA_QUARTILE_START 。
MEDIA_QUARTILE_FIRST_QUARTILE 播完四分之一。
MEDIA_QUARTILE_MIDPOINT 中點。
MEDIA_QUARTILE_THIRD_QUARTILE 播完四分之三。
MEDIA_QUARTILE_COMPLETE 完成。