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 规范化（即转换为 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)

可选。广告事件发生时所用设备的相关信息。
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 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 完成。