採取特定動作的訪客

您可以根據使用者在網站上採取的特定動作，填入目標對象名單。如果您使用轉換追蹤功能，可以將廣告指定給先前在您網站上觸發轉換 (例如購買) 的使用者。

您也可以將廣告放送對象鎖定為在網站上執行特定動作，但您不認為是轉換的使用者，例如使用者將商品加入購物車，但隨後刪除，且未完成購買。

必要條件

如要建立及指定目標對象區隔，請先完成下列步驟：

  1. 請參閱按照興趣和地區顯示廣告的相關政策。不得使用使用者的私密資訊建立目標對象。

  2. 設定 Google 代碼。

    如要根據行動應用程式行為建立使用者名單，廣告主應導入 Firebase SDK 或使用第三方 SDK 追蹤應用程式內行為。

1. 設定轉換追蹤。按照轉換管理入門指南的指示操作。然後在網站上安插 Google 代碼。

擷取 Google 代碼

所有 Google Ads 帳戶都只有一個帳戶層級的 Google 代碼，會在開啟帳戶時自動建立。

如要透過 Google Ads 使用者介面擷取 Google 代碼，請按照Google 代碼 ID 的指示操作。如要透過 Google Ads API 擷取 Google 代碼，請建立 RemarketingAction，然後使用 remarketing_action 資源發出 GoogleAdsService.SearchStream 要求，藉此擷取 Google 代碼：

SELECT
  remarketing_action.id,
  remarketing_action.name,
  remarketing_action.tag_snippets
FROM remarketing_action
WHERE
  remarketing_action.resource_name =
    'customers/CUSTOMER_ID/remarketingActions/REMARKETING_ACTION_ID'

在網站或應用程式中加入 Google 代碼

下一步是在網站的所有網頁上安裝 Google 代碼。詳情請參閱將 Google 代碼加進網站或行動應用程式。

如果您只打算根據造訪的網頁網址建立目標對象區隔，則不需要編輯 Google 代碼。如果您使用自訂參數，則需要編輯代碼來加入這些參數，詳情請參閱「代碼設定和建立再行銷名單的進階策略」。

您可以使用 Google Tag Assistant 驗證代碼安裝情形。

內建 Google 代碼參數

您可以使用內建再行銷參數 url__，根據使用者在您網站上造訪的網址，指定使用者名單，如「網站訪客」範例所示。

自訂 Google 代碼參數

您可以在 Google 代碼中加入自訂 Google 代碼參數，建立更精細的使用者名單。

建立自訂參數前，請先查看預先定義的參數清單，確認是否有適合您用途的參數。使用預先定義的參數，可更輕鬆地與其他 Google Ads 再行銷功能整合。

建立使用者清單

如要指定採取特定動作的訪客，請使用包含您指定動作 (轉換或非轉換動作) 參照的 BasicUserListInfo 物件，設定 UserList 的 basic_user_list 欄位。

如要完整瞭解以轉換和非轉換動作組合為依據，指定使用者的範例情境，請參閱範例情境。

觸發轉換的訪客

基本使用者名單會將在您網站上觸發一或多個轉換動作的使用者定義為成員。建立基本使用者名單時，您會將 ConversionAction 的資源名稱提供給 UserListActionInfo 物件，該物件會傳遞至 UserList。

以下範例會建立與兩個現有轉換動作相關聯的基本使用者名單：

Java

private void runExample(
    GoogleAdsClient googleAdsClient, long customerId, List<Long> conversionActionIds) {
  List<UserListActionInfo> userListActionInfoList = new ArrayList<>();
  for (long conversionActionId : conversionActionIds) {
    // Creates the UserListActionInfo object for a given conversion action. This specifies the
    // conversion action that, when triggered, will cause a user to be added to a UserList.
    UserListActionInfo userListActionInfo =
        UserListActionInfo.newBuilder()
            .setConversionAction(ResourceNames.conversionAction(customerId, conversionActionId))
            .build();
    userListActionInfoList.add(userListActionInfo);
  }

  // Creates a basic user list info object with all of the conversion actions.
  BasicUserListInfo basicUserListInfo =
      BasicUserListInfo.newBuilder().addAllActions(userListActionInfoList).build();

  // Creates the basic user list.
  UserList basicUserList =
      UserList.newBuilder()
          .setName("Example BasicUserList #" + getPrintableDateTime())
          .setDescription("A list of people who have triggered one or more conversion actions")
          .setMembershipLifeSpan(365)
          .setBasicUserList(basicUserListInfo)
          .setMembershipStatus(UserListMembershipStatus.OPEN)
          .build();

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

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

C#

public void Run(GoogleAdsClient client, long customerId, long[] conversionActionIds)
{
    // Creates the service client.
    UserListServiceClient userListServiceClient =
        client.GetService(Services.V25.UserListService);

    List<UserListActionInfo> userListActionInfoList = new List<UserListActionInfo>();
    foreach (long conversionActionId in conversionActionIds)
    {
        // Creates the UserListActionInfo object for a given conversion action. This
        // specifies the conversion action that, when triggered, will cause a user to be
        // added to a UserList.
        userListActionInfoList.Add(new UserListActionInfo
        {
            ConversionAction =
                ResourceNames.ConversionAction(customerId, conversionActionId)
        });
    }

    // Creates a basic user list info object with all of the conversion actions.
    BasicUserListInfo basicUserListInfo = new BasicUserListInfo();
    basicUserListInfo.Actions.Add(userListActionInfoList);

    // Creates the basic user list.
    UserList basicUserList = new UserList
    {
        Name = $"Example BasicUserList #{ExampleUtilities.GetShortRandomString()}",
        Description = "A list of people who have triggered one or more conversion actions",
        MembershipLifeSpan = 365L,
        BasicUserList = basicUserListInfo,
        MembershipStatus = UserListMembershipStatus.Open
    };

    // Creates the operation.
    UserListOperation operation = new UserListOperation
    {
        Create = basicUserList
    };

    try
    {
        // Adds the new user list.
        MutateUserListsResponse response = userListServiceClient.MutateUserLists
            (customerId.ToString(), new[] { operation });

        // Prints the result.
        Console.WriteLine("Created basic user list with resource name: " +
            $"{response.Results.First().ResourceName}");
    }
    catch (GoogleAdsException e)
    {
        Console.WriteLine("Failure:");
        Console.WriteLine($"Message: {e.Message}");
        Console.WriteLine($"Failure: {e.Failure}");
        Console.WriteLine($"Request ID: {e.RequestId}");
        throw;
    }
}

PHP

public static function runExample(
    GoogleAdsClient $googleAdsClient,
    int $customerId,
    array $conversionActionIds
) {
    $userListActionInfoList = [];
    foreach ($conversionActionIds as $conversionActionId) {
        // Creates the UserListActionInfo object for a given conversion action. This specifies
        // the conversion action that, when triggered, will cause a user to be added to a
        // UserList.
        $userListActionInfoList[] = new UserListActionInfo(
            [
            'conversion_action' => ResourceNames::forConversionAction(
                $customerId,
                $conversionActionId
            )
            ]
        );
    }

    // Creates a basic user list info object with all of the conversion actions.
    $basicUserListInfo = new BasicUserListInfo(['actions' => $userListActionInfoList]);

    // Creates the basic user list.
    $basicUserList = new UserList(
        [
        'name' => 'Example BasicUserList #' . Helper::getPrintableDatetime(),
        'description' => 'A list of people who have triggered one or more conversion actions',
        'membership_status' => UserListMembershipStatus::OPEN,
        'membership_life_span' => 365,
        'basic_user_list' => $basicUserListInfo
        ]
    );

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

    // Issues a mutate request to add the user list and prints some information.
    $userListServiceClient = $googleAdsClient->getUserListServiceClient();
    $response = $userListServiceClient->mutateUserLists(
        MutateUserListsRequest::build($customerId, [$operation])
    );
    printf(
        "Created basic user list with resource name '%s'.%s",
        $response->getResults()[0]->getResourceName(),
        PHP_EOL
    );
}

Python

def main(
    client: GoogleAdsClient,
    customer_id: str,
    conversion_action_ids: List[str],
) -> None:
    """Creates a combination user list.

    Args:
        client: The Google Ads client.
        customer_id: The customer ID for which to add the user list.
        conversion_action_ids: The IDs of the conversion actions for the basic
            user list.
    """
    # Get the UserListService and ConversionActionService clients.
    user_list_service: UserListServiceClient = client.get_service(
        "UserListService"
    )
    conversion_action_service: ConversionActionServiceClient = (
        client.get_service("ConversionActionService")
    )

    # Create a list of UserListActionInfo objects for the given conversion
    # actions. These specify the conversion actions that, when triggered, will
    # cause a user to be added to a UserList.
    user_list_action_info_list: List[UserListActionInfo] = []
    for conversion_action_id in conversion_action_ids:
        user_list_action_info: UserListActionInfo = client.get_type(
            "UserListActionInfo"
        )
        user_list_action_info.conversion_action = (
            conversion_action_service.conversion_action_path(
                customer_id, conversion_action_id
            )
        )
        user_list_action_info_list.append(user_list_action_info)

    # Create a UserListOperation and populate the UserList.
    user_list_operation: UserListOperation = client.get_type(
        "UserListOperation"
    )
    user_list: UserList = user_list_operation.create
    user_list.name = f"Example BasicUserList #{uuid4()}"
    user_list.description = (
        "A list of people who have triggered one or more conversion actions"
    )
    user_list.membership_status = client.enums.UserListMembershipStatusEnum.OPEN
    user_list.membership_life_span = 365
    # The basic user list info object contains the conversion action info.
    user_list.basic_user_list.actions.extend(user_list_action_info_list)

    # Issue a mutate request to add the user list, then print the results.
    response: MutateUserListsResponse = user_list_service.mutate_user_lists(
        customer_id=customer_id, operations=[user_list_operation]
    )
    print(
        "Created basic user list with resource name "
        f"'{response.results[0].resource_name}.'"
    )

小茹

def add_conversion_based_user_list(customer_id, conversion_action_ids)
  # GoogleAdsClient will read a config file from
  # ENV['HOME']/google_ads_config.rb when called without parameters
  client = Google::Ads::GoogleAds::GoogleAdsClient.new

  # Creates the basic user list.
  operation = client.operation.create_resource.user_list do |u|
    u.name = "Example BasicUserList ##{(Time.new.to_f * 100).to_i}"
    u.description = "A list of people who have triggered one or more conversion actions"
    u.membership_status = :OPEN
    u.membership_life_span = 365
    # Creates a basic user list info object with all of the conversion actions.
    u.basic_user_list = client.resource.basic_user_list_info do |info|
      conversion_action_ids.each do |conversion_action_id|
        # Creates the UserListActionInfo object for a given conversion action.
        # This specifies the conversion action that, when triggered, will cause a
        # user to be added to a user_list.
        info.actions << client.resource.user_list_action_info do |action|
          action.conversion_action =
            client.path.conversion_action(customer_id, conversion_action_id)
        end
      end
    end
  end

  # Issues a mutate request to add the user list and prints some information.
  response = client.service.user_list.mutate_user_lists(
    customer_id: customer_id,
    operations: [operation],
  )

  puts "Created basic user list with resource name " \
    "#{response.results.first.resource_name}"
end

Perl

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

  my $user_list_action_info_list = [];
  foreach my $conversion_action_id (@$conversion_action_ids) {
    # Create the UserListActionInfo object for a given conversion action. This
    # specifies the conversion action that, when triggered, will cause a user to
    # be added to a UserList.
    push @$user_list_action_info_list,
      Google::Ads::GoogleAds::V25::Common::UserListActionInfo->new({
        conversionAction =>
          Google::Ads::GoogleAds::V25::Utils::ResourceNames::conversion_action(
          $customer_id, $conversion_action_id
          )});
  }

  # Create a basic user list info object with all of the conversion actions.
  my $basic_user_list_info =
    Google::Ads::GoogleAds::V25::Common::BasicUserListInfo->new({
      actions => $user_list_action_info_list
    });

  # Create the basic user list.
  my $basic_user_list = Google::Ads::GoogleAds::V25::Resources::UserList->new({
    name        => "Example BasicUserList #" . uniqid(),
    description =>
      "A list of people who have triggered one or more conversion actions",
    membershipStatus   => OPEN,
    membershipLifeSpan => 365,
    basicUserList      => $basic_user_list_info
  });

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

  # Issue a mutate request to add the user list and print some information.
  my $user_lists_response = $api_client->UserListService()->mutate({
      customerId => $customer_id,
      operations => [$user_list_operation]});

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

  return 1;
}

curl

採取非轉換動作的訪客

您可以將基本使用者名單與RemarketingAction建立關聯，而非 ConversionAction，為在網站上採取您不視為轉換的動作的使用者建立名單。如要這麼做，請在 basic_user_list.actions 中，將每個 UserListActionInfo 物件的 remarketing_action 欄位設為 RemarketingAction 的資源名稱。

擷取清單

如要擷取使用者名單，請對 user_list 資源發出下列 Google Ads 查詢語言查詢：

SELECT
  user_list.name,
  user_list.membership_status,
  user_list.membership_life_span
FROM user_list
WHERE
  user_list.resource_name = 'customers/CUSTOMER_ID/userLists/USER_LIST_ID'

指定清單

建立目標對象區隔後，下一步就是指定該區隔。

指定目標對象區隔規則

  1. 您無法同時在廣告活動和廣告群組層級設定正面 (可出價) 使用者名單。如要為廣告活動設定正向使用者名單條件，請先從廣告活動中的所有廣告群組移除這類條件。

  2. 使用者名單正面指定目標僅適用於搜尋廣告活動。如果是多媒體廣告活動，則必須排除設定 user_list 的 CampaignCriterion。

  3. 在搜尋和購物廣告活動中，AdGroupCriterion 和 CampaignCriterion 的使用者名單目標不支援設定下列欄位：

將廣告指定給使用者名單

這項程序與 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.V25.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: GoogleAdsClient,
    customer_id: str,
    ad_group_id: str,
    user_list_resource_name: str,
) -> str:
    """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: AdGroupCriterionOperation = client.get_type(
        "AdGroupCriterionOperation"
    )
    # Creates the ad group criterion targeting members of the user list.
    ad_group_criterion: AdGroupCriterion = 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: AdGroupCriterionServiceClient = (
        client.get_service("AdGroupCriterionService")
    )
    response: MutateAdGroupCriteriaResponse = (
        ad_group_criterion_service.mutate_ad_group_criteria(
            customer_id=customer_id, operations=[ad_group_criterion_operation]
        )
    )
    resource_name: str = 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

小茹

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::V25::Resources::AdGroupCriterion->new({
      adGroup => Google::Ads::GoogleAds::V25::Utils::ResourceNames::ad_group(
        $customer_id, $ad_group_id
      ),
      userList => Google::Ads::GoogleAds::V25::Common::UserListInfo->new({
          userList => $user_list_resource_name
        })});

  # Create the operation.
  my $ad_group_criterion_operation =
    Google::Ads::GoogleAds::V25::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;
}

curl

與其他類型的條件一樣，您可以將其他屬性指派給 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.V25.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: GoogleAdsClient, customer_id: str, campaign_id: str
) -> List[str]:
    """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: str = 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: GoogleAdsServiceClient = client.get_service(
        "GoogleAdsService"
    )
    search_request: SearchGoogleAdsRequest = client.get_type(
        "SearchGoogleAdsRequest"
    )
    search_request.customer_id = customer_id
    search_request.query = query
    response: SearchGoogleAdsResponse = 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: List[str] = []
    row: GoogleAdsRow
    for row in response:
        resource_name: str = 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

小茹

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

  # 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::V25::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;
}

curl

然後移除傳回的所有廣告群組條件。

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.V25.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: GoogleAdsClient, customer_id: str, campaign_id: str
) -> None:
    """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: List[str] = get_user_list_ad_group_criteria(
        client, customer_id, campaign_id
    )

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

    ad_group_criterion_service: AdGroupCriterionServiceClient = (
        client.get_service("AdGroupCriterionService")
    )
    response: MutateAdGroupCriteriaResponse = (
        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}'"
    )

小茹

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::V25::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};
  }
}

curl

移除廣告群組條件後，您可以使用 CampaignCriterion，將廣告活動中的廣告指定給使用者名單：

使用 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.V25.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: GoogleAdsClient,
    customer_id: str,
    campaign_id: str,
    user_list_resource_name: str,
) -> str:
    """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: CampaignCriterionOperation = client.get_type(
        "CampaignCriterionOperation"
    )
    campaign_criterion: CampaignCriterion = 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: CampaignCriterionServiceClient = (
        client.get_service("CampaignCriterionService")
    )
    response: MutateCampaignCriteriaResponse = (
        campaign_criterion_service.mutate_campaign_criteria(
            customer_id=customer_id, operations=[campaign_criterion_operation]
        )
    )
    resource_name: str = 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

小茹

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::V25::Resources::CampaignCriterion->new({
      campaign => Google::Ads::GoogleAds::V25::Utils::ResourceNames::campaign(
        $customer_id, $campaign_id
      ),
      userList => Google::Ads::GoogleAds::V25::Common::UserListInfo->new({
          userList => $user_list_resource_name
        })});

  # Create the operation.
  my $campaign_criterion_operation =
    Google::Ads::GoogleAds::V25::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;
}

curl

反之，如要改用廣告群組層級使用者名單，則必須移除現有的廣告活動層級使用者名單條件，移除程序與上述範例類似。

查看清單成效

如要收集目標對象區隔的成效資料，請對 ad_group_audience_view 或 campaign_audience_view 資源發出搜尋要求。舉例來說，您可以分析 metrics.conversions 或 metrics.cost_per_conversion，判斷指定特定目標對象區隔是否能提高轉換次數，然後據此調整出價調整係數。

SELECT
  ad_group.id,
  ad_group_criterion.criterion_id,
  ad_group_criterion.resource_name,
  metrics.conversions,
  metrics.cost_per_conversion
FROM ad_group_audience_view
WHERE segments.date DURING LAST_30_DAYS