您网站的访问者

最简单的细分受众群类型包括您网站的访问者。

前提条件

要创建和定位细分受众群,您首先需要执行以下操作:

  1. 查看 针对用户兴趣和地理位置投放广告的政策。 与用户有关的敏感信息不能用于构建受众群体。

  2. 设置 Google 代码。

    希望根据移动应用行为创建用户名单的广告客户应 实施 Firebase SDK 或与第三方 SDK 合作以跟踪 应用内行为

检索 Google 代码

所有 Google Ads 账号只有一个账号一级的 Google 代码, 。

您可以按照帮助中心的相关说明在 Google Ads 界面中获取 Google 代码 说明或参阅 Google Ads API:创建 RemarketingAction,然后获取 Google 代码 方法是发出 GoogleAdsService.searchStream 请求(使用 remarketing_action) 资源:

SELECT
  remarketing_action.id,
  remarketing_action.name,
  remarketing_action.tag_snippets
FROM remarketing_action
WHERE remarketing_action.resource_name = 'REMARKETING_ACTION_RESOURCE_NAME'

在您的网站或应用中添加 Google 代码

下一步是在网站的所有网页上添加 Google 代码。学习 详细了解如何将 Google 代码添加到您的网站或移动应用 app

如果您打算仅根据访问过的网页网址构建细分受众群, 无需对 Google 代码进行任何修改。如果您使用的是自定义 参数,则需要修改代码以添加这些参数,详见高级 植入代码和创建再营销的策略 列表

您可以使用 Google Tag Assistant 来验证 代码添加情况

内置 Google 代码参数

您可以使用内置的再营销参数url__来定位用户名单 根据用户在您的网站上访问过的网址来调整流量,如 您网站的访问者 示例

自定义 Google 代码参数

您可以添加自定义 Google 代码 参数 添加到 Google 代码中,以创建更有针对性的用户名单。

在创建您自己的自定义参数之前,请先查看 预定义的参数 已经适合您的应用场景。使用预定义参数 可以更轻松地与其他 Google Ads 再营销功能集成。

创建用户列表

您需要创建一个用户列表,其中包含触发了 。创建和管理用户名单 UserListService

要创建包含访问过您网站上任意网页的所有用户的列表, 设置rule_based_user_list字段 使用 RuleBasedUserListInfo 对象的 UserList

接下来,指定 FlexibleRuleUserListInfo字段已开启 您的 RuleBasedUserListInfo 对象,其中包含一条规则,该规则针对符合以下条件的用户: 访问过您网站的用户

创建基于规则的用户名单的代码示例

Java

private String createUserList(GoogleAdsClient googleAdsClient, long customerId) {
  // Creates a rule targeting any user that visited a url containing 'example.com'.
  UserListRuleItemInfo rule =
      UserListRuleItemInfo.newBuilder()
          // Uses a built-in parameter to create a domain URL rule.
          .setName("url__")
          .setStringRuleItem(
              UserListStringRuleItemInfo.newBuilder()
                  .setOperator(UserListStringRuleItemOperator.CONTAINS)
                  .setValue("example.com")
                  .build())
          .build();

  // Specifies that the user list targets visitors of a page based on the provided rule.
  FlexibleRuleUserListInfo flexibleRuleUserListInfo =
      FlexibleRuleUserListInfo.newBuilder()
          .setInclusiveRuleOperator(UserListFlexibleRuleOperator.AND)
          // Inclusive operands are joined together with the specified inclusiveRuleOperator.
          .addInclusiveOperands(
              FlexibleRuleOperandInfo.newBuilder()
                  .setRule(
                      UserListRuleInfo.newBuilder()
                          .addRuleItemGroups(
                              UserListRuleItemGroupInfo.newBuilder().addRuleItems(rule)))
                  // Optional: adds a lookback window for this rule, in days.
                  .setLookbackWindowDays(7L))
          .build();

  // Defines a representation of a user list that is generated by a rule.
  RuleBasedUserListInfo ruleBasedUserListInfo =
      RuleBasedUserListInfo.newBuilder()
          // Optional: To include past users in the user list, set the prepopulation_status to
          // REQUESTED.
          .setPrepopulationStatus(UserListPrepopulationStatus.REQUESTED)
          .setFlexibleRuleUserList(flexibleRuleUserListInfo)
          .build();

  // Creates the user list.
  UserList userList =
      UserList.newBuilder()
          .setName("All visitors to example.com" + getPrintableDateTime())
          .setDescription("Any visitor to any page of example.com")
          .setMembershipStatus(UserListMembershipStatus.OPEN)
          .setMembershipLifeSpan(365)
          .setRuleBasedUserList(ruleBasedUserListInfo)
          .build();

  // Creates the operation.
  UserListOperation operation = UserListOperation.newBuilder().setCreate(userList).build();

  // Creates the user list service client.
  try (UserListServiceClient userListServiceClient =
      googleAdsClient.getLatestVersion().createUserListServiceClient()) {
    // Adds the user list.
    MutateUserListsResponse response =
        userListServiceClient.mutateUserLists(
            Long.toString(customerId), ImmutableList.of(operation));
    String userListResourceName = response.getResults(0).getResourceName();
    // Prints the result.
    System.out.printf("Created user list with resource name '%s'.%n", userListResourceName);
    return userListResourceName;
  }
}

      

C#

private string CreateUserList(GoogleAdsClient client, long customerId)
{
    // Get the UserListService client.
    UserListServiceClient userListServiceClient =
        client.GetService(Services.V17.UserListService);

    // Create a rule targeting any user that visited a url containing 'example.com'.
    UserListRuleItemInfo rule = new UserListRuleItemInfo
    {
        // Use a built-in parameter to create a domain URL rule.
        Name = "url__",
        StringRuleItem = new UserListStringRuleItemInfo
        {
            Operator = UserListStringRuleItemOperator.Contains,
            Value = "example.com"
        }
    };

    // Specify that the user list targets visitors of a page based on the provided rule.
    FlexibleRuleUserListInfo flexibleRuleUserListInfo = new FlexibleRuleUserListInfo();
    FlexibleRuleOperandInfo flexibleRuleOperandInfo = new FlexibleRuleOperandInfo() {
        Rule = new UserListRuleInfo()
    };
    UserListRuleItemGroupInfo userListRuleItemGroupInfo = new UserListRuleItemGroupInfo();
    userListRuleItemGroupInfo.RuleItems.Add(rule);
    flexibleRuleOperandInfo.Rule.RuleItemGroups.Add(userListRuleItemGroupInfo);
    flexibleRuleUserListInfo.InclusiveOperands.Add(flexibleRuleOperandInfo);

    // Define a representation of a user list that is generated by a rule.
    RuleBasedUserListInfo ruleBasedUserListInfo = new RuleBasedUserListInfo
    {
        // Optional: To include past users in the user list, set the prepopulation_status to
        // REQUESTED.
        PrepopulationStatus = UserListPrepopulationStatus.Requested,
        FlexibleRuleUserList = flexibleRuleUserListInfo
    };

    // Create the user list.
    UserList userList = new UserList
    {
        Name = $"All visitors to example.com #{ExampleUtilities.GetRandomString()}",
        Description = "Any visitor to any page of example.com",
        MembershipStatus = UserListMembershipStatus.Open,
        MembershipLifeSpan = 365L,
        RuleBasedUserList = ruleBasedUserListInfo
    };

    // Create the operation.
    UserListOperation userListOperation = new UserListOperation
    {
        Create = userList
    };

    // Add the user list, then print and return the new list's resource name.
    MutateUserListsResponse mutateUserListsResponse = userListServiceClient
        .MutateUserLists(customerId.ToString(), new[] { userListOperation });
    string userListResourceName = mutateUserListsResponse.Results.First().ResourceName;
    Console.WriteLine($"Created user list with resource name '{userListResourceName}'.");

    return userListResourceName;
}
      

PHP

private static function createUserList(
    GoogleAdsClient $googleAdsClient,
    int $customerId
): string {
    // Creates a rule targeting any user that visited a URL containing 'example.com'.
    $rule = new UserListRuleItemInfo([
        // Uses a built-in parameter to create a domain URL rule.
        'name' => 'url__',
        'string_rule_item' => new UserListStringRuleItemInfo([
            'operator' => UserListStringRuleItemOperator::CONTAINS,
            'value' => 'example.com'
        ])
    ]);

    // Specifies that the user list targets visitors of a page based on the provided rule.
    $flexibleRuleUserListInfo = new FlexibleRuleUserListInfo([
        'inclusive_rule_operator' => UserListFlexibleRuleOperator::PBAND,
        // Inclusive operands are joined together with the specified inclusive rule operator.
        'inclusive_operands' => [
            new FlexibleRuleOperandInfo([
                'rule' => new UserListRuleInfo([
                    'rule_item_groups' =>
                        [new UserListRuleItemGroupInfo(['rule_items' => [$rule]])]
                ]),
                // Optionally add a lookback window for this rule, in days.
                'lookback_window_days' => 7
            ])
        ],
        'exclusive_operands' => []
    ]);

    // Defines a representation of a user list that is generated by a rule.
    $ruleBasedUserListInfo = new RuleBasedUserListInfo([
        'flexible_rule_user_list' => $flexibleRuleUserListInfo,
        // Optional: To include past users in the user list, set the prepopulation_status to
        // REQUESTED.
        'prepopulation_status' => UserListPrepopulationStatus::REQUESTED
    ]);

    // Creates the user list.
    $userList = new UserList([
        'name' => "All visitors to example.com #" . Helper::getPrintableDatetime(),
        'description' => "Any visitor to any page of example.com",
        'membership_status' => UserListMembershipStatus::OPEN,
        'membership_life_span' => 365,
        'rule_based_user_list' => $ruleBasedUserListInfo
    ]);

    // Creates the operation.
    $operation = new UserListOperation();
    $operation->setCreate($userList);

    // Issues a mutate request to add a user list.
    $userListServiceClient = $googleAdsClient->getUserListServiceClient();
    /** @var MutateUserListsResponse $userListResponse */
    $userListResponse = $userListServiceClient->mutateUserLists(
        MutateUserListsRequest::build($customerId, [$operation])
    );

    $userListResourceName = $userListResponse->getResults()[0]->getResourceName();
    printf("Created user list with resource name '%s'.%s", $userListResourceName, PHP_EOL);

    return $userListResourceName;
}
      

Python

def create_user_list(client, customer_id):
    """Creates a user list targeting users that have visited a given URL.

    Args:
        client: an initialized GoogleAdsClient instance.
        customer_id: a str client customer ID used to create a user list.

    Returns:
        a str resource name for the newly created user list.
    """
    # Creates a UserListOperation.
    user_list_operation = client.get_type("UserListOperation")
    # Creates a UserList.
    user_list = user_list_operation.create
    user_list.name = f"All visitors to example.com #{uuid4()}"
    user_list.description = "Any visitor to any page of example.com"
    user_list.membership_status = client.enums.UserListMembershipStatusEnum.OPEN
    user_list.membership_life_span = 365
    # Optional: To include past users in the user list, set the
    # prepopulation_status to REQUESTED.
    user_list.rule_based_user_list.prepopulation_status = (
        client.enums.UserListPrepopulationStatusEnum.REQUESTED
    )
    # Specifies that the user list targets visitors of a page with a URL that
    # contains 'example.com'.
    user_list_rule_item_group_info = client.get_type(
        "UserListRuleItemGroupInfo"
    )
    user_list_rule_item_info = client.get_type("UserListRuleItemInfo")
    # Uses a built-in parameter to create a domain URL rule.
    user_list_rule_item_info.name = "url__"
    user_list_rule_item_info.string_rule_item.operator = (
        client.enums.UserListStringRuleItemOperatorEnum.CONTAINS
    )
    user_list_rule_item_info.string_rule_item.value = "example.com"
    user_list_rule_item_group_info.rule_items.append(user_list_rule_item_info)

    # Specify that the user list targets visitors of a page based on the
    # provided rule.
    flexible_rule_user_list_info = (
        user_list.rule_based_user_list.flexible_rule_user_list
    )
    flexible_rule_user_list_info.inclusive_rule_operator = (
        client.enums.UserListFlexibleRuleOperatorEnum.AND
    )
    # Inclusive operands are joined together with the specified
    # inclusive rule operator.
    rule_operand = client.get_type("FlexibleRuleOperandInfo")
    rule_operand.rule.rule_item_groups.extend([user_list_rule_item_group_info])
    rule_operand.lookback_window_days = 7
    flexible_rule_user_list_info.inclusive_operands.append(rule_operand)

    user_list_service = client.get_service("UserListService")
    response = user_list_service.mutate_user_lists(
        customer_id=customer_id, operations=[user_list_operation]
    )
    resource_name = response.results[0].resource_name
    print(f"Created user list with resource name: '{resource_name}'")
    return resource_name
      

Ruby

def create_user_list(client, customer_id)
  # Creates the user list operation.
  operation = client.operation.create_resource.user_list do |ul|
    ul.name = "All visitors to example.com ##{(Time.new.to_f * 1000).to_i}"
    ul.description = "Any visitor to any page of example.com"
    ul.membership_status = :OPEN
    ul.membership_life_span = 365
    # Defines a representation of a user list that is generated by a rule.
    ul.rule_based_user_list = client.resource.rule_based_user_list_info do |r|
      # To include past users in the user list, set the prepopulation_status
      # to REQUESTED.
      r.prepopulation_status = :REQUESTED
      # Specifies that the user list targets visitors of a page based on
      # the provided rule.
      r.flexible_rule_user_list = client.resource.flexible_rule_user_list_info do |frul|
        frul.inclusive_rule_operator = :AND
        frul.inclusive_operands << client.resource.flexible_rule_operand_info do |froi|
          froi.rule = client.resource.user_list_rule_info do |u|
            u.rule_item_groups << client.resource.user_list_rule_item_group_info do |group|
              group.rule_items << client.resource.user_list_rule_item_info do |item|
                # Uses a built-in parameter to create a domain URL rule.
                item.name = "url__"
                item.string_rule_item = client.resource.user_list_string_rule_item_info do |s|
                  s.operator = :CONTAINS
                  s.value = "example.com"
                end
              end
            end
          end
          # Optionally add a lookback window for this rule, in days.
          froi.lookback_window_days = 7
        end
      end
    end
  end

  # Issues a mutate request to add the user list.
  response = client.service.user_list.mutate_user_lists(
    customer_id: customer_id,
    operations: [operation],
  )
  user_list_resource_name = response.results.first.resource_name
  puts "Created user list with resource name '#{user_list_resource_name}'"

  user_list_resource_name
end
      

Perl

sub create_user_list {
  my ($api_client, $customer_id) = @_;

  # Create a rule targeting any user that visited a url containing 'example.com'.
  my $rule = Google::Ads::GoogleAds::V17::Common::UserListRuleItemInfo->new({
      # Use a built-in parameter to create a domain URL rule.
      name           => "url__",
      stringRuleItem =>
        Google::Ads::GoogleAds::V17::Common::UserListStringRuleItemInfo->new({
          operator => CONTAINS,
          value    => "example.com"
        })});

  # Specify that the user list targets visitors of a page based on the provided rule.
  my $user_list_rule_item_group_info =
    Google::Ads::GoogleAds::V17::Common::UserListRuleItemGroupInfo->new(
    {ruleItems => [$rule]});
  my $flexible_rule_user_list_info =
    Google::Ads::GoogleAds::V17::Common::FlexibleRuleUserListInfo->new({
      inclusiveRuleOperator => AND,
      # Inclusive operands are joined together with the specified inclusiveRuleOperator.
      inclusiveOperands => [
        Google::Ads::GoogleAds::V17::Common::FlexibleRuleOperandInfo->new({
            rule => Google::Ads::GoogleAds::V17::Common::UserListRuleInfo->new({
                ruleItemGroups => [$user_list_rule_item_group_info]}
            ),
            # Optionally add a lookback window for this rule, in days.
            lookbackWindowDays => 7
          })
      ],
      exclusiveOperands => []});

  # Define a representation of a user list that is generated by a rule.
  my $rule_based_user_list_info =
    Google::Ads::GoogleAds::V17::Common::RuleBasedUserListInfo->new({
      # Optional: To include past users in the user list, set the
      # prepopulationStatus to REQUESTED.
      prepopulationStatus  => REQUESTED,
      flexibleRuleUserList => $flexible_rule_user_list_info
    });

  # Create the user list.
  my $user_list = Google::Ads::GoogleAds::V17::Resources::UserList->new({
    name               => "All visitors to example.com #" . uniqid(),
    description        => "Any visitor to any page of example.com",
    membershipLifespan => 365,
    membershipStatus   => OPEN,
    ruleBasedUserList  => $rule_based_user_list_info
  });

  # Create the operation.
  my $user_list_operation =
    Google::Ads::GoogleAds::V17::Services::UserListService::UserListOperation->
    new({
      create => $user_list
    });

  # Add the user list, then print and return the new list's resource name.
  my $user_lists_response = $api_client->UserListService()->mutate({
      customerId => $customer_id,
      operations => [$user_list_operation]});

  my $user_list_resource_name =
    $user_lists_response->{results}[0]{resourceName};
  printf "Created user list with resource name '%s'.\n",
    $user_list_resource_name;

  return $user_list_resource_name;
}
      

检索列表

要检索您的用户列表,您可以向 user_list 资源。

SELECT
  user_list.name,
  user_list.membership_status,
  user_list.membership_life_span
FROM user_list
WHERE
  user_list.resource_name = 'USER_LIST_RESOURCE_NAME'

定位到列表

创建细分受众群后,下一步就是定位该细分受众群。

细分受众群定位规则

  1. 肯定(可出价)用户列表无法在广告系列一级设置,且 广告组一级。必须移除肯定用户列表条件 先从某个广告系列中的所有广告组获取一个 ID,然后才能为广告系列设置一个广告组。

  2. 只有搜索广告系列支持按用户列表进行肯定定位。对于 展示广告系列,CampaignCriterion 设置 user_list 的值必须为 已排除。

  3. 在搜索广告系列和购物广告系列中,用户名单定位条件不支持设置 以下字段:

将广告定位到您的用户列表

此流程与 API 中其他类型的定位条件类似。通过 以下代码演示了如何使用 AdGroupCriterion 将广告组中的广告定位到用户列表:

Java

private String targetAdsInAdGroupToUserList(
    GoogleAdsClient googleAdsClient, long customerId, long adGroupId, String userList) {
  // Creates the ad group criterion targeting members of the user list.
  AdGroupCriterion adGroupCriterion =
      AdGroupCriterion.newBuilder()
          .setAdGroup(ResourceNames.adGroup(customerId, adGroupId))
          .setUserList(UserListInfo.newBuilder().setUserList(userList).build())
          .build();

  // Creates the operation.
  AdGroupCriterionOperation operation =
      AdGroupCriterionOperation.newBuilder().setCreate(adGroupCriterion).build();

  // Creates the ad group criterion service.
  try (AdGroupCriterionServiceClient adGroupCriterionServiceClient =
      googleAdsClient.getLatestVersion().createAdGroupCriterionServiceClient()) {
    // Adds the ad group criterion.
    MutateAdGroupCriteriaResponse response =
        adGroupCriterionServiceClient.mutateAdGroupCriteria(
            Long.toString(customerId), ImmutableList.of(operation));
    // Gets and prints the results.
    String adGroupCriterionResourceName = response.getResults(0).getResourceName();
    System.out.printf(
        "Successfully created ad group criterion with resource name '%s' "
            + "targeting user list with resource name '%s' with ad group with ID %d.%n",
        adGroupCriterionResourceName, userList, adGroupId);
    return adGroupCriterionResourceName;
  }
}

      

C#

private string TargetAdsInAdGroupToUserList(
    GoogleAdsClient client, long customerId, long adGroupId, string userListResourceName)
{
    // Get the AdGroupCriterionService client.
    AdGroupCriterionServiceClient adGroupCriterionServiceClient = client.GetService
        (Services.V17.AdGroupCriterionService);

    // Create the ad group criterion targeting members of the user list.
    AdGroupCriterion adGroupCriterion = new AdGroupCriterion
    {
        AdGroup = ResourceNames.AdGroup(customerId, adGroupId),
        UserList = new UserListInfo
        {
            UserList = userListResourceName
        }
    };

    // Create the operation.
    AdGroupCriterionOperation adGroupCriterionOperation = new AdGroupCriterionOperation
    {
        Create = adGroupCriterion
    };

    // Add the ad group criterion, then print and return the new criterion's resource name.
    MutateAdGroupCriteriaResponse mutateAdGroupCriteriaResponse =
        adGroupCriterionServiceClient.MutateAdGroupCriteria(customerId.ToString(),
            new[] { adGroupCriterionOperation });

    string adGroupCriterionResourceName =
        mutateAdGroupCriteriaResponse.Results.First().ResourceName;
    Console.WriteLine("Successfully created ad group criterion with resource name " +
        $"'{adGroupCriterionResourceName}' targeting user list with resource name " +
        $"'{userListResourceName}' with ad group with ID {adGroupId}.");
    return adGroupCriterionResourceName;
}
      

PHP

private static function targetAdsInAdGroupToUserList(
    GoogleAdsClient $googleAdsClient,
    int $customerId,
    int $adGroupId,
    string $userListResourceName
): string {
    // Creates the ad group criterion targeting members of the user list.
    $adGroupCriterion = new AdGroupCriterion([
        'ad_group' => ResourceNames::forAdGroup($customerId, $adGroupId),
        'user_list' => new UserListInfo(['user_list' => $userListResourceName])
    ]);

    // Creates the operation.
    $operation = new AdGroupCriterionOperation();
    $operation->setCreate($adGroupCriterion);

    // Issues a mutate request to add an ad group criterion.
    $adGroupCriterionServiceClient = $googleAdsClient->getAdGroupCriterionServiceClient();
    /** @var MutateAdGroupCriteriaResponse $adGroupCriterionResponse */
    $adGroupCriterionResponse = $adGroupCriterionServiceClient->mutateAdGroupCriteria(
        MutateAdGroupCriteriaRequest::build($customerId, [$operation])
    );

    $adGroupCriterionResourceName =
        $adGroupCriterionResponse->getResults()[0]->getResourceName();
    printf(
        "Successfully created ad group criterion with resource name '%s' " .
        "targeting user list with resource name '%s' with ad group with ID %d.%s",
        $adGroupCriterionResourceName,
        $userListResourceName,
        $adGroupId,
        PHP_EOL
    );

    return $adGroupCriterionResourceName;
}
      

Python

def target_ads_in_ad_group_to_user_list(
    client, customer_id, ad_group_id, user_list_resource_name
):
    """Creates an ad group criterion that targets a user list with an ad group.

    Args:
        client: an initialized GoogleAdsClient instance.
        customer_id: a str client customer ID used to create an ad group
            criterion.
        ad_group_id: a str ID for an ad group used to create an ad group
            criterion that targets members of a user list.
        user_list_resource_name: a str resource name for a user list.

    Returns:
        a str resource name for an ad group criterion.
    """
    ad_group_criterion_operation = client.get_type("AdGroupCriterionOperation")
    # Creates the ad group criterion targeting members of the user list.
    ad_group_criterion = ad_group_criterion_operation.create
    ad_group_criterion.ad_group = client.get_service(
        "AdGroupService"
    ).ad_group_path(customer_id, ad_group_id)
    ad_group_criterion.user_list.user_list = user_list_resource_name

    ad_group_criterion_service = client.get_service("AdGroupCriterionService")
    response = ad_group_criterion_service.mutate_ad_group_criteria(
        customer_id=customer_id, operations=[ad_group_criterion_operation]
    )
    resource_name = response.results[0].resource_name
    print(
        "Successfully created ad group criterion with resource name: "
        f"'{resource_name}' targeting user list with resource name: "
        f"'{user_list_resource_name}' and with ad group with ID "
        f"{ad_group_id}."
    )
    return resource_name
      

Ruby

def target_ads_in_ad_group_to_user_list(
  client,
  customer_id,
  ad_group_id,
  user_list
)
  # Creates the ad group criterion targeting members of the user list.
  operation = client.operation.create_resource.ad_group_criterion do |agc|
    agc.ad_group = client.path.ad_group(customer_id, ad_group_id)
    agc.user_list = client.resource.user_list_info do |info|
      info.user_list = user_list
    end
  end

  # Issues a mutate request to create the ad group criterion.
  response = client.service.ad_group_criterion.mutate_ad_group_criteria(
    customer_id: customer_id,
    operations: [operation],
  )
  ad_group_criterion_resource_name = response.results.first.resource_name
  puts "Successfully created ad group criterion with resource name " \
    "'#{ad_group_criterion_resource_name}' targeting user list with resource name " \
    "'#{user_list}' with ad group with ID #{ad_group_id}"

  ad_group_criterion_resource_name
end
      

Perl

sub target_ads_in_ad_group_to_user_list {
  my ($api_client, $customer_id, $ad_group_id, $user_list_resource_name) = @_;

  # Create the ad group criterion targeting members of the user list.
  my $ad_group_criterion =
    Google::Ads::GoogleAds::V17::Resources::AdGroupCriterion->new({
      adGroup => Google::Ads::GoogleAds::V17::Utils::ResourceNames::ad_group(
        $customer_id, $ad_group_id
      ),
      userList => Google::Ads::GoogleAds::V17::Common::UserListInfo->new({
          userList => $user_list_resource_name
        })});

  # Create the operation.
  my $ad_group_criterion_operation =
    Google::Ads::GoogleAds::V17::Services::AdGroupCriterionService::AdGroupCriterionOperation
    ->new({
      create => $ad_group_criterion
    });

  # Add the ad group criterion, then print and return the new criterion's resource name.
  my $ad_group_criteria_response =
    $api_client->AdGroupCriterionService()->mutate({
      customerId => $customer_id,
      operations => [$ad_group_criterion_operation]});

  my $ad_group_criterion_resource_name =
    $ad_group_criteria_response->{results}[0]{resourceName};
  printf "Successfully created ad group criterion with resource name '%s' " .
    "targeting user list with resource name '%s' with ad group with ID %d.\n",
    $ad_group_criterion_resource_name, $user_list_resource_name, $ad_group_id;

  return $ad_group_criterion_resource_name;
}
      

与其他类型的条件一样,您可以为 AdGroupCriterion 对象,例如出价覆盖。

切换定位级别

如果您要将广告组一级的用户列表条件切换为广告系列一级 您必须先从每个已启用或 已暂停的广告组。点击可展开的元素即可查看 示例代码

首先,获取指定广告系列下的所有 AdGroupCriteria。

Java

private List<String> getUserListAdGroupCriterion(
    GoogleAdsClient googleAdsClient, long customerId, long campaignId) {
  List<String> userListCriteria = new ArrayList<>();
  // Creates the Google Ads service client.
  try (GoogleAdsServiceClient googleAdsServiceClient =
      googleAdsClient.getLatestVersion().createGoogleAdsServiceClient()) {
    // Creates a request that will retrieve all of the ad group criteria under a campaign.
    SearchGoogleAdsRequest request =
        SearchGoogleAdsRequest.newBuilder()
            .setCustomerId(Long.toString(customerId))
            .setQuery(
                "SELECT ad_group_criterion.criterion_id"
                    + " FROM ad_group_criterion"
                    + " WHERE campaign.id = "
                    + campaignId
                    + " AND ad_group_criterion.type = 'USER_LIST'")
            .build();
    // Issues the search request.
    SearchPagedResponse searchPagedResponse = googleAdsServiceClient.search(request);
    // Iterates over all rows in all pages. Prints the results and adds the ad group criteria
    // resource names to the list.
    for (GoogleAdsRow googleAdsRow : searchPagedResponse.iterateAll()) {
      String adGroupCriterionResourceName = googleAdsRow.getAdGroupCriterion().getResourceName();
      System.out.printf(
          "Ad group criterion with resource name '%s' was found.%n",
          adGroupCriterionResourceName);
      userListCriteria.add(adGroupCriterionResourceName);
    }
  }
  return userListCriteria;
}

      

C#

private List<string> GetUserListAdGroupCriteria(
    GoogleAdsClient client, long customerId, long campaignId)
{
    // Get the GoogleAdsService client.
    GoogleAdsServiceClient googleAdsServiceClient =
        client.GetService(Services.V17.GoogleAdsService);

    List<string> userListCriteriaResourceNames = new List<string>();

    // Create a query that will retrieve all of the ad group criteria under a campaign.
    string query = $@"
        SELECT ad_group_criterion.criterion_id
        FROM ad_group_criterion
        WHERE
          campaign.id = {campaignId}
          AND ad_group_criterion.type = 'USER_LIST'";

    // Issue the search request.
    googleAdsServiceClient.SearchStream(customerId.ToString(), query,
        delegate (SearchGoogleAdsStreamResponse resp)
        {
            // Display the results and add the resource names to the list.
            foreach (GoogleAdsRow googleAdsRow in resp.Results)
            {
                string adGroupCriterionResourceName =
                    googleAdsRow.AdGroupCriterion.ResourceName;
                Console.WriteLine("Ad group criterion with resource name " +
                    $"{adGroupCriterionResourceName} was found.");
                userListCriteriaResourceNames.Add(adGroupCriterionResourceName);
            }
        });

    return userListCriteriaResourceNames;
}
      

PHP

private static function getUserListAdGroupCriteria(
    GoogleAdsClient $googleAdsClient,
    int $customerId,
    int $campaignId
): array {
    // Creates a query that retrieves all of the ad group criteria under a campaign.
    $query = sprintf(
        "SELECT ad_group_criterion.criterion_id " .
        "FROM ad_group_criterion " .
        "WHERE campaign.id = %d " .
        "AND ad_group_criterion.type = 'USER_LIST'",
        $campaignId
    );

    // Creates the Google Ads service client.
    $googleAdsServiceClient = $googleAdsClient->getGoogleAdsServiceClient();

    // Issues the search request.
    $response =
        $googleAdsServiceClient->search(SearchGoogleAdsRequest::build($customerId, $query));

    $userListCriteria = [];
    // Iterates over all rows in all pages. Prints the user list criteria and adds the ad group
    // criteria resource names to the list.
    foreach ($response->iterateAllElements() as $googleAdsRow) {
        /** @var GoogleAdsRow $googleAdsRow */
        $adGroupCriterionResourceName = $googleAdsRow->getAdGroupCriterion()->getResourceName();

        printf(
            "Ad group criterion with resource name '%s' was found.%s",
            $adGroupCriterionResourceName,
            PHP_EOL
        );

        $userListCriteria[] = $adGroupCriterionResourceName;
    }

    return $userListCriteria;
}
      

Python

def get_user_list_ad_group_criteria(client, customer_id, campaign_id):
    """Finds all of user list ad group criteria under a campaign.

    Args:
        client: an initialized GoogleAdsClient instance.
        customer_id: a str client customer ID.
        campaign_id: a str campaign ID.

    Returns:
        a list of ad group criterion resource names.
    """
    # Creates a query that retrieves all of the ad group criteria under a
    # campaign.
    query = f"""
        SELECT
          ad_group_criterion.criterion_id
        FROM ad_group_criterion
        WHERE campaign.id = {campaign_id}
        AND ad_group_criterion.type = USER_LIST"""

    googleads_service = client.get_service("GoogleAdsService")
    search_request = client.get_type("SearchGoogleAdsRequest")
    search_request.customer_id = customer_id
    search_request.query = query
    response = googleads_service.search(request=search_request)

    # Iterates over all rows in all pages. Prints the user list criteria and
    # adds the ad group criteria resource names to the list.
    user_list_criteria = []
    for row in response:
        resource_name = row.ad_group_criterion.resource_name
        print(
            "Ad group criterion with resource name '{resource_name}' was "
            "found."
        )
        user_list_criteria.append(resource_name)

    return user_list_criteria
      

Ruby

def get_user_list_ad_group_criterion(
  client,
  customer_id,
  campaign_id
)
  user_list_criteria = []

  # Creates a query that will retrieve all of the ad group criteria 
  # under a campaign.
  query = <<~QUERY
    SELECT ad_group_criterion.criterion_id
    FROM ad_group_criterion
    WHERE campaign.id = #{campaign_id}
    AND ad_group_criterion.type = 'USER_LIST'
  QUERY

  # Issues the search request.
  response = client.service.google_ads.search(
    customer_id: customer_id,
    query: query,
    page_size: PAGE_SIZE,
  )

  # Iterates over all rows in all pages. Prints the results and adds the ad
  # group criteria resource names to the list.
  response.each do |row|
    ad_group_criterion_resource_name = row.ad_group_criterion.resource_name
    puts "Ad group criterion with resource name " \
      "'#{ad_group_criterion_resource_name}' was found"
    user_list_criteria << ad_group_criterion_resource_name
  end

  user_list_criteria
end
      

Perl

sub get_user_list_ad_group_criteria {
  my ($api_client, $customer_id, $campaign_id) = @_;

  my $user_list_criterion_resource_names = [];

  # Create a search stream request that will retrieve all of the user list ad
  # group criteria under a campaign.
  my $search_stream_request =
    Google::Ads::GoogleAds::V17::Services::GoogleAdsService::SearchGoogleAdsStreamRequest
    ->new({
      customerId => $customer_id,
      query      => sprintf(
        "SELECT ad_group_criterion.criterion_id " .
          "FROM ad_group_criterion " .
          "WHERE campaign.id = %d AND ad_group_criterion.type = 'USER_LIST'",
        $campaign_id
      )});

  my $search_stream_handler =
    Google::Ads::GoogleAds::Utils::SearchStreamHandler->new({
      service => $api_client->GoogleAdsService(),
      request => $search_stream_request
    });

  # Issue a search request and process the stream response.
  $search_stream_handler->process_contents(
    sub {
      # Display the results and add the resource names to the list.
      my $google_ads_row = shift;

      my $ad_group_criterion_resource_name =
        $google_ads_row->{adGroupCriterion}{resourceName};
      printf "Ad group criterion with resource name '%s' was found.\n",
        $ad_group_criterion_resource_name;
      push(@$user_list_criterion_resource_names,
        $ad_group_criterion_resource_name);
    });

  return $user_list_criterion_resource_names;
}
      

然后,移除返回的所有广告组条件定位条件。

Java

private void removeExistingListCriteriaFromAdGroup(
    GoogleAdsClient googleAdsClient, long customerId, long campaignId) {
  // Retrieves all of the ad group criteria under a campaign.
  List<String> adGroupCriteria =
      getUserListAdGroupCriterion(googleAdsClient, customerId, campaignId);

  List<AdGroupCriterionOperation> operations = new ArrayList<>();

  // Creates a list of remove operations.
  for (String adGroupCriterion : adGroupCriteria) {
    operations.add(AdGroupCriterionOperation.newBuilder().setRemove(adGroupCriterion).build());
  }

  // Creates the ad group criterion service.
  try (AdGroupCriterionServiceClient adGroupCriterionServiceClient =
      googleAdsClient.getLatestVersion().createAdGroupCriterionServiceClient()) {
    // Removes the ad group criterion.
    MutateAdGroupCriteriaResponse response =
        adGroupCriterionServiceClient.mutateAdGroupCriteria(
            Long.toString(customerId), operations);
    // Gets and prints the results.
    System.out.printf("Removed %d ad group criteria.%n", response.getResultsCount());
    for (MutateAdGroupCriterionResult result : response.getResultsList()) {
      System.out.printf(
          "Successfully removed ad group criterion with resource name '%s'.%n",
          result.getResourceName());
    }
  }
}

      

C#

private void RemoveExistingListCriteriaFromAdGroup(GoogleAdsClient client, long customerId,
    long campaignId)
{
    // Get the AdGroupCriterionService client.
    AdGroupCriterionServiceClient adGroupCriterionServiceClient =
        client.GetService(Services.V17.AdGroupCriterionService);

    // Retrieve all of the ad group criteria under a campaign.
    List<string> adGroupCriteria =
        GetUserListAdGroupCriteria(client, customerId, campaignId);

    // Create a list of remove operations.
    List<AdGroupCriterionOperation> operations = adGroupCriteria.Select(adGroupCriterion =>
        new AdGroupCriterionOperation { Remove = adGroupCriterion }).ToList();

    // Remove the ad group criteria and print the resource names of the removed criteria.
    MutateAdGroupCriteriaResponse mutateAdGroupCriteriaResponse =
        adGroupCriterionServiceClient.MutateAdGroupCriteria(customerId.ToString(),
            operations);

    Console.WriteLine($"Removed {mutateAdGroupCriteriaResponse.Results.Count} ad group " +
        "criteria.");
    foreach (MutateAdGroupCriterionResult result in mutateAdGroupCriteriaResponse.Results)
    {
        Console.WriteLine("Successfully removed ad group criterion with resource name " +
            $"'{result.ResourceName}'.");
    }
}
      

PHP

private static function removeExistingListCriteriaFromAdGroup(
    GoogleAdsClient $googleAdsClient,
    int $customerId,
    int $campaignId
) {
    // Retrieves all of the ad group criteria under a campaign.
    $allAdGroupCriteria = self::getUserListAdGroupCriteria(
        $googleAdsClient,
        $customerId,
        $campaignId
    );

    $removeOperations = [];
    // Creates a list of remove operations.
    foreach ($allAdGroupCriteria as $adGroupCriterionResourceName) {
        $operation = new AdGroupCriterionOperation();
        $operation->setRemove($adGroupCriterionResourceName);
        $removeOperations[] = $operation;
    }

    // Issues a mutate request to remove the ad group criteria.
    $adGroupCriterionServiceClient = $googleAdsClient->getAdGroupCriterionServiceClient();
    /** @var MutateAdGroupCriteriaResponse $adGroupCriteriaResponse */
    $adGroupCriteriaResponse = $adGroupCriterionServiceClient->mutateAdGroupCriteria(
        MutateAdGroupCriteriaRequest::build($customerId, $removeOperations)
    );

    foreach ($adGroupCriteriaResponse->getResults() as $adGroupCriteriaResult) {
        printf(
            "Successfully removed ad group criterion with resource name '%s'.%s",
            $adGroupCriteriaResult->getResourceName(),
            PHP_EOL
        );
    }
}
      

Python

def remove_existing_criteria_from_ad_group(client, customer_id, campaign_id):
    """Removes all ad group criteria targeting a user list under a campaign.

    This is a necessary step before targeting a user list at the campaign level.

    Args:
        client: an initialized GoogleAdsClient instance.
        customer_id: a str client customer ID.
        campaign_id: a str ID for a campaign that will have all ad group
            criteria that targets user lists removed.
    """
    # Retrieves all of the ad group criteria under a campaign.
    all_ad_group_criteria = get_user_list_ad_group_criteria(
        client, customer_id, campaign_id
    )

    # Creates a list of remove operations.
    remove_operations = []
    for ad_group_criterion_resource_name in all_ad_group_criteria:
        remove_operation = client.get_type("AdGroupCriterionOperation")
        remove_operation.remove = ad_group_criterion_resource_name
        remove_operations.append(remove_operation)

    ad_group_criterion_service = client.get_service("AdGroupCriterionService")
    response = ad_group_criterion_service.mutate_ad_group_criteria(
        customer_id=customer_id, operations=remove_operations
    )
    print(
        "Successfully removed ad group criterion with resource name: "
        f"'{response.results[0].resource_name}'"
    )
      

Ruby

def remove_existing_list_criteria_from_ad_group(
  client,
  customer_id,
  campaign_id
)
  # Retrieves all of the ad group criteria under a campaign.
  ad_group_criteria = get_user_list_ad_group_criterion(
    client, customer_id, campaign_id)

  # Creates a list of remove operations.
  operations = []
  ad_group_criteria.each do |agc|
    operations << client.operation.remove_resource.ad_group_criterion(agc)
  end

  # Issues a mutate request to remove all ad group criteria.
  response = client.service.ad_group_criterion.mutate_ad_group_criteria(
    customer_id: customer_id,
    operations: operations,
  )
  puts "Removed #{response.results.size} ad group criteria."
  response.results.each do |result|
    puts "Successfully removed ad group criterion with resource name " \
      "'#{result.resource_name}'"
  end
end
      

Perl

sub remove_existing_list_criteria_from_ad_group {
  my ($api_client, $customer_id, $campaign_id) = @_;

  # Retrieve all of the ad group criteria under a campaign.
  my $ad_group_criteria =
    get_user_list_ad_group_criteria($api_client, $customer_id, $campaign_id);

  # Create a list of remove operations.
  my $operations = [];
  foreach my $ad_group_criterion (@$ad_group_criteria) {
    push(
      @$operations,
      Google::Ads::GoogleAds::V17::Services::AdGroupCriterionService::AdGroupCriterionOperation
        ->new({
          remove => $ad_group_criterion
        }));
  }

  # Remove the ad group criteria and print the resource names of the removed criteria.
  my $ad_group_criteria_response =
    $api_client->AdGroupCriterionService()->mutate({
      customerId => $customer_id,
      operations => $operations
    });

  printf "Removed %d ad group criteria.\n",
    scalar @{$ad_group_criteria_response->{results}};
  foreach my $result (@{$ad_group_criteria_response->{results}}) {
    printf "Successfully removed ad group criterion with resource name '%s'.\n",
      $result->{resourceName};
  }
}
      

切换时,还必须移除现有的广告系列级用户名单条件 广告组一级的用户列表,相应过程与前面的示例相同。

使用 CampaignCriterion,将广告系列中的广告定位到某个用户列表。

Java

private String targetAdsInCampaignToUserList(
    GoogleAdsClient googleAdsClient, long customerId, long campaignId, String userList) {
  // Creates the campaign criterion.
  CampaignCriterion campaignCriterion =
      CampaignCriterion.newBuilder()
          .setCampaign(ResourceNames.campaign(customerId, campaignId))
          .setUserList(UserListInfo.newBuilder().setUserList(userList).build())
          .build();

  // Creates the operation.
  CampaignCriterionOperation operation =
      CampaignCriterionOperation.newBuilder().setCreate(campaignCriterion).build();

  // Creates the campaign criterion service client.
  try (CampaignCriterionServiceClient campaignCriterionServiceClient =
      googleAdsClient.getLatestVersion().createCampaignCriterionServiceClient()) {
    // Adds the campaign criterion.
    MutateCampaignCriteriaResponse response =
        campaignCriterionServiceClient.mutateCampaignCriteria(
            Long.toString(customerId), ImmutableList.of(operation));
    // Gets and prints the campaign criterion resource name.
    String campaignCriterionResourceName = response.getResults(0).getResourceName();
    System.out.printf(
        "Successfully created campaign criterion with resource name '%s' "
            + "targeting user list with resource name '%s' with campaign with ID %d.%n",
        campaignCriterionResourceName, userList, campaignId);
    return campaignCriterionResourceName;
  }
}

      

C#

private string TargetAdsInCampaignToUserList(
    GoogleAdsClient client, long customerId, long campaignId, string userListResourceName)
{
    // Get the CampaignCriterionService client.
    CampaignCriterionServiceClient campaignCriterionServiceClient =
        client.GetService(Services.V17.CampaignCriterionService);

    // Create the campaign criterion.
    CampaignCriterion campaignCriterion = new CampaignCriterion
    {
        Campaign = ResourceNames.Campaign(customerId, campaignId),
        UserList = new UserListInfo
        {
            UserList = userListResourceName
        }
    };

    // Create the operation.
    CampaignCriterionOperation campaignCriterionOperation = new CampaignCriterionOperation
    {
        Create = campaignCriterion
    };

    // Add the campaign criterion and print the resulting criterion's resource name.
    MutateCampaignCriteriaResponse mutateCampaignCriteriaResponse =
        campaignCriterionServiceClient.MutateCampaignCriteria(customerId.ToString(),
            new[] { campaignCriterionOperation });

    string campaignCriterionResourceName =
        mutateCampaignCriteriaResponse.Results.First().ResourceName;
    Console.WriteLine("Successfully created campaign criterion with resource name " +
        $"'{campaignCriterionResourceName}' targeting user list with resource name " +
        $"'{userListResourceName}' with campaign with ID {campaignId}.");

    return campaignCriterionResourceName;
}
      

PHP

private static function targetAdsInCampaignToUserList(
    GoogleAdsClient $googleAdsClient,
    int $customerId,
    int $campaignId,
    string $userListResourceName
): string {
    // Creates the campaign criterion.
    $campaignCriterion = new CampaignCriterion([
        'campaign' => ResourceNames::forCampaign($customerId, $campaignId),
        'user_list' => new UserListInfo(['user_list' => $userListResourceName])
    ]);

    // Creates the operation.
    $operation = new CampaignCriterionOperation();
    $operation->setCreate($campaignCriterion);

    // Issues a mutate request to create a campaign criterion.
    $campaignCriterionServiceClient = $googleAdsClient->getCampaignCriterionServiceClient();
    /** @var MutateCampaignCriteriaResponse $campaignCriteriaResponse */
    $campaignCriteriaResponse = $campaignCriterionServiceClient->mutateCampaignCriteria(
        MutateCampaignCriteriaRequest::build($customerId, [$operation])
    );

    $campaignCriterionResourceName =
        $campaignCriteriaResponse->getResults()[0]->getResourceName();
    printf(
        "Successfully created campaign criterion with resource name '%s' " .
        "targeting user list with resource name '%s' with campaign with ID %d.%s",
        $campaignCriterionResourceName,
        $userListResourceName,
        $campaignId,
        PHP_EOL
    );

    return $campaignCriterionResourceName;
}
      

Python

def target_ads_in_campaign_to_user_list(
    client, customer_id, campaign_id, user_list_resource_name
):
    """Creates a campaign criterion that targets a user list with a campaign.

    Args:
        client: an initialized GoogleAdsClient instance.
        customer_id: a str client customer ID used to create an campaign
            criterion.
        campaign_id: a str ID for a campaign used to create a campaign
            criterion that targets members of a user list.
        user_list_resource_name: a str resource name for a user list.

    Returns:
        a str resource name for a campaign criterion.
    """
    campaign_criterion_operation = client.get_type("CampaignCriterionOperation")
    campaign_criterion = campaign_criterion_operation.create
    campaign_criterion.campaign = client.get_service(
        "CampaignService"
    ).campaign_path(customer_id, campaign_id)
    campaign_criterion.user_list.user_list = user_list_resource_name

    campaign_criterion_service = client.get_service("CampaignCriterionService")
    response = campaign_criterion_service.mutate_campaign_criteria(
        customer_id=customer_id, operations=[campaign_criterion_operation]
    )
    resource_name = response.results[0].resource_name
    print(
        "Successfully created campaign criterion with resource name "
        f"'{resource_name}' targeting user list with resource name "
        f"'{user_list_resource_name}' with campaign with ID {campaign_id}"
    )
    return resource_name
      

Ruby

def target_ads_in_campaign_to_user_list(
  client,
  customer_id,
  campaign_id,
  user_list
)
  # Creates the campaign criterion targeting members of the user list.
  operation = client.operation.create_resource.campaign_criterion do |cc|
    cc.campaign = client.path.campaign(customer_id, campaign_id)
    cc.user_list = client.resource.user_list_info do |info|
      info.user_list = user_list
    end
  end

  # Issues a mutate request to create the campaign criterion.
  response = client.service.campaign_criterion.mutate_campaign_criteria(
    customer_id: customer_id,
    operations: [operation],
  )
  campaign_criterion_resource_name = response.results.first.resource_name
  puts "Successfully created campaign criterion with resource name " \
    "'#{campaign_criterion_resource_name}' targeting user list with resource name " \
    "'#{user_list}' with campaign with ID #{campaign_id}"

  campaign_criterion_resource_name
end
      

Perl

sub target_ads_in_campaign_to_user_list {
  my ($api_client, $customer_id, $campaign_id, $user_list_resource_name) = @_;

  # Create the campaign criterion.
  my $campaign_criterion =
    Google::Ads::GoogleAds::V17::Resources::CampaignCriterion->new({
      campaign => Google::Ads::GoogleAds::V17::Utils::ResourceNames::campaign(
        $customer_id, $campaign_id
      ),
      userList => Google::Ads::GoogleAds::V17::Common::UserListInfo->new({
          userList => $user_list_resource_name
        })});

  # Create the operation.
  my $campaign_criterion_operation =
    Google::Ads::GoogleAds::V17::Services::CampaignCriterionService::CampaignCriterionOperation
    ->new({
      create => $campaign_criterion
    });

  # Add the campaign criterion and print the resulting criterion's resource name.
  my $campaign_criteria_response =
    $api_client->CampaignCriterionService()->mutate({
      customerId => $customer_id,
      operations => [$campaign_criterion_operation]});

  my $campaign_criterion_resource_name =
    $campaign_criteria_response->{results}[0]{resourceName};
  printf "Successfully created campaign criterion with resource name '%s' " .
    "targeting user list with resource name '%s' with campaign with ID %d.\n",
    $campaign_criterion_resource_name, $user_list_resource_name, $campaign_id;

  return $campaign_criterion_resource_name;
}
      

查看列表效果

要收集细分受众群的效果数据,请发出一次搜索 针对 ad_group_audience_viewcampaign_audience_view 资源。 例如,您可能会查看 conversionscost_per_conversion, 确定定位细分受众群是否真的带来了更多 转化次数,然后相应地调整您的出价调节系数。

SELECT
  ad_group_criterion.criterion_id,
  metrics.conversions,
  metrics.cost_per_conversion
FROM ad_group_audience_view