Rule-based user lists let you define a targeting audience for your ads based on visited URLs or custom parameters you add to your remarketing tag.
Once you have a user list in place and add the remarketing tag to your site, you can target users in the list, bid differently for those users, and run reports that organize or filter stats based on members of the list.
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.
Flexible rule user lists
FlexibleRuleUserListInfo is a
rule-based user list that is a representation of visitors with one or more
actions. You can AND or OR these rules together along with a loopback window
for how many days back the rules apply. This is the preferred way of creating
rule-based user lists.
Adding the remarketing tag to your site
For your rule-based user lists to be populated, you need to add your account-level remarketing tag to your site.
If you're planning to build remarketing lists based only on visited page URLs, you don't need to make any edits to your remarketing tag. If you're using custom parameters, you need to edit your tag to include them, as detailed in Advanced strategies for tagging and creating remarketing lists.
Built-in remarketing tag parameters
You can use the built-in remarketing parameter url__ to target a user
list based on the URLs that people have visited on your website.
The following code illustrates how to create a rule-based user list for people who visited pages in two different sections of your website. Using a built-in remarketing parameter does not require making any edits to your remarketing tag.
Java
private void runExample(GoogleAdsClient googleAdsClient, long customerId) {
// Creates a UserListRuleInfo object containing the first rule.
UserListRuleInfo userVisitedSite1Rule =
createUserListRuleInfoFromUrl("http://example.com/example1");
// Creates a UserListRuleInfo object containing the second rule.
UserListRuleInfo userVisitedSite2Rule =
createUserListRuleInfoFromUrl("http://example.com/example2");
// Creates a UserListRuleInfo object containing the third rule.
UserListRuleInfo userVisitedSite3Rule =
createUserListRuleInfoFromUrl("http://example.com/example3");
// Create the user list "Visitors of page 1 AND page 2, but not page 3". To create the user list
// "Visitors of page 1 *OR* page 2, but not page 3", change the UserListFlexibleRuleOperator
// from AND to OR.
FlexibleRuleUserListInfo flexibleRuleUserListInfo =
FlexibleRuleUserListInfo.newBuilder()
.setInclusiveRuleOperator(UserListFlexibleRuleOperator.AND)
// Inclusive operands are joined together with the specified inclusiveRuleOperator. This
// represents the set of users that should be included in the user list.
.addInclusiveOperands(
FlexibleRuleOperandInfo.newBuilder()
.setRule(userVisitedSite1Rule)
// Optional: adds a lookback window for this rule, in days.
.setLookbackWindowDays(7L))
.addInclusiveOperands(
FlexibleRuleOperandInfo.newBuilder()
.setRule(userVisitedSite2Rule)
// Optional: adds a lookback window for this rule, in days.
.setLookbackWindowDays(7L))
.addExclusiveOperands(
// Exclusive operands are joined together with OR. This represents the set of users
// to be excluded from the user list.
FlexibleRuleOperandInfo.newBuilder().setRule(userVisitedSite3Rule))
.build();
// Defines a representation of a user list that is generated by a rule.
RuleBasedUserListInfo ruleBasedUserListInfo =
RuleBasedUserListInfo.newBuilder()
// Optional: To include past users in the user list, set the prepopulation_status to
// REQUESTED.
.setPrepopulationStatus(UserListPrepopulationStatus.REQUESTED)
.setFlexibleRuleUserList(flexibleRuleUserListInfo)
.build();
// Creates a user list.
UserList userList =
UserList.newBuilder()
.setName("Flexible rule user list for example.com #" + getPrintableDateTime())
.setDescription(
"Visitors of both http://example.com/example1 AND http://example.com/example2 but"
+ " NOT http://example.com/example3")
.setMembershipStatus(UserListMembershipStatus.OPEN)
.setMembershipLifeSpan(365)
.setRuleBasedUserList(ruleBasedUserListInfo)
.build();
// Creates the operation.
UserListOperation operation = UserListOperation.newBuilder().setCreate(userList).build();
// Creates the user list service client.
try (UserListServiceClient userListServiceClient =
googleAdsClient.getLatestVersion().createUserListServiceClient()) {
// Adds the user list.
MutateUserListsResponse response =
userListServiceClient.mutateUserLists(
Long.toString(customerId), ImmutableList.of(operation));
String userListResourceName = response.getResults(0).getResourceName();
// Prints the result.
System.out.printf("Created user list with resource name '%s'.%n", userListResourceName);
}
}
/**
* Creates a UserListRuleInfo object containing a rule targeting any user that visited the
* provided URL.
*/
private UserListRuleInfo createUserListRuleInfoFromUrl(String urlString) {
// Creates a rule targeting any user that visited a URL that equals the given urlString.
UserListRuleItemInfo userVisitedSiteRule =
UserListRuleItemInfo.newBuilder()
// Uses a built-in parameter to create a domain URL rule.
.setName(URL_STRING)
.setStringRuleItem(
UserListStringRuleItemInfo.newBuilder()
.setOperator(UserListStringRuleItemOperator.EQUALS)
.setValue(urlString))
.build();
// Returns a UserListRuleInfo object containing the rule.
return UserListRuleInfo.newBuilder()
.addRuleItemGroups(UserListRuleItemGroupInfo.newBuilder().addRuleItems(userVisitedSiteRule))
.build();
}
C#
public void Run(GoogleAdsClient client, long customerId)
{
// Creates a UserListRuleInfo object containing the first rule.
UserListRuleInfo userVisitedSite1Rule =
CreateUserListRuleInfoFromUrl("http://example.com/example1");
// Creates a UserListRuleInfo object containing the second rule.
UserListRuleInfo userVisitedSite2Rule =
CreateUserListRuleInfoFromUrl("http://example.com/example2");
// Creates a UserListRuleInfo object containing the third rule.
UserListRuleInfo userVisitedSite3Rule =
CreateUserListRuleInfoFromUrl("http://example.com/example3");
// Create the user list "Visitors of page 1 AND page 2, but not page 3". To create the
// user list "Visitors of page 1 *OR* page 2, but not page 3", change the
// UserListFlexibleRuleOperator from And to Or.
FlexibleRuleUserListInfo flexibleRuleUserListInfo = new FlexibleRuleUserListInfo
{
InclusiveRuleOperator = UserListFlexibleRuleOperator.And
};
// Inclusive operands are joined together with the specified inclusiveRuleOperator. This
// represents the set of users that should be included in the user list.
flexibleRuleUserListInfo.InclusiveOperands.Add(new FlexibleRuleOperandInfo
{
Rule = userVisitedSite1Rule,
// Optional: adds a lookback window for this rule, in days.
LookbackWindowDays = 7
});
flexibleRuleUserListInfo.InclusiveOperands.Add(new FlexibleRuleOperandInfo
{
Rule = userVisitedSite2Rule,
// Optional: adds a lookback window for this rule, in days.
LookbackWindowDays = 7
});
// Exclusive operands are joined together with OR. This represents the set of users
// to be excluded from the user list.
flexibleRuleUserListInfo.InclusiveOperands.Add(new FlexibleRuleOperandInfo
{
Rule = userVisitedSite3Rule
});
// Defines a representation of a user list that is generated by a rule.
RuleBasedUserListInfo ruleBasedUserListInfo = new RuleBasedUserListInfo
{
// Optional: To include past users in the user list, set the prepopulation_status to
// REQUESTED.
PrepopulationStatus = UserListPrepopulationStatus.Requested,
FlexibleRuleUserList = flexibleRuleUserListInfo
};
// Creates a user list.
UserList userList = new UserList
{
Name = $"Flexible rule user list example.com #{ExampleUtilities.GetRandomString()}",
Description = "Visitors of both https://example.com/example1 AND " +
"https://example.com/example2 but NOT https://example.com/example3",
MembershipStatus = UserListMembershipStatus.Open,
MembershipLifeSpan = 365,
RuleBasedUserList = ruleBasedUserListInfo
};
// Creates the operation.
UserListOperation operation = new UserListOperation
{
Create = userList
};
try
{
UserListServiceClient userListServiceClient =
client.GetService(Services.V14.UserListService);
MutateUserListsResponse response =
userListServiceClient.MutateUserLists(customerId.ToString(),
new[] { operation });
string userListResourceName = response.Results[0].ResourceName;
Console.WriteLine($"Created user list with resource name '{userListResourceName}'.");
}
catch (GoogleAdsException e)
{
Console.WriteLine("Failure:");
Console.WriteLine($"Message: {e.Message}");
Console.WriteLine($"Failure: {e.Failure}");
Console.WriteLine($"Request ID: {e.RequestId}");
throw;
}
}
/// <summary>
/// Creates a UserListRuleInfo object containing a rule targeting any user that visited the
/// provided URL.
/// </summary>
private UserListRuleInfo CreateUserListRuleInfoFromUrl(string urlString)
{
// Creates a rule targeting any user that visited a URL that equals the given urlString.
UserListRuleItemInfo userVisitedSiteRule = new UserListRuleItemInfo
{
Name = URL_STRING,
StringRuleItem = new UserListStringRuleItemInfo
{
Operator = UserListStringRuleItemOperator.Equals,
Value = urlString
}
};
// Returns a UserListRuleInfo object containing the rule.
UserListRuleInfo userListRuleInfo = new UserListRuleInfo();
UserListRuleItemGroupInfo userListRuleItemGroupInfo = new UserListRuleItemGroupInfo();
userListRuleItemGroupInfo.RuleItems.Add(userVisitedSiteRule);
userListRuleInfo.RuleItemGroups.Add(userListRuleItemGroupInfo);
return userListRuleInfo;
}
PHP
public static function runExample(
GoogleAdsClient $googleAdsClient,
int $customerId
) {
// Creates a rule targeting any user that visited a url that equals
// http://example.com/example1'.
$userVisitedSite1RuleInfo = self::createUserListRuleFromUrl('http://example.com/example1');
// Creates a rule targeting any user that visited a url that equals
// http://example.com/example2'.
$userVisitedSite2RuleInfo = self::createUserListRuleFromUrl('http://example.com/example2');
// Creates a rule targeting any user that visited a url that equals
// http://example.com/example3'.
$userVisitedSite3RuleInfo = self::createUserListRuleFromUrl('http://example.com/example3');
// Create the user list "Visitors of page 1 AND page 2, but not page 3".
// To create the user list "Visitors of page 1 *OR* page 2, but not page 3",
// change the UserListFlexibleRuleOperator from PBAND to OR.
$flexibleRuleUserListInfo = new FlexibleRuleUserListInfo([
'inclusive_rule_operator' => UserListFlexibleRuleOperator::PBAND,
'inclusive_operands' => [
new FlexibleRuleOperandInfo([
'rule' => $userVisitedSite1RuleInfo,
// Optionally add a lookback window for this rule, in days.
'lookback_window_days' => 7
]),
new FlexibleRuleOperandInfo([
'rule' => $userVisitedSite2RuleInfo,
// Optionally add a lookback window for this rule, in days.
'lookback_window_days' => 7
])
],
// Exclusive operands are joined together with OR. This represents the set of users to
// be excluded from the user list.
'exclusive_operands' => [
new FlexibleRuleOperandInfo(['rule' => $userVisitedSite3RuleInfo])
]
]);
// Defines a representation of a user list that is generated by a rule.
$ruleBasedUserListInfo = new RuleBasedUserListInfo([
// Optional: To include past users in the user list, set the prepopulation_status to
// REQUESTED.
'prepopulation_status' => UserListPrepopulationStatus::REQUESTED,
'flexible_rule_user_list' => $flexibleRuleUserListInfo
]);
// Creates a user list.
$userList = new UserList([
'name' => 'All visitors to http://example.com/example1 AND ' .
'http://example.com/example2 but NOT http://example.com/example3 #'
. Helper::getPrintableDatetime(),
'description' => 'Visitors of both http://example.com/example1 AND ' .
'http://example.com/example2 but NOT http://example.com/example3',
'membership_status' => UserListMembershipStatus::OPEN,
'membership_life_span' => 365,
'rule_based_user_list' => $ruleBasedUserListInfo
]);
// Creates the operation.
$operation = new UserListOperation();
$operation->setCreate($userList);
// Issues a mutate request to add the user list and prints some information.
$userListServiceClient = $googleAdsClient->getUserListServiceClient();
$response = $userListServiceClient->mutateUserLists(
MutateUserListsRequest::build($customerId, [$operation])
);
printf(
"Created user list with resource name '%s'.%s",
$response->getResults()[0]->getResourceName(),
PHP_EOL
);
}
Python
def main(client, customer_id):
"""Creates a rule-based user list.
The list will be defined by a combination of rules for users who have
visited two different pages of a website.
Args:
client: The Google Ads client.
customer_id: The customer ID for which to add the user list.
"""
# Create a UserListRuleInfo object containing the first rule.
user_visited_site1_rule_info = create_user_list_rule_info_from_url(
client, "http://example.com/example1"
)
# Create a UserListRuleInfo object containing the second rule.
user_visited_site2_rule_info = create_user_list_rule_info_from_url(
client, "http://example.com/example2"
)
# Create a UserListRuleInfo object containing the third rule.
user_visited_site3_rule_info = create_user_list_rule_info_from_url(
client, "http://example.com/example3"
)
# Create the user list "Visitors of page 1 AND page 2, but not page 3".
# To create the user list "Visitors of page 1 *OR* page 2, but not page 3",
# change the UserListFlexibleRuleOperator from AND to OR.
flexible_rule_user_list_info = client.get_type("FlexibleRuleUserListInfo")
flexible_rule_user_list_info.inclusive_rule_operator = (
client.enums.UserListFlexibleRuleOperatorEnum.AND
)
# Inclusive operands are joined together with the specified
# inclusive_rule_operator. This represents the set of users that should be
# included in the user list.
operand_1 = client.get_type("FlexibleRuleOperandInfo")
operand_1.rule = user_visited_site1_rule_info
# Optionally add a lookback window for this rule, in days.
operand_1.lookback_window_days = 7
flexible_rule_user_list_info.inclusive_operands.append(operand_1)
operand_2 = client.get_type("FlexibleRuleOperandInfo")
operand_2.rule = user_visited_site2_rule_info
# Optionally add a lookback window for this rule, in days.
operand_2.lookback_window_days = 7
flexible_rule_user_list_info.inclusive_operands.append(operand_2)
# Exclusive operands are joined together with OR.
# This represents the set of users to be excluded from the user list.
operand_3 = client.get_type("FlexibleRuleOperandInfo")
operand_3.rule = user_visited_site3_rule_info
flexible_rule_user_list_info.exclusive_operands.append(operand_3)
# Define a representation of a user list that is generated by a rule.
rule_based_user_list_info = client.get_type("RuleBasedUserListInfo")
# Optional: To include past users in the user list, set the
# prepopulation_status to REQUESTED.
rule_based_user_list_info.prepopulation_status = (
client.enums.UserListPrepopulationStatusEnum.REQUESTED
)
rule_based_user_list_info.flexible_rule_user_list = (
flexible_rule_user_list_info
)
# Create a user list.
user_list_operation = client.get_type("UserListOperation")
user_list = user_list_operation.create
user_list.name = (
"All visitors to http://example.com/example1 AND "
"http://example.com/example2 but NOT "
f"http://example.com/example3 #{uuid4()}"
)
user_list.description = (
"Visitors of both http://example.com/example1 AND "
"http://example.com/example2 but NOT"
"http://example.com/example3"
)
user_list.membership_status = client.enums.UserListMembershipStatusEnum.OPEN
user_list.membership_life_span = 365
user_list.rule_based_user_list = rule_based_user_list_info
# Issue a mutate request to add the user list, then print the results.
user_list_service = client.get_service("UserListService")
response = user_list_service.mutate_user_lists(
customer_id=customer_id, operations=[user_list_operation]
)
print(
"Created user list with resource name: "
f"'{response.results[0].resource_name}.'"
)
Ruby
def add_combined_rule_user_list(customer_id)
# GoogleAdsClient will read a config file from
# ENV['HOME']/google_ads_config.rb when called without parameters
client = Google::Ads::GoogleAds::GoogleAdsClient.new
user_visited_site1_rule_info = create_user_list_rule_info_from_url(
client,
'http://example.com/example1',
)
user_visited_site2_rule_info = create_user_list_rule_info_from_url(
client,
'http://example.com/example2',
)
user_visited_site3_rule_info = create_user_list_rule_info_from_url(
client,
'http://example.com/example3',
)
# Creates a user list.
operation = client.operation.create_resource.user_list do |u|
u.name = "Flexible rule user list for example.com ##{(Time.new.to_f * 1000).to_i}"
u.description = "Visitors of both http://example.com/example1 AND " \
"http://example.com/example2 but NOT http://example.com/example3"
u.membership_status = :OPEN
u.membership_life_span = 365
# Defines a representation of a user list that is generated by a rule.
u.rule_based_user_list = client.resource.rule_based_user_list_info do |r|
# Optional: To include past users in the user list, set the
# prepopulation_status to REQUESTED.
r.prepopulation_status = :REQUESTED
r.flexible_rule_user_list = client.resource.flexible_rule_user_list_info do |frul|
frul.inclusive_rule_operator = :AND
frul.inclusive_operands += [
client.resource.flexible_rule_operand_info do |froi|
froi.rule = user_visited_site1_rule_info
# Optionally add a lookback window for this rule, in days.
froi.lookback_window_days = 7
end,
client.resource.flexible_rule_operand_info do |froi|
froi.rule = user_visited_site2_rule_info
# Optionally add a lookback window for this rule, in days.
froi.lookback_window_days = 7
end,
]
frul.exclusive_operands << client.resource.flexible_rule_operand_info do |froi|
froi.rule = user_visited_site3_rule_info
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 user list with resource name " \
"#{response.results.first.resource_name}"
end
Perl
sub add_combined_rule_user_list {
my ($api_client, $customer_id) = @_;
# Create a UserListRuleInfo object containing the first rule.
my $user_visited_site1_rule_info =
create_user_list_rule_info_from_url("http://example.com/example1");
# Create a UserListRuleInfo object containing the second rule.
my $user_visited_site2_rule_info =
create_user_list_rule_info_from_url("http://example.com/example2");
# Create a UserListRuleInfo object containing the third rule.
my $user_visited_site3_rule_info =
create_user_list_rule_info_from_url("http://example.com/example3");
# Create the user list "Visitors of page 1 AND page 2, but not page 3".
# To create the user list "Visitors of page 1 *OR* page 2, but not page 3",
# change the UserListFlexibleRuleOperator from AND to OR.
my $flexible_rule_user_list_info =
Google::Ads::GoogleAds::V14::Common::FlexibleRuleUserListInfo->new({
inclusiveRuleOperator => AND,
# Inclusive operands are joined together with the specified inclusiveRuleOperator.
# This represents the set of users that should be included in the user list.
inclusiveOperands => [
Google::Ads::GoogleAds::V14::Common::FlexibleRuleOperandInfo->new({
rule => $user_visited_site1_rule_info,
# Optionally add a lookback window for this rule, in days.
lookbackWindowDays => 7
}
),
Google::Ads::GoogleAds::V14::Common::FlexibleRuleOperandInfo->new({
rule => $user_visited_site2_rule_info,
# Optionally add a lookback window for this rule, in days.
lookbackWindowDays => 7
})
],
# Exclusive operands are joined together with OR.
# This represents the set of users to be excluded from the user list.
exclusiveOperands => [
Google::Ads::GoogleAds::V14::Common::FlexibleRuleOperandInfo->new({
rule => $user_visited_site3_rule_info
})
],
});
# Define a representation of a user list that is generated by a rule.
my $rule_based_user_list_info =
Google::Ads::GoogleAds::V14::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 a user list.
my $user_list = Google::Ads::GoogleAds::V14::Resources::UserList->new({
name => "Flexible rule user list for example.com #" . uniqid(),
description => "Visitors of both http://example.com/example1 AND " .
"http://example.com/example2 but NOT http://example.com/example3",
membershipStatus => OPEN,
membershipLifespan => 365,
ruleBasedUserList => $rule_based_user_list_info
});
# Create the operation.
my $user_list_operation =
Google::Ads::GoogleAds::V14::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 user list with resource name '%s'.\n",
$user_lists_response->{results}[0]{resourceName};
return 1;
}
Custom remarketing tag parameters
You can add custom remarketing tag parameters to your remarketing tag to create more tailored user lists.
Before creating your own custom parameters, check out the list of predefined parameters to 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.