REST Resource: firstAndThirdPartyAudiences

资源:FirstAndThirdPartyAudience

描述用于定位的第一方或第三方受众群体名单。第一方受众群体是通过使用客户数据创建的。第三方受众群体由第三方数据提供商提供,且只能授予客户使用。

JSON 表示法
{
  "name": string,
  "firstAndThirdPartyAudienceId": string,
  "displayName": string,
  "description": string,
  "firstAndThirdPartyAudienceType": enum (FirstAndThirdPartyAudienceType),
  "audienceType": enum (AudienceType),
  "audienceSource": enum (AudienceSource),
  "membershipDurationDays": string,
  "displayAudienceSize": string,
  "activeDisplayAudienceSize": string,
  "youtubeAudienceSize": string,
  "gmailAudienceSize": string,
  "displayMobileAppAudienceSize": string,
  "displayMobileWebAudienceSize": string,
  "displayDesktopAudienceSize": string,
  "appId": string,

  // Union field members can be only one of the following:
  "contactInfoList": {
    object (ContactInfoList)
  },
  "mobileDeviceIdList": {
    object (MobileDeviceIdList)
  }
  // End of list of possible types for union field members.
}
字段
name

string

仅限输出。第一方和第三方受众群体的资源名称。

firstAndThirdPartyAudienceId

string (int64 format)

仅限输出。第一方和第三方受众群体的唯一 ID。由系统分配。

displayName

string

第一方和第三方受众群体的显示名称。

description

string

用户提供的受众群体说明。

仅适用于第一方受众群体。

firstAndThirdPartyAudienceType

enum (FirstAndThirdPartyAudienceType)

受众群体是第一方受众群体还是第三方受众群体。

audienceType

enum (AudienceType)

受众群体的类型。

audienceSource

enum (AudienceSource)

仅限输出。受众群体的来源。

membershipDurationDays

string (int64 format)

符合条件的活动结束后,相应作品在受众群体中保留的时长(以天为单位)。如果受众群体没有到期时间,请将此字段的值设置为 10000。否则,设置值必须大于 0 且小于或等于 540。

仅适用于第一方受众群体。

如果使用了以下某个 audienceType,则该字段是必需的:

  • CUSTOMER_MATCH_CONTACT_INFO
  • CUSTOMER_MATCH_DEVICE_ID
displayAudienceSize

string (int64 format)

仅限输出。展示广告网络的估算受众群体规模。

如果大小小于 1000,出于保护隐私的考虑,该数字将被隐藏并返回 0。否则,该数字将被四舍五入为两位有效数字。

仅在 GET 请求中返回。

activeDisplayAudienceSize

string (int64 format)

仅限输出。展示广告网络上个月的估算受众群体规模。

如果大小小于 1000,出于保护隐私的考虑,该数字将被隐藏并返回 0。否则,该数字将被四舍五入为两位有效数字。

仅在 GET 请求中返回。

youtubeAudienceSize

string (int64 format)

仅限输出。YouTube 广告网络的估算受众群体规模。

如果大小小于 1000,出于保护隐私的考虑,该数字将被隐藏并返回 0。否则,该数字将被四舍五入为两位有效数字。

仅适用于第一方受众群体。

仅在 GET 请求中返回。

gmailAudienceSize

string (int64 format)

仅限输出。Gmail 广告网络的估算受众群体规模。

如果大小小于 1000,出于保护隐私的考虑,该数字将被隐藏并返回 0。否则,该数字将被四舍五入为两位有效数字。

仅适用于第一方受众群体。

仅在 GET 请求中返回。

displayMobileAppAudienceSize

string (int64 format)

仅限输出。展示广告网络上的移动应用受众群体规模估算值。

如果大小小于 1000,出于保护隐私的考虑,该数字将被隐藏并返回 0。否则,该数字将被四舍五入为两位有效数字。

仅适用于第一方受众群体。

仅在 GET 请求中返回。

displayMobileWebAudienceSize

string (int64 format)

仅限输出。展示广告网络中的移动网络受众群体规模估算值。

如果大小小于 1000,出于保护隐私的考虑,该数字将被隐藏并返回 0。否则,该数字将被四舍五入为两位有效数字。

仅适用于第一方受众群体。

仅在 GET 请求中返回。

displayDesktopAudienceSize

string (int64 format)

仅限输出。展示广告网络中的桌面设备受众群体规模估算值。

如果大小小于 1000,出于保护隐私的考虑,该数字将被隐藏并返回 0。否则,该数字将被四舍五入为两位有效数字。

仅适用于第一方受众群体。

仅在 GET 请求中返回。

appId

string

appId 与要上传的 mobileDeviceId 的类型匹配。

仅适用于 audienceType CUSTOMER_MATCH_DEVICE_ID

联合字段 members。目标客户匹配受众群体的初始成员。members 只能是下列其中一项:
contactInfoList

object (ContactInfoList)

仅限输入。用于定义初始受众群体成员的联系信息列表。

仅适用于 audienceType CUSTOMER_MATCH_CONTACT_INFO

mobileDeviceIdList

object (MobileDeviceIdList)

仅限输入。用于定义初始受众群体成员的移动设备 ID 列表。

仅适用于 audienceType CUSTOMER_MATCH_DEVICE_ID

FirstAndThirdPartyAudienceType

第一方和第三方受众群体资源的可能类型。

枚举
FIRST_AND_THIRD_PARTY_AUDIENCE_TYPE_UNSPECIFIED 未指定类型或类型未知时的默认值。
FIRST_AND_THIRD_PARTY_AUDIENCE_TYPE_FIRST_PARTY 通过使用客户数据创建的受众群体。
FIRST_AND_THIRD_PARTY_AUDIENCE_TYPE_THIRD_PARTY 由第三方数据提供商提供的受众群体。

AudienceType

可能的受众群体类型。

枚举
AUDIENCE_TYPE_UNSPECIFIED 未指定类型或类型未知时的默认值。
CUSTOMER_MATCH_CONTACT_INFO 受众群体是通过将客户与已知联系信息进行匹配生成的。
CUSTOMER_MATCH_DEVICE_ID 受众群体是通过将客户与已知的移动设备 ID 进行匹配生成的。
CUSTOMER_MATCH_USER_ID 受众群体是通过将客户与已知用户 ID 进行匹配来生成的。
ACTIVITY_BASED

根据广告系列活动创建受众群体。

FREQUENCY_CAP

受众群体是在排除已投放的展示次数的情况下创建的。

TAG_BASED 受众群体是根据附加到像素的自定义变量创建的。
YOUTUBE_USERS 受众群体是根据以往与视频、YouTube 广告或 YouTube 频道的互动情况创建的。
LICENSED 第三方受众群体类型的子类型。

AudienceSource

可能的受众群体来源。

枚举
AUDIENCE_SOURCE_UNSPECIFIED 未指定受众群体来源或受众群体来源未知时的默认值。
DISPLAY_VIDEO_360 来源:展示广告和Video 360。
CAMPAIGN_MANAGER 来源于 Campaign Manager 360。
AD_MANAGER 源自 Google Ad Manager。
SEARCH_ADS_360 来源于 Search Ads 360。
YOUTUBE 源自 YouTube。
ADS_DATA_HUB 来源:广告数据中心。

ContactInfoList

用来定义目标客户匹配受众群体成员的联系信息列表的封装容器消息。

JSON 表示法
{
  "contactInfos": [
    {
      object (ContactInfo)
    }
  ],
  "consent": {
    object (Consent)
  }
}
字段
contactInfos[]

object (ContactInfo)

定义目标客户匹配受众群体成员的 ContactInfo 对象列表。拆分 contactInfo 后,成员的大小不得超过 500,000。

consent

object (Consent)

仅限输入。contactInfos 中用户的用户意见征求设置。

如果未设置此字段,则表示未指定意见征求状态。

如果 adUserDataadPersonalization 字段设置为 CONSENT_STATUS_DENIED,请求将返回错误。

ContactInfo

定义目标客户匹配受众群体成员的联系信息。

JSON 表示法
{
  "hashedEmails": [
    string
  ],
  "hashedPhoneNumbers": [
    string
  ],
  "zipCodes": [
    string
  ],
  "hashedFirstName": string,
  "hashedLastName": string,
  "countryCode": string
}
字段
hashedEmails[]

string

成员经过 SHA256 哈希处理的电子邮件地址列表。在进行哈希处理之前,移除所有空格并确保字符串全部为小写。

hashedPhoneNumbers[]

string

成员经过 SHA256 哈希处理的电话号码列表。在进行哈希处理之前,所有电话号码都必须采用 E.164 格式,并包含国家/地区呼叫代码。

zipCodes[]

string

成员的邮政编码列表。

还必须使用以下字段进行设置:

hashedFirstName

string

经过 SHA256 哈希处理的成员名字。在进行哈希处理之前,移除所有空格并确保字符串全部为小写。

还必须使用以下字段进行设置:

hashedLastName

string

经过 SHA256 哈希处理的成员姓氏。在进行哈希处理之前,移除所有空格并确保字符串全部为小写。

还必须使用以下字段进行设置:

countryCode

string

成员的国家/地区代码。

还必须使用以下字段进行设置:

ConsentStatus

用户意见状态。

枚举
CONSENT_STATUS_UNSPECIFIED 未指定类型值或此版本中的类型值未知。
CONSENT_STATUS_GRANTED 用户选择同意。
CONSENT_STATUS_DENIED 用户选择拒绝。

MobileDeviceIdList

包含定义目标客户匹配受众群体成员的移动设备 ID 列表的封装容器消息。

JSON 表示法
{
  "mobileDeviceIds": [
    string
  ],
  "consent": {
    object (Consent)
  }
}
字段
mobileDeviceIds[]

string

定义目标客户匹配受众群体成员的移动设备 ID 列表。mobileDeviceId 的大小不得超过 500,000。

consent

object (Consent)

仅限输入。mobileDeviceIds 中用户的用户意见征求设置。

如果未设置此字段,则表示未指定意见征求状态。

如果 adUserDataadPersonalization 字段设置为 CONSENT_STATUS_DENIED,请求将返回错误。

方法

create

创建一个 FirstAndThirdPartyAudience。

editCustomerMatchMembers

更新目标客户匹配受众群体的成员列表。

get

获取第一方和第三方受众群体。

list

列出第一方受众群体和第三方受众群体。

patch

更新现有 FirstAndThirdPartyAudience。