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)

可选。用于加密数据加密密钥的相关信息。如果广告事件包含 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 必须与关联流程中发送的 ID 一致。
eventType

enum (EventType)

必需。事件的类型。
timestamp

string (Timestamp format)

必需。事件发生的时间。

采用 RFC 3339 标准，生成的输出将始终进行 Z 规范化（即转换为 UTC 零时区格式并在末尾附加 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 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 再营销定位。

PlatformType

投放广告的平台类型。

枚举
PLATFORM_TYPE_UNSPECIFIED 未指定平台类型。
PLATFORM_TYPE_MOBILE 移动平台。
PLATFORM_TYPE_DESKTOP 桌面设备平台。
PLATFORM_TYPE_CTV CTV 平台。
PLATFORM_TYPE_PHONE 手机平台。
PLATFORM_TYPE_TABLET 平板电脑平台。

平台

广告投放平台的更详细信息。

枚举
PLATFORM_UNSPECIFIED 未指定平台。
PLATFORM_IOS iOS 平台。
PLATFORM_ANDROID Android 平台。
PLATFORM_WEB 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)

可选。广告的可见时长。

该时长以秒为单位，最多包含九个小数位，以“s”结尾。示例："3.5s"。
mediaSkippable

boolean

可选。广告媒体是否可跳过。
mediaQuartile

enum (MediaQuartile)

可选。以离散四分位数形式播放的媒体量。
mediaDuration

string (Duration format)

可选。广告媒体时长。

该时长以秒为单位，最多包含九个小数位，以“s”结尾。示例："3.5s"。
mediaVolumePercent

integer

可选。媒体播放音量的数值百分比 (0-100)。
playbackDuration

string (Duration format)

可选。广告媒体的播放时长，无论广告是否可见。

该时长以秒为单位，最多包含九个小数位，以“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 完成。