Multiple User Lists

You can combine two or more existing user lists to create even more sophisticated targeting.

Create the user list

You can construct custom combinations of existing user lists as a logical_user_list with UserListLogicalRuleInfo fields. The rules in the logical_user_list are AND ed, so a user must match every rule to be considered in the list. However, each rule lets you specify whether its operands are AND ed or OR ed. In other words, you can specify whether the user must fulfill allof the rule operands or just one of them.

In addition, rules let you specify other logical_user_list objects as operands, effectively letting you create a tree of them. logical_user_list can be a very powerful way of defining complex hierarchies of groups for your targeting. You can combine lists with different AccessReason fields. However, if access is revoked, then that UserList will be treated as a list with no members when the rules of the logical_user_list are evaluated.

The following code shows how to create a logical_user_list containing users in either of two basic_user_list instances:

Code example to create a logical user list

Java

 private 
  
 void 
  
 runExample 
 ( 
  
 GoogleAdsClient 
  
 googleAdsClient 
 , 
  
 long 
  
 customerId 
 , 
  
 List<Long> 
  
 userListIds 
 ) 
  
 { 
  
 // Adds each of the provided list IDs to a list of rule operands specifying which lists the 
  
 // operator should target. 
  
 List<LogicalUserListOperandInfo> 
  
 logicalUserListOperandInfoList 
  
 = 
  
 new 
  
 ArrayList 
<> (); 
  
 for 
  
 ( 
 long 
  
 userListId 
  
 : 
  
 userListIds 
 ) 
  
 { 
  
 String 
  
 userListResourceName 
  
 = 
  
 ResourceNames 
 . 
 userList 
 ( 
 customerId 
 , 
  
 userListId 
 ); 
  
 logicalUserListOperandInfoList 
 . 
 add 
 ( 
  
 LogicalUserListOperandInfo 
 . 
 newBuilder 
 (). 
 setUserList 
 ( 
 userListResourceName 
 ). 
 build 
 ()); 
  
 } 
  
 // Creates the UserListLogicalRuleInfo specifying that a user should be added to the new list if 
  
 // they are present in any of the provided lists. 
  
 UserListLogicalRuleInfo 
  
 userListLogicalRuleInfo 
  
 = 
  
 UserListLogicalRuleInfo 
 . 
 newBuilder 
 () 
  
 // Using ANY means that a user should be added to the combined list if they are present 
  
 // on any of the lists targeted in the LogicalUserListOperandInfo. Use ALL to add users 
  
 // present on all of the provided lists or NONE to add users that aren't present on any 
  
 // of the targeted lists. 
  
 . 
 setOperator 
 ( 
 UserListLogicalRuleOperator 
 . 
 ANY 
 ) 
  
 . 
 addAllRuleOperands 
 ( 
 logicalUserListOperandInfoList 
 ) 
  
 . 
 build 
 (); 
  
 // Creates the new combination user list. 
  
 UserList 
  
 userList 
  
 = 
  
 UserList 
 . 
 newBuilder 
 () 
  
 . 
 setName 
 ( 
 "My combination list of other user lists #" 
  
 + 
  
 getPrintableDateTime 
 ()) 
  
 . 
 setLogicalUserList 
 ( 
  
 LogicalUserListInfo 
 . 
 newBuilder 
 (). 
 addRules 
 ( 
 userListLogicalRuleInfo 
 ). 
 build 
 ()) 
  
 . 
 build 
 (); 
  
 // Creates the operation. 
  
 UserListOperation 
  
 operation 
  
 = 
  
 UserListOperation 
 . 
 newBuilder 
 (). 
 setCreate 
 ( 
 userList 
 ). 
 build 
 (); 
  
 // Creates the service client. 
  
 try 
  
 ( 
 UserListServiceClient 
  
 userListServiceClient 
  
 = 
  
 googleAdsClient 
 . 
 getLatestVersion 
 (). 
 createUserListServiceClient 
 ()) 
  
 { 
  
 // Adds the user list. 
  
 MutateUserListsResponse 
  
 response 
  
 = 
  
 userListServiceClient 
 . 
 mutateUserLists 
 ( 
  
 Long 
 . 
 toString 
 ( 
 customerId 
 ), 
  
 ImmutableList 
 . 
 of 
 ( 
 operation 
 )); 
  
 // Prints the response. 
  
 System 
 . 
 out 
 . 
 printf 
 ( 
  
 "Created combination user list with resource name, '%s'.%n" 
 , 
  
 response 
 . 
 getResults 
 ( 
 0 
 ). 
 getResourceName 
 ()); 
  
 } 
 } 
  
  

C#

 public 
  
 void 
  
 Run 
 ( 
 GoogleAdsClient 
  
 client 
 , 
  
 long 
  
 customerId 
 , 
  
 long 
 [] 
  
 userListIds 
 ) 
 { 
  
 // Gets the UserListService client. 
  
 UserListServiceClient 
  
 userListServiceClient 
  
 = 
  
 client 
 . 
 GetService 
 ( 
 Services 
 . 
 V21 
 . 
 UserListService 
 ); 
  
 // Adds each of the provided list IDs to a list of rule operands specifying which lists 
  
 // the operator should target. 
  
 List<LogicalUserListOperandInfo> 
  
 logicalUserListOperandInfoList 
  
 = 
  
 userListIds 
 . 
 Select 
 ( 
 userListId 
  
 = 
>  
 new 
  
 LogicalUserListOperandInfo 
  
 { 
  
 UserList 
  
 = 
  
 ResourceNames 
 . 
 UserList 
 ( 
 customerId 
 , 
  
 userListId 
 ) 
  
 }). 
 ToList 
 (); 
  
 // Creates the UserListLogicalRuleInfo specifying that a user should be added to the new 
  
 // list if they are present in any of the provided lists. 
  
 UserListLogicalRuleInfo 
  
 userListLogicalRuleInfo 
  
 = 
  
 new 
  
 UserListLogicalRuleInfo 
  
 { 
  
 // Using ANY means that a user should be added to the combined list if they are 
  
 // present on any of the lists targeted in the LogicalUserListOperandInfo. Use ALL 
  
 // to add users present on all of the provided lists or NONE to add users that 
  
 // aren't present on any of the targeted lists. 
  
 Operator 
  
 = 
  
 UserListLogicalRuleOperatorEnum 
 . 
 Types 
 . 
 UserListLogicalRuleOperator 
 . 
 Any 
 , 
  
 }; 
  
 userListLogicalRuleInfo 
 . 
 RuleOperands 
 . 
 Add 
 ( 
 logicalUserListOperandInfoList 
 ); 
  
 LogicalUserListInfo 
  
 logicalUserListInfo 
  
 = 
  
 new 
  
 LogicalUserListInfo 
 (); 
  
 logicalUserListInfo 
 . 
 Rules 
 . 
 Add 
 ( 
 userListLogicalRuleInfo 
 ); 
  
 // Creates the new combination user list. 
  
 UserList 
  
 userList 
  
 = 
  
 new 
  
 UserList 
  
 { 
  
 Name 
  
 = 
  
 "My combination list of other user lists " 
  
 + 
  
 $"#{ExampleUtilities.GetRandomString()}" 
 , 
  
 LogicalUserList 
  
 = 
  
 logicalUserListInfo 
  
 }; 
  
 // Creates the operation. 
  
 UserListOperation 
  
 operation 
  
 = 
  
 new 
  
 UserListOperation 
  
 { 
  
 Create 
  
 = 
  
 userList 
  
 }; 
  
 try 
  
 { 
  
 // Sends the request to add the user list and prints the response. 
  
 MutateUserListsResponse 
  
 response 
  
 = 
  
 userListServiceClient 
 . 
 MutateUserLists 
  
 ( 
 customerId 
 . 
 ToString 
 (), 
  
 new 
 [] 
  
 { 
  
 operation 
  
 }); 
  
 Console 
 . 
 WriteLine 
 ( 
 "Created combination 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 $userListIds 
 ) { 
 // Adds each of the provided list IDs to a list of rule operands specifying which lists the 
 // operator should target. 
 $logicalUserListOperandInfoList = []; 
 foreach ($userListIds as $userListId) { 
 $logicalUserListOperandInfoList[] = new LogicalUserListOperandInfo([ 
 'user_list' => ResourceNames::forUserList($customerId, $userListId) 
 ]); 
 } 
 // Creates the UserListLogicalRuleInfo specifying that a user should be added to the new 
 // list if they are present in any of the provided lists. 
 $userListLogicalRuleInfo = new UserListLogicalRuleInfo([ 
 // Using ANY means that a user should be added to the combined list if they are present 
 // on any of the lists targeted in the LogicalUserListOperandInfo. Use ALL to add users 
 // present on all of the provided lists or NONE to add users that aren't present on any 
 // of the targeted lists. 
 'operator' => UserListLogicalRuleOperator::ANY, 
 'rule_operands' => $logicalUserListOperandInfoList 
 ]); 
 // Creates the new combination user list. 
 $userList = new UserList([ 
 'name' => 'My combination list of other user lists #' . Helper::getPrintableDatetime(), 
 'logical_user_list' => new LogicalUserListInfo([ 
 'rules' => [$userListLogicalRuleInfo] 
 ]) 
 ]); 
 // Creates the operation. 
 $operation = new UserListOperation(); 
 $operation->setCreate($userList); 
 // 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 combination user list with resource name '%s'.%s", 
 $response->getResults()[0]->getResourceName(), 
 PHP_EOL 
 ); 
 }  
 

Python

 def 
  
 main 
 ( 
 client 
 : 
 GoogleAdsClient 
 , 
 customer_id 
 : 
 str 
 , 
 user_list_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. 
 user_list_ids: A list of user list IDs to logically combine. 
 """ 
 # Get the UserListService client. 
 user_list_service 
 : 
 UserListServiceClient 
 = 
 client 
 . 
 get_service 
 ( 
 "UserListService" 
 ) 
 # Add each of the provided list IDs to a list of rule operands specifying 
 # which lists the operator should target. 
 logical_user_list_operand_info_list 
 : 
 List 
 [ 
 LogicalUserListOperandInfo 
 ] 
 = 
 [] 
 for 
 user_list_id 
 in 
 user_list_ids 
 : 
 logical_user_list_operand_info 
 : 
 LogicalUserListOperandInfo 
 = 
 ( 
 client 
 . 
 get_type 
 ( 
 "LogicalUserListOperandInfo" 
 ) 
 ) 
 logical_user_list_operand_info 
 . 
 user_list 
 = 
 ( 
 user_list_service 
 . 
 user_list_path 
 ( 
 customer_id 
 , 
 user_list_id 
 ) 
 ) 
 logical_user_list_operand_info_list 
 . 
 append 
 ( 
 logical_user_list_operand_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 
 "My combination list of other user lists # 
 { 
 uuid4 
 () 
 } 
 " 
 # Create a UserListLogicalRuleInfo specifying that a user should be added to 
 # the new list if they are present in any of the provided lists. 
 user_list_logical_rule_info 
 : 
 UserListLogicalRuleInfo 
 = 
 client 
 . 
 get_type 
 ( 
 "UserListLogicalRuleInfo" 
 ) 
 # Using ANY means that a user should be added to the combined list if they 
 # are present on any of the lists targeted in the 
 # LogicalUserListOperandInfo. Use ALL to add users present on all of the 
 # provided lists or NONE to add users that aren't present on any of the 
 # targeted lists. 
 user_list_logical_rule_info 
 . 
 operator 
 = 
 ( 
 client 
 . 
 enums 
 . 
 UserListLogicalRuleOperatorEnum 
 . 
 ANY 
 ) 
 user_list_logical_rule_info 
 . 
 rule_operands 
 . 
 extend 
 ( 
 logical_user_list_operand_info_list 
 ) 
 user_list 
 . 
 logical_user_list 
 . 
 rules 
 . 
 append 
 ( 
 user_list_logical_rule_info 
 ) 
 # 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 logical user list with resource name " 
 f 
 "' 
 { 
 response 
 . 
 results 
 [ 
 0 
 ] 
 . 
 resource_name 
 } 
 .'" 
 ) 
  

Ruby

 def 
  
 add_logical_user_list 
 ( 
 customer_id 
 , 
  
 user_list_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 UserListLogicalRuleInfo specifying that a user should be added 
  
 # to the new list if they are present in any of the provided lists. 
  
 user_list_logical_rule_info 
  
 = 
  
 client 
 . 
 resource 
 . 
 user_list_logical_rule_info 
  
 do 
  
 | 
 info 
 | 
  
 # Using ANY means that a user should be added to the combined list if they 
  
 # are present on any of the lists targeted in the logical_user_list_operand_info. 
  
 # Use ALL to add users present on all of the provided lists or NONE to add 
  
 # users that aren't present on any of the targeted lists. 
  
 info 
 . 
 operator 
  
 = 
  
 :ANY 
  
 user_list_ids 
 . 
 each 
  
 do 
  
 | 
 list_id 
 | 
  
 info 
 . 
 rule_operands 
 << 
 client 
 . 
 resource 
 . 
 logical_user_list_operand_info 
  
 do 
  
 | 
 op 
 | 
  
 op 
 . 
 user_list 
  
 = 
  
 client 
 . 
 path 
 . 
 user_list 
 ( 
 customer_id 
 , 
  
 list_id 
 ) 
  
 end 
  
 end 
  
 end 
  
 # Creates the new combination user list operation. 
  
 operation 
  
 = 
  
 client 
 . 
 operation 
 . 
 create_resource 
 . 
 user_list 
  
 do 
  
 | 
 ul 
 | 
  
 ul 
 . 
 name 
  
 = 
  
 "My combination list of other user lists 
 #{ 
 ( 
 Time 
 . 
 new 
 . 
 to_f 
  
 * 
  
 1000 
 ) 
 . 
 to_i 
 } 
 " 
  
 ul 
 . 
 logical_user_list 
  
 = 
  
 client 
 . 
 resource 
 . 
 logical_user_list_info 
  
 do 
  
 | 
 info 
 | 
  
 info 
 . 
 rules 
 << 
 user_list_logical_rule_info 
  
 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 combination user list with resource name " 
 \ 
  
 "' 
 #{ 
 response 
 . 
 results 
 . 
 first 
 . 
 resource_name 
 } 
 '" 
 end  
 
 . 
 rb 
  

Perl

 sub 
  
 add_logical_user_list 
  
 { 
  
 my 
  
 ( 
 $api_client 
 , 
  
 $customer_id 
 , 
  
 $user_list_ids 
 ) 
  
 = 
  
 @_ 
 ; 
  
 # Add each of the provided list IDs to a list of rule operands specifying which 
  
 # lists the operator should target. 
  
 my 
  
 $logical_user_list_operand_info_list 
  
 = 
  
 [] 
 ; 
  
 foreach 
  
 my 
  
 $user_list_id 
  
 ( 
 @$user_list_ids 
 ) 
  
 { 
  
 push 
  
 @$logical_user_list_operand_info_list 
 , 
  
 Google::Ads::GoogleAds::V21::Common:: 
 LogicalUserListOperandInfo 
 - 
> new 
 ({ 
  
 userList 
  
 = 
>  
 Google::Ads::GoogleAds::V21::Utils::ResourceNames:: 
 user_list 
 ( 
  
 $customer_id 
 , 
  
 $user_list_id 
  
 )}); 
  
 } 
  
 # Create the UserListLogicalRuleInfo specifying that a user should be added to 
  
 # the new list if they are present in any of the provided lists. 
  
 my 
  
 $user_list_logical_rule_info 
  
 = 
  
 Google::Ads::GoogleAds::V21::Common:: 
 UserListLogicalRuleInfo 
 - 
> new 
 ({ 
  
 # Using ANY means that a user should be added to the combined list if they 
  
 # are present on any of the lists targeted in the LogicalUserListOperandInfo. 
  
 # Use ALL to add users present on all of the provided lists or NONE to add 
  
 # users that aren't present on any of the targeted lists. 
  
 operator 
  
 = 
>  
 ANY 
 , 
  
 ruleOperands 
  
 = 
>  
 $logical_user_list_operand_info_list 
  
 }); 
  
 # Create the new combination user list. 
  
 my 
  
 $user_list 
  
 = 
  
 Google::Ads::GoogleAds::V21::Resources:: 
 UserList 
 - 
> new 
 ({ 
  
 name 
  
 = 
>  
 "My combination list of other user lists #" 
  
 . 
  
 uniqid 
 (), 
  
 logicalUserList 
  
 = 
>  
 Google::Ads::GoogleAds::V21::Common:: 
 LogicalUserListInfo 
 - 
> new 
 ({ 
  
 rules 
  
 = 
>  
 [ 
 $user_list_logical_rule_info 
 ]})}); 
  
 # Create the operation. 
  
 my 
  
 $user_list_operation 
  
 = 
  
 Google::Ads::GoogleAds::V21::Services::UserListService:: 
 UserListOperation 
 - 
>  
 new 
 ({ 
  
 create 
  
 = 
>  
 $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 combination user list with resource name '%s'.\n" 
 , 
  
 $user_lists_response 
 - 
> { 
 results 
 }[ 
 0 
 ]{ 
 resourceName 
 }; 
  
 return 
  
 1 
 ; 
 } 
  
  

Retrieve the list

To retrieve your user list, you can issue the following Google Ads Query Language query to the user_list resource.

  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 
' 
 

Target the list

With your audience segment created, the next step is to target it.

Audience segment targeting rules

  1. Positive (biddable) user lists cannot be set at the campaign level and the ad group level at the same time. Positive user list criteria must be removed from all ad groups within a campaign before one can be set for the campaign.

  2. Positive targeting by user list is only supported for Search campaigns. For Display campaigns, CampaignCriterion that sets user_list must be excluded.

  3. In Search and Shopping campaigns, user list targets don't support setting the following fields:

Target ads to your user list

The process is similar to other types of targeting criteria in the API. The following code demonstrates how you can use an AdGroupCriterion to target ads in an ad group to a user list:

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 
 . 
 V21 
 . 
 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  
 
 . 
 py 

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  
 
 . 
 rb 
  

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::V21::Resources:: 
 AdGroupCriterion 
 - 
> new 
 ({ 
  
 adGroup 
  
 = 
>  
 Google::Ads::GoogleAds::V21::Utils::ResourceNames:: 
 ad_group 
 ( 
  
 $customer_id 
 , 
  
 $ad_group_id 
  
 ), 
  
 userList 
  
 = 
>  
 Google::Ads::GoogleAds::V21::Common:: 
 UserListInfo 
 - 
> new 
 ({ 
  
 userList 
  
 = 
>  
 $user_list_resource_name 
  
 })}); 
  
 # Create the operation. 
  
 my 
  
 $ad_group_criterion_operation 
  
 = 
  
 Google::Ads::GoogleAds::V21::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 
 ; 
 } 
  
  

As with other types of criteria, you can assign other properties to the AdGroupCriterion object, such as bid overrides.

Switch targeting levels

If you are switching from ad group level user list criteria to campaign level, you must first remove the existing user list criteria from each enabled or paused ad group under that campaign. Click the expandable elements to view example code for each step.

First, retrieve all of the AdGroupCriteria under a given campaign.

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 
 . 
 V21 
 . 
 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  
 
 . 
 py 

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 
 , 
  
 ) 
  
 # 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  
 
 . 
 rb 
  

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

Then, remove all of the ad group criteria target that were returned.

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 
 . 
 V21 
 . 
 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 
 } 
 '" 
 ) 
  

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  
 
 . 
 rb 

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

Existing campaign level user list criteria must also be removed when switching to ad group level user lists, and the process mirrors the preceding example.

Target ads in a campaign to a user list, using a 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 
 . 
 V21 
 . 
 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  
 
 . 
 py 

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  
 
 . 
 rb 
  

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::V21::Resources:: 
 CampaignCriterion 
 - 
> new 
 ({ 
  
 campaign 
  
 = 
>  
 Google::Ads::GoogleAds::V21::Utils::ResourceNames:: 
 campaign 
 ( 
  
 $customer_id 
 , 
  
 $campaign_id 
  
 ), 
  
 userList 
  
 = 
>  
 Google::Ads::GoogleAds::V21::Common:: 
 UserListInfo 
 - 
> new 
 ({ 
  
 userList 
  
 = 
>  
 $user_list_resource_name 
  
 })}); 
  
 # Create the operation. 
  
 my 
  
 $campaign_criterion_operation 
  
 = 
  
 Google::Ads::GoogleAds::V21::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 
 ; 
 } 
  
  

Review list performance

In order to collect performance data for your audience segments, issue a search request against the ad_group_audience_view or the campaign_audience_view resource. For example, you might look at the conversions or cost_per_conversion to determine if targeting the audience segment is actually leading to more conversions, then adjust your bid modifiers accordingly.

  SELECT 
  
 ad_group_criterion 
 . 
 criterion_id 
 , 
  
 metrics 
 . 
 conversions 
 , 
  
 metrics 
 . 
 cost_per_conversion 
 FROM 
  
 ad_group_audience_view 
 
Create a Mobile Website
View Site in Mobile | Classic
Share by: