Method: adEvents.ingest

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

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

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)

(選用步驟) 用於加密資料的加密金鑰相關資訊。
validateOnly

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

  // Union field event_subtype_oneof can be only one of the following:
  "eventSubtype": enum (EventSubtype),
  "eventSubtypeString": string
  // End of list of possible types for union field event_subtype_oneof.

  // Union field ad_type_oneof can be only one of the following:
  "adType": enum (AdType),
  "adTypeString": string
  // End of list of possible types for union field ad_type_oneof.

  // Union field ad_format_oneof can be only one of the following:
  "adFormat": enum (AdFormat),
  "adFormatString": string
  // End of list of possible types for union field ad_format_oneof.

  // Union field ad_placement_oneof can be only one of the following:
  "adPlacement": enum (AdPlacement),
  "adPlacementString": string
  // End of list of possible types for union field ad_placement_oneof.

  // Union field targeting_type_oneof can be only one of the following:
  "targetingType": enum (TargetingType),
  "targetingTypeString": string
  // End of list of possible types for union field targeting_type_oneof.

  // Union field platform_type_oneof can be only one of the following:
  "platformType": enum (PlatformType),
  "platformTypeString": string
  // End of list of possible types for union field platform_type_oneof.

  // Union field platform_oneof can be only one of the following:
  "platform": enum (Platform),
  "platformString": string
  // End of list of possible types for union field platform_oneof.
  "measurementAllowed": boolean
}
欄位
advertiserId

string

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

這個 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)

(選用步驟) 廣告事件發生時所用裝置的相關資訊。
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)

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

聯集欄位 event_subtype_oneof。(選用步驟) 廣告事件類型的額外分類。

系統會接受原始字串，以處理純列舉以外的值。建議盡可能使用列舉。event_subtype_oneof 只能是下列其中一項：
eventSubtype

enum (EventSubtype)

活動子類型的列舉值。
eventSubtypeString

string

活動子類型的字串值。

聯集欄位 ad_type_oneof。(選用步驟) 放送的廣告類型。

系統會接受原始字串，以處理純列舉以外的值。建議盡可能使用列舉。ad_type_oneof 只能是下列其中一項：
adType

enum (AdType)

廣告類型的列舉值。
adTypeString

string

廣告類型的字串值。

聯集欄位 ad_format_oneof。(選用步驟) 放送的廣告類型。

系統會接受原始字串，以處理純列舉以外的值。建議盡可能使用列舉。ad_format_oneof 只能是下列其中一項：
adFormat

enum (AdFormat)

廣告格式的列舉值。
adFormatString

string

廣告格式的字串值。

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

系統會接受原始字串，以處理純列舉以外的值。建議盡可能使用列舉。ad_placement_oneof 只能是下列其中一項：
adPlacement

enum (AdPlacement)

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

string

廣告刊登位置的字串值。

聯集欄位 targeting_type_oneof。(選用步驟) 用於放送廣告的指定目標類型。

系統會接受原始字串，以處理純列舉以外的值。建議盡可能使用列舉。targeting_type_oneof 只能是下列其中一項：
targetingType

enum (TargetingType)

指定目標類型的列舉值。
targetingTypeString

string

指定類型的字串值。

聯集欄位 platform_type_oneof。(選用步驟) 放送廣告的平台類型。

系統會接受原始字串，以處理純列舉以外的值。建議盡可能使用列舉。platform_type_oneof 只能是下列其中一項：
platformType

enum (PlatformType)

平台類型的列舉值。
platformTypeString

string

平台類型的字串值。

聯集欄位 platform_oneof。(選用步驟) 放送廣告的平台詳細資料。

系統會接受原始字串，以處理純列舉以外的值。建議盡可能使用列舉。platform_oneof 只能是下列其中一項：
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 媒體評議會已查看。
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 完成。