Advertisers seeking to create user lists based on mobile app behavior should
implement the Firebase SDK or work with third-party SDKs in order to track
in-app behavior.
Retrieve the Google tag
All Google Ads accounts have exactly one account-levelGoogle
tag, created automatically
when the account is opened.
If you're planning to build audience segments based only on visited page URLs,
you don't need to make any edits to your Google tag. If you're using custom
parameters, you need to edit your tag to include them, as detailed inAdvanced
strategies for tagging and creating remarketing
lists.
You can use the built-in remarketing parameterurl__to target a user list
based on the URLs that people have visited on your website, as demonstrated in
theVisitors to your website example.
Before creating your own custom parameters, check out the list ofpredefined parametersto see
if there's already a good fit for your use case. Using predefined parameters
makes it easier to integrate with other Google Ads remarketing features.
Create the user list
You need to create a user list that contains the people who've triggered the
remarketing tag configured on your website. Create and manage a user list with
theUserListService.
To create a list that captures everyone who visited any page on your website,
set therule_based_user_listfield of yourUserListwith aRuleBasedUserListInfoobject.
Next, specify aFlexibleRuleUserListInfofield on
yourRuleBasedUserListInfoobject, which contains a rule targeting people who
visited your website.
defcreate_user_list(client:GoogleAdsClient,customer_id:str)->str:"""Creates a user list targeting users that have visited a given URL.Args:client: an initialized GoogleAdsClient instance.customer_id: a str client customer ID used to create a user list.Returns:a str resource name for the newly created user list."""# Creates a UserListOperation.user_list_operation:UserListOperation=client.get_type("UserListOperation")# Creates a UserList.user_list:UserList=user_list_operation.createuser_list.name=f"All visitors to example.com #{uuid4()}"user_list.description="Any visitor to any page of example.com"user_list.membership_status=client.enums.UserListMembershipStatusEnum.OPENuser_list.membership_life_span=365# Optional: To include past users in the user list, set the# prepopulation_status to REQUESTED.user_list.rule_based_user_list.prepopulation_status=(client.enums.UserListPrepopulationStatusEnum.REQUESTED)# Specifies that the user list targets visitors of a page with a URL that# contains 'example.com'.user_list_rule_item_group_info:UserListRuleItemGroupInfo=client.get_type("UserListRuleItemGroupInfo")user_list_rule_item_info:UserListRuleItemInfo=client.get_type("UserListRuleItemInfo")# Uses a built-in parameter to create a domain URL rule.user_list_rule_item_info.name="url__"user_list_rule_item_info.string_rule_item.operator=(client.enums.UserListStringRuleItemOperatorEnum.CONTAINS)user_list_rule_item_info.string_rule_item.value="example.com"user_list_rule_item_group_info.rule_items.append(user_list_rule_item_info)# Specify that the user list targets visitors of a page based on the# provided rule.flexible_rule_user_list_info:FlexibleRuleUserListInfo=(user_list.rule_based_user_list.flexible_rule_user_list)flexible_rule_user_list_info.inclusive_rule_operator=(client.enums.UserListFlexibleRuleOperatorEnum.AND)# Inclusive operands are joined together with the specified# inclusive rule operator.rule_operand:FlexibleRuleOperandInfo=client.get_type("FlexibleRuleOperandInfo")rule_operand.rule.rule_item_groups.extend([user_list_rule_item_group_info])rule_operand.lookback_window_days=7flexible_rule_user_list_info.inclusive_operands.append(rule_operand)user_list_service:UserListServiceClient=client.get_service("UserListService")response:MutateUserListsResponse=user_list_service.mutate_user_lists(customer_id=customer_id,operations=[user_list_operation])resource_name:str=response.results[0].resource_nameprint(f"Created user list with resource name: '{resource_name}'")returnresource_name
defcreate_user_list(client,customer_id)# Creates the user list operation.operation=client.operation.create_resource.user_listdo|ul|ul.name="All visitors to example.com ##{(Time.new.to_f*1000).to_i}"ul.description="Any visitor to any page of example.com"ul.membership_status=:OPENul.membership_life_span=365# Defines a representation of a user list that is generated by a rule.ul.rule_based_user_list=client.resource.rule_based_user_list_infodo|r|# To include past users in the user list, set the prepopulation_status# to REQUESTED.r.prepopulation_status=:REQUESTED# Specifies that the user list targets visitors of a page based on# the provided rule.r.flexible_rule_user_list=client.resource.flexible_rule_user_list_infodo|frul|frul.inclusive_rule_operator=:ANDfrul.inclusive_operands<<client.resource.flexible_rule_operand_infodo|froi|froi.rule=client.resource.user_list_rule_infodo|u|u.rule_item_groups<<client.resource.user_list_rule_item_group_infodo|group|group.rule_items<<client.resource.user_list_rule_item_infodo|item|# Uses a built-in parameter to create a domain URL rule.item.name="url__"item.string_rule_item=client.resource.user_list_string_rule_item_infodo|s|s.operator=:CONTAINSs.value="example.com"endendendend# Optionally add a lookback window for this rule, in days.froi.lookback_window_days=7endendendend# Issues a mutate request to add the user list.response=client.service.user_list.mutate_user_lists(customer_id:customer_id,operations:[operation],)user_list_resource_name=response.results.first.resource_nameputs"Created user list with resource name '#{user_list_resource_name}'"user_list_resource_nameend
subcreate_user_list{my($api_client,$customer_id)=@_;# Create a rule targeting any user that visited a url containing 'example.com'.my$rule=Google::Ads::GoogleAds::V21::Common::UserListRuleItemInfo->new({# Use a built-in parameter to create a domain URL rule.name=>"url__",stringRuleItem=>Google::Ads::GoogleAds::V21::Common::UserListStringRuleItemInfo->new({operator=>CONTAINS,value=>"example.com"})});# Specify that the user list targets visitors of a page based on the provided rule.my$user_list_rule_item_group_info=Google::Ads::GoogleAds::V21::Common::UserListRuleItemGroupInfo->new({ruleItems=>[$rule]});my$flexible_rule_user_list_info=Google::Ads::GoogleAds::V21::Common::FlexibleRuleUserListInfo->new({inclusiveRuleOperator=>AND,# Inclusive operands are joined together with the specified inclusiveRuleOperator.inclusiveOperands=>[Google::Ads::GoogleAds::V21::Common::FlexibleRuleOperandInfo->new({rule=>Google::Ads::GoogleAds::V21::Common::UserListRuleInfo->new({ruleItemGroups=>[$user_list_rule_item_group_info]}),# Optionally add a lookback window for this rule, in days.lookbackWindowDays=>7})],exclusiveOperands=>[]});# Define a representation of a user list that is generated by a rule.my$rule_based_user_list_info=Google::Ads::GoogleAds::V21::Common::RuleBasedUserListInfo->new({# Optional: To include past users in the user list, set the# prepopulationStatus to REQUESTED.prepopulationStatus=>REQUESTED,flexibleRuleUserList=>$flexible_rule_user_list_info});# Create the user list.my$user_list=Google::Ads::GoogleAds::V21::Resources::UserList->new({name=>"All visitors to example.com #".uniqid(),description=>"Any visitor to any page of example.com",membershipLifespan=>365,membershipStatus=>OPEN,ruleBasedUserList=>$rule_based_user_list_info});# Create the operation.my$user_list_operation=Google::Ads::GoogleAds::V21::Services::UserListService::UserListOperation->new({create=>$user_list});# Add the user list, then print and return the new list's resource name.my$user_lists_response=$api_client->UserListService()->mutate({customerId=>$customer_id,operations=>[$user_list_operation]});my$user_list_resource_name=$user_lists_response->{results}[0]{resourceName};printf"Created user list with resource name '%s'.\n",$user_list_resource_name;return$user_list_resource_name;}
With your audience segment created, the next step is to target it.
Audience segment targeting rules
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.
Positive targeting by user list is only supported for Search campaigns. For
Display campaigns,CampaignCriterionthat setsuser_listmust be
excluded.
In Search and Shopping campaigns, user list targets don't support setting
the following fields:
The process is similar to other types of targeting criteria in the API. The
following code demonstrates how you can use anAdGroupCriterionto target ads in an ad group to a user list:
deftarget_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 groupcriterion.ad_group_id: a str ID for an ad group used to create an ad groupcriterion 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.createad_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_namead_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_nameprint("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}.")returnresource_name
deftarget_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_criteriondo|agc|agc.ad_group=client.path.ad_group(customer_id,ad_group_id)agc.user_list=client.resource.user_list_infodo|info|info.user_list=user_listendend# 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_nameputs"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_nameend
subtarget_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 theAdGroupCriterionobject, 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.
defget_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"""SELECTad_group_criterion.criterion_idFROM ad_group_criterionWHERE 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_idsearch_request.query=queryresponse: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:GoogleAdsRowforrowinresponse:resource_name:str=row.ad_group_criterion.resource_nameprint("Ad group criterion with resource name '{resource_name}' was ""found.")user_list_criteria.append(resource_name)returnuser_list_criteria
defget_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=<<~QUERYSELECTad_group_criterion.criterion_idFROMad_group_criterionWHEREcampaign.id=#{campaign_id}ANDad_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.eachdo|row|ad_group_criterion_resource_name=row.ad_group_criterion.resource_nameputs"Ad group criterion with resource name "\"'#{ad_group_criterion_resource_name}' was found"user_list_criteria<<ad_group_criterion_resource_nameenduser_list_criteriaend
subget_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;}
defremove_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 groupcriteria 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]=[]forad_group_criterion_resource_nameinall_ad_group_criteria:remove_operation:AdGroupCriterionOperation=client.get_type("AdGroupCriterionOperation")remove_operation.remove=ad_group_criterion_resource_nameremove_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}'")
defremove_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.eachdo|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.eachdo|result|puts"Successfully removed ad group criterion with resource name "\"'#{result.resource_name}'"endend
subremove_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=[];foreachmy$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}};foreachmy$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.
deftarget_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 campaigncriterion.campaign_id: a str ID for a campaign used to create a campaigncriterion 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.createcampaign_criterion.campaign=client.get_service("CampaignService").campaign_path(customer_id,campaign_id)campaign_criterion.user_list.user_list=user_list_resource_namecampaign_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_nameprint("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}")returnresource_name
deftarget_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_criteriondo|cc|cc.campaign=client.path.campaign(customer_id,campaign_id)cc.user_list=client.resource.user_list_infodo|info|info.user_list=user_listendend# 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_nameputs"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_nameend
subtarget_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;}
In order to collect performance data for your audience segments, issue a search
request against thead_group_audience_viewor thecampaign_audience_viewresource.
For example, you might look at theconversionsorcost_per_conversionto
determine if targeting the audience segment is actually leading to more
conversions, then adjust your bid modifiers accordingly.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-09-03 UTC."],[[["\u003cp\u003eUtilize the Google Ads API to create user lists based on website visitor behavior for remarketing campaigns.\u003c/p\u003e\n"],["\u003cp\u003eLeverage \u003ccode\u003eurl__\u003c/code\u003e and custom parameters to refine user list targeting based on specific website interactions.\u003c/p\u003e\n"],["\u003cp\u003eManage user list targeting at both the campaign and ad group levels, ensuring alignment with your campaign objectives.\u003c/p\u003e\n"],["\u003cp\u003eRemove existing ad group user list criteria before applying targeting at the campaign level to avoid conflicts.\u003c/p\u003e\n"],["\u003cp\u003eMonitor user list performance metrics like conversions and cost-per-conversion and adjust bids for optimal results.\u003c/p\u003e\n"]]],[],null,[]]
