Remarketing allows you to advertise to people who have previously visited your website, used your mobile app, or who are in your CRM databases, by showing them relevant ads when they visit other sites or search on Google. The user lists used in remarketing can also be used for other types of audience targeting, such as Customer Match.
This guide covers:
- User list audience types
- Targeting settings for remarketing
- User list performance reports
- Remarketing with rule-based user lists
Limitations
Sensitive information about users can't be used to build remarketing lists. Before setting up a remarketing campaign and placing the remarketing tag on your website or app, please review our policy for advertising based on interests and location.
You can target or exclude user lists at both the ad group and campaign levels. However, positive (biddable) user lists cannot be set at both levels 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, the only option at the campaign level for
CriterionUserList
is to exclude those criteria.User list targets don't support setting the
urlCustomParameters
,trackingUrlTemplate
,finalUrls
,finalAppUrls
, orfinalMobileUrls
fields in Search and Shopping campaigns.User lists are not supported in test accounts and will automatically close upon creation.
Audience types in a UserList
You can remarket and target specific audiences with a
UserList
.
The list can be constructed from different audience types:
Visitors to your website - This is done through advertiser-defined rules. A rule can be as simple as including all visitors to your website.
Visitors who took specific actions - This can include actions such as a purchase on your website or app.
Multiple user lists - This is done by combining two or more user lists.
Similar audiences - People that share similar interests and behaviors with those in other user lists.
Customer Match with email address, address, or user ID - A user list of uploaded customer emails.
Visitors to your website
The simplest type of audience list comprises visitors to your website. More advanced targeting strategies described below can, for example, tailor ads to target only people who recently visited a specific page or combination of pages on your website.
All Google Ads accounts have exactly one account-level remarketing tag, created automatically when the account is opened. The tag is available even if you haven't yet initiated remarketing. The first step is to retrieve your account's account-level remarketing tag using CustomerService:
// Get the customer service.
CustomerServiceInterface customerService =
adWordsServices.get(session, CustomerServiceInterface.class);
// Retrieve the Customer object for the session. Make sure
// that the session's clientCustomerId is set to your account's
// ID.
Customer customer = customerService.getCustomers()[0];
// Print the account level Google global site tag.
System.out.printf("Customer ID %s has Google global site tag:%n%s%n",
customer.getCustomerId(),
customer.getRemarketingSettings().getGoogleGlobalSiteTag());
The next step is to install your account-level remarketing tag on all of your site's pages. Learn more about adding the remarketing tag to your site or mobile app in this Google Ads Help Center article.
You can also use the Google Tag Assistant in Chrome to validate your tag installation.
Next, you need to create a user list that contains the people who've triggered
the remarketing tag. You create and manage user lists with
AdwordsUserListService.
There are different kinds of user lists with different characteristics. To
create a list that captures everyone who visited any page on your website,
you can use an ExpressionRuleUserList
,
as shown below, where the URL of the visited page includes
your website's domain. See
Rule-based remarketing
for further details on using rule-based remarketing lists.
// Get the user list service.
AdwordsUserListServiceInterface userListService =
adWordsServices.get(session, AdwordsUserListServiceInterface.class);
// Use built-in parameter to create domain URL rule.
StringKey urlKey = new StringKey("url__");
StringRuleItem urlStringRuleItem = new StringRuleItem();
urlStringRuleItem.setKey(urlKey);
urlStringRuleItem.setOp(StringRuleItemStringOperator.CONTAINS);
urlStringRuleItem.setValue("example.com");
RuleItem urlRuleItem = new RuleItem();
urlRuleItem.setStringRuleItem(urlStringRuleItem);
RuleItemGroup ruleItemGroup = new RuleItemGroup();
ruleItemGroup.setItems(new RuleItem[] {urlRuleItem});
Rule rule = new Rule();
rule.setGroups(new RuleItemGroup[] {ruleItemGroup});
// Create the user list.
ExpressionRuleUserList expressionUserList = new ExpressionRuleUserList();
expressionUserList.setName("All visitors to example.com");
expressionUserList.setDescription("Any visitor to any page of example.com");
expressionUserList.setRule(rule);
expressionUserList.setMembershipLifeSpan(365L);
expressionUserList.setStatus(UserListMembershipStatus.OPEN);
// Optional: To include past users in the user list, set the
// prepopulationStatus to REQUESTED.
expressionUserList.setPrepopulationStatus(
RuleBasedUserListPrepopulationStatus.REQUESTED);
// Create and submit the operation.
UserListOperation operation = new UserListOperation();
operation.setOperator(Operator.ADD);
operation.setOperand(expressionUserList);
UserListReturnValue result =
userListService.mutate(new UserListOperation[] {operation});
Long userListId = result.getValue(0).getId();
Two important attributes of a user list are membershipLifeSpan
and
status
. The former allows you to define the time period, in days, for which a
user is considered to be in the list. The latter defines whether the list will
accept new users.
The final step is to target ads to members of your user list. The process is
similar to other types of targeting criteria in the API. The following code
demonstrates how you can use a
CriterionUserList
to target ads in an ad group to a user list:
// Get the ad group criterion service.
AdGroupCriterionServiceInterface adGroupCriterionService =
adWordsServices.get(session, AdGroupCriterionServiceInterface.class);
// Create user list criterion.
CriterionUserList userListCriterion = new CriterionUserList();
userListCriterion.setUserListId(userListId);
// Create biddable ad group criterion.
BiddableAdGroupCriterion biddableCriterion = new BiddableAdGroupCriterion();
biddableCriterion.setAdGroupId(adGroupId);
biddableCriterion.setCriterion(userListCriterion);
// Create operation.
AdGroupCriterionOperation operation = new AdGroupCriterionOperation();
operation.setOperand(biddableCriterion);
operation.setOperator(Operator.ADD);
AdGroupCriterionOperation[] operations =
new AdGroupCriterionOperation[] {operation};
// Apply the criterion.
AdGroupCriterionReturnValue result = adGroupCriterionService.mutate(operations);
As with other types of criteria, you can assign other properties to the
BiddableAdGroupCriterion
object, such as bid overrides.
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 adgroup under that campaign:
// Create selector for all user list criteria.
SelectorBuilder builder = new SelectorBuilder();
Selector selector = builder
.fields(AdGroupCriterionField.Id)
.equals(AdGroupCriterionField.AdGroupId, adGroupId)
.equals(AdGroupCriterionField.CriteriaType, "USER_LIST")
.build();
AdGroupCriterionServiceInterface criterionService =
new AdWordsServices().get(session, AdGroupCriterionServiceInterface.class);
AdGroupCriterionPage page = criterionService.get(selector);
List<AdGroupCriterionOperation> operations =
new ArrayList<AdGroupCriterionOperation>();
// Create remove operation for each user list.
for(AdGroupCriterion criterion : page.getEntries()){
Long criterionId = criterion.getCriterion().getId();
// Create user list criterion and specify the criterion ID to remove.
CriterionUserList userListCriterion = new CriterionUserList();
userListCriterion.setId(criterionId);
// Create biddable ad group criterion.
BiddableAdGroupCriterion biddableCriterion = new BiddableAdGroupCriterion();
biddableCriterion.setAdGroupId(adGroupId);
biddableCriterion.setCriterion(userListCriterion);
// Create remove operation.
AdGroupCriterionOperation operation = new AdGroupCriterionOperation();
operation.setOperand(biddableCriterion);
operation.setOperator(Operator.REMOVE);
operations.add(operation);
}
// Remove the criteria.
AdGroupCriterionReturnValue result =
adGroupCriterionService.mutate(
operations.toArray(new AdGroupCriterionOperation[operations.size()]));
Existing campaign level user list criteria must also be removed when switching
to ad group level user lists, and the process mirrors the example shown above.
Please note that the criterionId
is not the criterion's underlying user list
id.
Targeting ads in a campaign to a user list is done similarly:
// Get the campaign criterion service.
CampaignCriterionServiceInterface campaignCriterionService =
adWordsServices.get(session, CampaignCriterionServiceInterface.class);
// Create user list criterion.
CriterionUserList userListCriterion = new CriterionUserList();
userListCriterion.setUserListId(userListId);
// Create campaign criterion.
CampaignCriterion campaignCriterion = new CampaignCriterion();
campaignCriterion.setCampaignId(campaignId);
campaignCriterion.setCriterion(userListCriterion);
// Create operation.
CampaignCriterionOperation operation = new CampaignCriterionOperation();
operation.setOperand(campaignCriterion);
operation.setOperator(Operator.ADD);
CampaignCriterionOperation[] operations =
new CampaignCriterionOperation[] {operation};
// Apply the criterion.
CampaignCriterionReturnValue result = campaignCriterionService.mutate(operations);
Visitors to specific pages
You can target people who have visited specific pages or sections of
your website using an ExpressionRuleUserList
in a manner similar to the
example above but targeted to more specific URLs, not just your website's domain.
See Rule-based remarketing
below for an example and more details.
Visitors of a page who did visit another page
You can target people who visited more than one page using a
CombinedRuleUserList
.
The targeting would be done the same way as in the previous example. Only the
first step changes, where you use a CombinedRuleUserList
rather than an
ExpressionRuleUserList
.
First, create the two rules:
Java
// Visitors of a page who visited another page. StringKey urlStringKey = new StringKey("url__"); StringRuleItem site1StringRuleItem = new StringRuleItem(); site1StringRuleItem.setKey(urlStringKey); site1StringRuleItem.setOp(StringRuleItemStringOperator.EQUALS); site1StringRuleItem.setValue("example.com/example1"); RuleItem site1RuleItem = new RuleItem(); site1RuleItem.setStringRuleItem(site1StringRuleItem); StringRuleItem site2StringRuleItem = new StringRuleItem(); site2StringRuleItem.setKey(urlStringKey); site2StringRuleItem.setOp(StringRuleItemStringOperator.EQUALS); site2StringRuleItem.setValue("example.com/example2"); RuleItem site2RuleItem = new RuleItem(); site2RuleItem.setStringRuleItem(site2StringRuleItem); // Create two RuleItemGroups to show that a visitor browsed two sites. RuleItemGroup site1RuleItemGroup = new RuleItemGroup(); site1RuleItemGroup.setItems(new RuleItem[]{site1RuleItem}); RuleItemGroup site2RuleItemGroup = new RuleItemGroup(); site2RuleItemGroup.setItems(new RuleItem[]{site2RuleItem}); // Create two rules to show that a visitor browsed two sites. Rule userVisitedSite1Rule = new Rule(); userVisitedSite1Rule.setGroups(new RuleItemGroup[]{site1RuleItemGroup}); Rule userVisitedSite2Rule = new Rule(); userVisitedSite2Rule.setGroups(new RuleItemGroup[]{site2RuleItemGroup});
C#
// Visitors of a page who visited another page. See // https://developers.google.com/adwords/api/docs/reference/latest/AdwordsUserListService.StringKey // for more details. StringKey urlStringKey = new StringKey() { name = "url__" }; StringRuleItem site1StringRuleItem = new StringRuleItem { key = urlStringKey, op = StringRuleItemStringOperator.EQUALS, value = "example.com/example1" }; RuleItem site1RuleItem = new RuleItem { Item = site1StringRuleItem }; StringRuleItem site2StringRuleItem = new StringRuleItem { key = (urlStringKey), op = (StringRuleItemStringOperator.EQUALS), value = ("example.com/example2") }; RuleItem site2RuleItem = new RuleItem { Item = (site2StringRuleItem) }; // Create two RuleItemGroups to show that a visitor browsed two sites. RuleItemGroup site1RuleItemGroup = new RuleItemGroup { items = new RuleItem[] { site1RuleItem } }; RuleItemGroup site2RuleItemGroup = new RuleItemGroup { items = new RuleItem[] { site2RuleItem } }; // Create two rules to show that a visitor browsed two sites. Rule userVisitedSite1Rule = new Rule { groups = new RuleItemGroup[] { site1RuleItemGroup } }; Rule userVisitedSite2Rule = new Rule { groups = new RuleItemGroup[] { site2RuleItemGroup } };
PHP
// Visitors of a page who visited another page. $site1StringRuleItem = new StringRuleItem(); $site1StringKey = new StringKey(); $site1StringKey->setName('url__'); $site1StringRuleItem->setKey($site1StringKey); $site1StringRuleItem->setOp(StringRuleItemStringOperator::EQUALS); $site1StringRuleItem->setValue('example.com/example1'); $site1RuleItem = new RuleItem(); $site1RuleItem->setStringRuleItem($site1StringRuleItem); $site2StringRuleItem = new StringRuleItem(); $site2StringKey = new StringKey(); $site2StringKey->setName('url__'); $site2StringRuleItem->setKey($site2StringKey); $site2StringRuleItem->setOp(StringRuleItemStringOperator::EQUALS); $site2StringRuleItem->setValue('example.com/example2'); $site2RuleItem = new RuleItem(); $site2RuleItem->setStringRuleItem($site2StringRuleItem); // Create two RuleItemGroups to show that a visitor browsed two sites. $site1ItemGroup = new RuleItemGroup(); $site1ItemGroup->setItems([$site1RuleItem]); $site2ItemGroup = new RuleItemGroup(); $site2ItemGroup->setItems([$site2RuleItem]); // Create two rules to show that a visitor browsed two sites. $userVisitedSite1Rule = new Rule(); $userVisitedSite1Rule->setGroups([$site1ItemGroup]); $userVisitedSite2Rule = new Rule(); $userVisitedSite2Rule->setGroups([$site2ItemGroup]);
Perl
# Visitors of a page who visited another page. my $site1_string_rule_item = Google::Ads::AdWords::v201809::StringRuleItem->new({ key => Google::Ads::AdWords::v201809::StringKey->new( {name => "url__"} ), op => "EQUALS", value => "example.com/example1" }); my $site1_rule_item = Google::Ads::AdWords::v201809::RuleItem->new( {StringRuleItem => $site1_string_rule_item}); my $site2_string_rule_item = Google::Ads::AdWords::v201809::StringRuleItem->new({ key => Google::Ads::AdWords::v201809::StringKey->new( {name => "url__"} ), op => "EQUALS", value => "example.com/example2" }); my $site2_rule_item = Google::Ads::AdWords::v201809::RuleItem->new( {StringRuleItem => $site2_string_rule_item}); # Create two RuleItemGroups to show that a visitor browsed two sites. my $site1_item_group = Google::Ads::AdWords::v201809::RuleItemGroup->new( {items => [$site1_rule_item]}); my $site2_item_group = Google::Ads::AdWords::v201809::RuleItemGroup->new( {items => [$site2_rule_item]}); # Create two rules to show that a visitor browsed two sites. my $user_visited_site1_rule = Google::Ads::AdWords::v201809::Rule->new({ groups => [$site1_item_group] }); my $user_visited_site2_rule = Google::Ads::AdWords::v201809::Rule->new({ groups => [$site2_item_group] });
Python
# Visitors of a page who visited another page. site1_rule_item = { 'StringRuleItem': { 'key': {'name': 'url__'}, 'op': 'EQUALS', 'value': 'example.com/example1' } } site2_rule_item = { 'StringRuleItem': { 'key': {'name': 'url__'}, 'op': 'EQUALS', 'value': 'example.com/example2' } } # Create two rules to show that a visitor browsed two sites. user_visited_site1_rule = { 'groups': [{ 'items': [site1_rule_item] }] } user_visited_site2_rule = { 'groups': [{ 'items': [site2_rule_item] }] }
Ruby
# Visitors of a page who visited another page. sites = ['example.com/example1', 'example.com/example2'] # Create two rules to show that a visitor browsed two sites. user_visited_site_rules = sites.map do |site| { :groups => [ :items => [ { :xsi_type => 'StringRuleItem', :key => {:name => 'url__'}, :op => 'EQUALS', :value => site } ]]} end
Then, combine the rules with the CombinedRuleUserList
:
Java
// Create the user list where "Visitors of a page who did visit another page". // To create a user list where "Visitors of a page who did not visit another // page", change the ruleOperator from AND to AND_NOT. CombinedRuleUserList combinedRuleUserList = new CombinedRuleUserList(); combinedRuleUserList.setName("Combined rule user list created at " + creationTimeString); combinedRuleUserList.setDescription("Users who visited two sites."); combinedRuleUserList.setLeftOperand(userVisitedSite1Rule); combinedRuleUserList.setRightOperand(userVisitedSite2Rule); combinedRuleUserList.setRuleOperator(CombinedRuleUserListRuleOperator.AND);
C#
// Create the user list where "Visitors of a page who did visit another page". // To create a user list where "Visitors of a page who did not visit another // page", change the ruleOperator from AND to AND_NOT. CombinedRuleUserList combinedRuleUserList = new CombinedRuleUserList { name = "Combined rule user list created at " + creationTimeString, description = "Users who visited two sites.", leftOperand = userVisitedSite1Rule, rightOperand = userVisitedSite2Rule, ruleOperator = CombinedRuleUserListRuleOperator.AND };
PHP
// Create the user list where "Visitors of a page who did visit another // page". To create a user list where "Visitors of a page who did not visit // another page", change the ruleOperator from AND to AND_NOT. $combinedUserList = new CombinedRuleUserList(); $combinedUserList->setName( sprintf('Combined rule user list created at %s', date('Y-m-d_His')) ); $combinedUserList->setDescription('Users who visited two sites.'); $operands = self::createCombinedUserListRules(); $combinedUserList->setLeftOperand($operands[0]); $combinedUserList->setRightOperand($operands[1]); $combinedUserList->setRuleOperator( CombinedRuleUserListRuleOperator::AND_VALUE );
Perl
# Create the user list where "Visitors of a page who did visit another page". # To create a user list where "Visitors of a page who did not visit another # page", change the ruleOperator from AND to AND_NOT. my $combined_user_list = Google::Ads::AdWords::v201809::CombinedRuleUserList->new({ name => "Combined rule user list created at ${creation_time}", description => "Users who visited two sites.", leftOperand => $user_visited_site1_rule, rightOperand => $user_visited_site2_rule, ruleOperator => "AND" });
Python
# Create the user list for "Visitors of a page who did visit another page". # To create a user list for "Visitors of a page who did not visit another # page", change the ruleOperator from AND to AND_NOT. combined_user_list = { 'xsi_type': 'CombinedRuleUserList', 'name': 'Combined rule user lst create at ${creation_time}', 'description': 'Users who visited two sites.', 'leftOperand': user_visited_site1_rule, 'rightOperand': user_visited_site2_rule, 'ruleOperator': 'AND' }
Ruby
# Create the user list where "Visitors of a page who did visit another page". # To create a user list where "Visitors of a page who did not visit another # page", change the ruleOperator from AND to AND_NOT. combined_rule_user_list = { :xsi_type => 'CombinedRuleUserList', :name => 'Combined rule user list "Visitors of a page who did visit another page"', :description => 'Users who visited two sites.', :left_operand => user_visited_site_rules[0], :right_operand => user_visited_site_rules[1], :rule_operator => 'AND' }
Visitors of a page who did not visit another page
You can target people who visited one page but not another page by using
CombinedRuleUserList
.
The only change that would have to be made to the previous example is that the
rule operator needs to change from AND
to AND_NOT
.
Visitors who took specific actions
You can populate your audience list with people who have taken specific actions on your website. If you're using conversion tracking, you can target ads to people who previously triggered a conversion (such as a purchase) on your website.
You can also target ads to people who have taken a particular action on your
website that you do not consider a conversion, such as when a person adds
but then deletes an item from their shopping cart without making a purchase.
Both of these use cases are covered through
BasicUserList
.
Triggered a conversion
If you haven't yet created a conversion tracker, you can do so using ConversionTrackerService. You can then install the conversion tracker tag on your website.
A BasicUserList
defines its membership as people who had triggered one or more
conversion trackers on your website. When you create a BasicUserList
, you
provide the value of the id
field in the
ConversionTracker
you want associated with the user list.
The following example creates a BasicUserList
associated with two existing
conversion trackers:
AdwordsUserListServiceInterface userListService =
adWordsServices.get(session, AdwordsUserListServiceInterface.class);
// Indicate the conversion trackers we want to associate with a new user list
UserListConversionType conversionType1 = new UserListConversionType();
conversionType1.setId(conversionTrackerId1);
UserListConversionType conversionType2 = new UserListConversionType();
conversionType2.setId(conversionTrackerId2);
// Create a basic user list associated with the two conversion trackers.
BasicUserList userList = new BasicUserList();
userList.setName("Example BasicUserList");
userList.setDescription("A list of people who have triggered conversion #1 or #2");
userList.setMembershipLifeSpan(365L);
userList.setConversionTypes(new UserListConversionType[] {conversionType1, conversionType2});
userList.setStatus(UserListMembershipStatus.OPEN);
// Create operation.
UserListOperation operation = new UserListOperation();
operation.setOperand(userList);
operation.setOperator(Operator.ADD);
UserListOperation[] operations = new UserListOperation[] {operation};
// Add user list.
UserListReturnValue result = userListService.mutate(operations);
Non-conversion actions
You can create a BasicUserList
for people who took actions on your website
that you do not consider conversions by associating it with a
ConversionTracker
with a category of
REMARKETING
.
There are two ways to create such a ConversionTracker
object. The first is by
directly using ConversionTrackerService.
The second is to have it created automatically by Google Ads at the same time you
create the associated BasicUserList
. The following code illustrates the second
method:
UserListConversionType conversionType = new UserListConversionType();
conversionType.setName("Remarketing-only conversion tracker");
// Create basic user list.
BasicUserList userList = new BasicUserList();
userList.setName("Example BasicUserList Remarketing Only");
userList.setDescription("Triggered an action not considered a conversion");
userList.setMembershipLifeSpan(365L);
userList.setConversionTypes(new UserListConversionType[] {conversionType});
userList.setStatus(UserListMembershipStatus.OPEN);
// Same as previous example
...
Note that a
UserListConversionType
is attached to the list, but no id
is set. This triggers the automatic
generation of a ConversionTracker
object of category REMARKETING
.
You can retrieve the Google global site tag for the automatically generated
ConversionTracker
object:
// From the user list creation obtain the tracker ID.
String conversionId = userList.getConversionTypes().get(0).getId().toString();
// Create predicate and selector.
Predicate predicate = new Predicate();
predicate.setField("Id");
predicate.setOperator(PredicateOperator.IN);
predicate.setValues(new String [] {conversionId});
Selector selector = new Selector();
selector.setFields(new String[] {"Id"});
selector.setPredicates(new Predicate[] {predicate});
// Get the conversion tracker.
ConversionTrackerPage page = conversionTrackerService.get(selector);
// Print out the conversion tracker Google global site tag.
System.out.println(((AdWordsConversionTracker) page.getEntries()[0]).getGoogleGlobalSiteTag());
Multiple user lists
You can construct custom combinations of existing user lists as a
LogicalUserList
with
UserListLogicalRule
fields.
The rules in the LogicalUserList
are ANDed so a user must match every rule to
be considered in the list. However, each rule lets you specify whether its
operands are ANDed or ORed. In other words, you can specify whether the user
must fulfill ALL of the rule operands or just one of them.
In addition, rules let you specify other LogicalUserList
objects as operands,
effectively letting you create a tree of them. LogicalUserList
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 LogicalUserList
are evaluated.
The following code shows how to create a LogicalUserList
containing users in either of two BasicUserList
:
// My basic user list of Mars customers.
BasicUserList basicMarsList = new BasicUserList();
basicMarsList.setId(...);
// My basic user list of Venus customers.
BasicUserList basicVenusList = new BasicUserList();
basicVenusList.setId(...);
LogicalUserListOperand marsListOperand = new LogicalUserListOperand();
marsListOperand.setUserList(basicMarsList);
LogicalUserListOperand venusListOperand = new LogicalUserListOperand();
venusListOperand.setUserList(basicVenusList);
UserListLogicalRule rule = new UserListLogicalRule(
UserListLogicalRuleOperator.ANY,
new LogicalUserListOperand[] {marsListOperand, venusListOperand});
// Create logical user list.
LogicalUserList combinationList = new LogicalUserList();
combinationList.setName("My combination list of Mars or Venus customers #"
+ System.currentTimeMillis());
combinationList.setRules(new UserListLogicalRule[] {rule});
// Create operations.
UserListOperation operation = new UserListOperation();
operation.setOperand(combinationList);
operation.setOperator(Operator.ADD);
UserListOperation[] operations = new UserListOperation[] {operation};
// Add logical user list.
UserListReturnValue result = userListService.mutate(operations);
Similar audiences
One way of reaching new audiences is using a
SimilarUserList
.
With this user list you can target people who share characteristics with those
in your other user lists.
A SimilarUserList
is automatically generated by Google for each UserList
,
based on a variety of factors; for example, the number of people on the original
list, how recently they joined the list, the types of sites they browsed, and
whether the list is yours. This process may take up to four days starting from
when the source list was created.
The following code shows how to find all available SimilarUserList
objects:
AdwordsUserListServiceInterface userListService =
adWordsServices.get(session, AdwordsUserListServiceInterface.class);
UserListPage page = userListService.get(
new SelectorBuilder()
.fields("Id", "Name", "SeedUserListId")
.equals("ListType", UserListType._SIMILAR)
.build());
for (UserList userlist : page.getEntries()) {
System.out.printf("id: %d, name: %s, seed list id: %d%n",
userlist.getId(),
userlist.getName(),
((SimilarUserList)userlist).getSeedUserListId());
}
Customer Match with email address, address, or user ID
For advertisers with rich CRM databases, you can define and target audience
lists based on your CRM data. You can upload CRM data in bulk, append/remove
data, or use these user lists to create a
LogicalUserList
.
These audience lists are eligible to serve on Google Search, YouTube, Gmail, and the Google Display Network.
Per policy, you will only be allowed to upload data that you have acquired yourself (first party). You are not allowed to buy email lists from third parties and upload them into the account.
For privacy concerns, email addresses, first names, and last names must be hashed using the SHA-256 algorithm before being uploaded. In order to standardize the hash results, prior to hashing one of these values you must:
Remove leading/trailing whitespaces.
Convert the text to lowercase.
See the Code examples section below for a full demonstration of how to add members, correctly normalized and hashed.
Options for Customer Match in different campaign types
- Search network-only campaigns
- A
CrmBasedUserList
is available. Ads will show on the search network. - Display network-only campaigns
- A
CrmBasedUserList
and itsSimilarUserList
are available. Ads will show on Gmail only if there are GSP creatives. - Display Expansion on Search campaigns
- A
CrmBasedUserList
is available. Ads will show on the search network and on Gmail (only if there are GSP creatives). - Video campaigns
- A
CrmBasedUserList
and itsSimilarUserList
are available. Ads will show on YouTube only if there are in-stream TrueView ads.
Customer Match with phone number
Similar to Customer Match with emails, you can also perform customer matching with phone numbers.
For privacy concerns, the phone number needs to be hashed using the
SHA-256 algorithm before being uploaded. In order to standardize
results, convert each phone number to
E164 format before hashing. This format
represents a phone number as a number up to fifteen digits in length
starting with a +
sign (e.g. +12125650000, +442070313000).
If the phone number is not correctly formatted before hashing, the API will still accept the hashed phone number, but the phone number will not be matched with a customer.
Customer Match with mobile device IDs
Similar to Customer Match with emails, you can also perform customer matching using IDFA (Identifier for Advertising) or AAID (Google Advertising ID) mobile device IDs. Note that mobile device IDs cannot be combined with any other types of customer data.
Customer Match considerations
When implementing Customer Match, keep the following points in mind:
The API imposes a limit on the number of members in each
mutateMember
request.The
MembershipLifeSpan
limit might be different from other user lists.It takes 6 to 48 hours for a list to be populated with members, so you'll most likely see an "In Progress" status (on the Google Ads UI) if you upload to an audience list more frequently than once every 12 hours.
If your job includes an operation with
removeAll
set totrue
, it may run for up to 72 hours.For privacy purposes, the user list size will show as zero until the list has at least 1,000 members. After that, the size will be rounded to the two most significant digits.
Upload at least 5,000 members to the list to ensure that ads start serving.
A
CrmBasedUserList
can only be combined with anotherCrmBasedUserList
when using aLogicalUserList
. All the policies forCrmBasedUserList
will apply to the result user list.
Targeting settings for remarketing
Once you've added a user list to an ad group or campaign as a criterion, it's
ready to go--however, it may not be targeting exactly how you'd expect.
To verify that the targeting is working as intended, check the
TargetingSetting
on ad groups or campaigns that use the new list by calling their getSettings
methods.
You can set up details on how your various criteria types are used for
targeting with an array of
TargetingSettingDetail
objects. Each TargetingSettingDetail
lets you control whether a
type of criteria uses the Bid only
or Target and bid
scheme.
When using Bid only
, the criteria won't be used to restrict traffic, but
will allow you to bid differently for different users on your lists.
The Target and bid
scheme enables the criteria to restrict ad group traffic
only to users on the targeted list.
The default targeting for remarketing lists is Target and bid
. If you're
adding remarketing lists to your main search campaign, consider changing the
targeting setting to Bid only
. If you're setting up a duplicate campaign for
remarketing lists for search ads, keep the targeting at Target and bid
.
Here's an example that uses the Java client library to set the
TargetingSettingDetail
to Bid only
on an ad group:
AdGroup adGroup = ... // fetch the ad group relevant for this case
List<Setting> settings = Lists.newArrayList();
List<TargetingSettingDetail> details = Lists.newArrayList();
TargetingSetting targetingSetting = null;
if (adGroup.getSettings() != null) {
// Find the existing TargetingSetting if it exists, and keep
// track of all other settings.
for (Setting setting : adGroup.getSettings()) {
if (setting instanceof TargetingSetting) {
targetingSetting = (TargetingSetting) setting;
} else {
settings.add(setting);
}
}
if (targetingSetting != null) {
// Copy all the existing TargetingSettingDetails except the one for
// USER_INTEREST_AND_LIST.
for (TargetingSettingDetail settingDetail : targetingSetting.getDetails()) {
if (!CriterionTypeGroup.USER_INTEREST_AND_LIST.equals(
settingDetail.getCriterionTypeGroup())) {
details.add(settingDetail);
}
}
}
}
if (targetingSetting == null) {
targetingSetting = new TargetingSetting();
}
// Create a new USER_INTEREST_AND_LIST targeting setting detail and add
// it to the details list.
TargetingSettingDetail userListsSetting = new TargetingSettingDetail();
userListsSetting.setCriterionTypeGroup(CriterionTypeGroup.USER_INTEREST_AND_LIST);
// true = "Bid only"; false = "Target and bid"
userListsSetting.setTargetAll(true);
details.add(userListsSetting);
targetingSetting.setDetails(details.toArray(new TargetingSettingDetail[details.size()]));
// Add the new TargetingSetting for USER_INTEREST_AND_LIST to the settings list.
settings.add(targetingSetting);
adGroup.setSettings(settings.toArray(new Setting[settings.size()]));
The process for setting Bid only
or Target and bid
on campaigns is nearly
identical. Use the getSettings
and setSettings
methods of a Campaign
object in the same way as shown for AdGroup
.
Performance reports
The Audience Performance report
exposes the fields needed to collect performance reports of your user lists.
For example, you might look at the Conversions
or CostPerConversion
in that
report to determine if targeting members of the list is actually leading to more
conversions, then adjust your bid modifiers accordingly. You can also see the
user list for each click by including the UserListId
field in the
Click Performance report.
Consult the
Reporting guide for more details.
Remarketing with rule-based user lists
Rule-based user lists allow you to define a targeting audience for your ads based on built-in remarketing tag parameters 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 or mobile app, 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.
Since this section focuses on rule-based lists, it contains
examples of creating ExpressionRuleUserList
and DateSpecificRuleUserList
.
Sensitive information about users can't be used to build remarketing lists. Before setting up a remarketing campaign and placing the remarketing tag on your website or app, please review our Personalized advertising page page.
Using 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. For example,
the code below 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.
StringKey urlKey = new StringKey("url__");
StringRuleItem urlStringRuleItem1 = new StringRuleItem();
urlStringRuleItem1.setKey(urlKey);
urlStringRuleItem1.setOp(StringRuleItemStringOperator.CONTAINS);
urlStringRuleItem1.setValue("example.com/section1/");
RuleItem urlRuleItem1 = new RuleItem();
urlRuleItem1.setStringRuleItem(urlStringRuleItem1);
StringRuleItem urlStringRuleItem2 = new StringRuleItem();
urlStringRuleItem2.setKey(urlKey);
urlStringRuleItem2.setOp(StringRuleItemStringOperator.CONTAINS);
urlStringRuleItem2.setValue("example.com/section2/");
RuleItem urlRuleItem2 = new RuleItem();
urlRuleItem2.setStringRuleItem(urlStringRuleItem2);
// Combine the two rule items into a RuleItemGroup so Google Ads will AND their
// rules together. To instead OR the rules together, each RuleItem should be
// placed in its own RuleItemGroup.
RuleItemGroup ruleItemGroup = new RuleItemGroup();
ruleItemGroup.setItems(new RuleItem[] {urlRuleItem1, urlRuleItem2});
Rule rule = new Rule();
rule.setGroups(new RuleItemGroup[] {ruleItemGroup});
// Create the user list.
ExpressionRuleUserList expressionUserList = new ExpressionRuleUserList();
expressionUserList.setName("Sections 1 and 2"));
expressionUserList.setDescription("Visitors to section1 or section2");
expressionUserList.setRule(rule);
Using custom remarketing tag parameters
You can add custom remarketing tag parameters to your remarketing tag to create more tailored user lists.
Scenario
Let's say you have a site where you've configured several custom remarketing tag parameters to capture the following attributes of users:
ecomm_pagetype
- The category of page on your site, such as checkout, cart, etc.cartsize
- The number of items in a user's shopping cart.checkoutdate
- The date on which a user checked out. You only set this parameter when a user has actually completed a purchase.
You're interested in showing more impressions to users who have placed multiple items in their shopping carts and initiated the checkout process. You also want to find users who have made a purchase during November and December because you plan to have a big sale on your site during those months.
You can describe this set of users with either of the following rules:
- Users who visited the checkout page and had more than one item in their cart.
- Users who checked out during the months of November or December.
If a user falls into either category 1 or category 2, you want to increase your bids in specific ad groups or campaigns by 25%.
Objects overview
Before diving into the code, let's take a look at the structure of a rule-based
user list. A rule-based list is represented in the AdWords API as a
RuleBasedUserList
.
The diagram below shows what the RuleBasedUserList
for this use case will look
like when we're done.

Create the first RuleItemGroup
Let's start by creating the first RuleItemGroup
on the left, which consists of
two RuleItem
s:
- Users who visited the checkout page.
- Users with more than one item in their shopping cart.
The first item uses the ecomm_pagetype
parameter which has string values, so
you'll want to create a StringRuleItem
first.
StringRuleItem checkoutStringRuleItem = new StringRuleItem(
new StringKey("ecomm_pagetype"), StringRuleItemStringOperator.EQUALS, "checkout");
RuleItem checkoutRuleItem = new RuleItem();
checkoutRuleItem.setStringRuleItem(checkoutStringRuleItem);
The second item uses the cartsize
parameter which has numeric values, so now
you'll need a NumberRuleItem
.
NumberRuleItem cartSizeNumberRuleItem = new NumberRuleItem(
new NumberKey("cartsize"), NumberRuleItemNumberOperator.GREATER_THAN, 1.0);
RuleItem cartSizeRuleItem = new RuleItem();
cartSizeRuleItem.setNumberRuleItem(cartSizeNumberRuleItem);
Next, combine the two RuleItems
into a RuleItemGroup
. By default, when items
are combined into an item group, Google Ads will AND
their rules together. See
the section below on creating the user list for more
details.
RuleItemGroup checkoutMultipleItemGroup = new RuleItemGroup();
checkoutMultipleItemGroup.setItems(new RuleItem[] {checkoutRuleItem, cartSizeRuleItem});
Create the second RuleItemGroup
The RuleItemGroup
on the right consists of two RuleItem
objects:
- Users who checked out after October 31st.
- Users who checked out before January 1st.
Both of these items use the checkoutdate
parameter which has date values, so
this time you'll create DateRuleItem
objects.
// Create the RuleItem for the start date.
DateRuleItem startDateDateRuleItem = new DateRuleItem(
new DateKey("checkoutdate"),
DateRuleItemDateOperator.AFTER, "20171031");
RuleItem startDateRuleItem = new RuleItem();
startDateRuleItem.setDateRuleItem(startDateDateRuleItem);
// Create the RuleItem for the end date.
DateRuleItem endDateDateRuleItem = new DateRuleItem(
new DateKey("checkoutdate"),
DateRuleItemDateOperator.BEFORE, "20180101");
RuleItem endDateRuleItem = new RuleItem();
endDateRuleItem.setDateRuleItem(endDateDateRuleItem);
As with the group on the left, combine these two RuleItem
objects into a
RuleItemGroup
to AND
them together.
RuleItemGroup checkedOutNovDecItemGroup = new RuleItemGroup();
checkedOutNovDecItemGroup.setItems(new RuleItem[] {startDateRuleItem, endDateRuleItem});
Create the user list
For ExpressionRuleUserList
, there's an additional distinction to make. By
default, Google Ads will AND
together all rule items in a rule item
group. This means that every rule item in at least one rule item group
must match in order for the rule to add a visitor to the list. This is called
"disjunctive normal form", or DNF
.
Alternatively, you could set up your list to only add a visitor to the list if
at least one rule item in each rule item group matches. This
is called "conjunctive normal form", or CNF
, and is available for
ExpressionRuleUserList
by using the ruleType
field. Trying to use CNF
for
a DateSpecificRuleUserList
will result in an error.
All that's left is to combine the rule item groups above into a new user
list. In this case, we'll leave the default DNF
functionality in place, since
that's what we built these rules for.
// Create the user list.
ExpressionRuleUserList expressionUserList = new ExpressionRuleUserList();
expressionUserList.setName("My expression rule user list");
expressionUserList.setDescription("Users who checked out in November or December "
+ "OR visited the checkout page with more than one item in their cart");
// OR the RuleItemGroups together into a Rule.
Rule rule = new Rule();
rule.setGroups(new RuleItemGroup[] {checkoutMultipleItemGroup, checkedOutNovDecItemGroup});
rule.setRuleType(UserListRuleType.DNF);
expressionUserList.setRule(rule);
// Set other optional attributes of the user list.
...
// Create an operation to ADD the user list.
UserListOperation operation = new UserListOperation();
operation.setOperator(Operator.ADD);
operation.setOperand(expressionUserList);
// Submit the operation.
UserListReturnValue result =
adwordsUserListService.mutate(new UserListOperation[] {operation});
Limit by site visit date range
The ExpressionRuleUserList
above meets your needs, but what if you only want
to capture the users who satisfy the rule in that list and visit your site
between October 1st and December 31st? Use DateSpecificRuleUserList
.
To create a DateSpecificUserList
, follow the same process you'd follow for an
ExpressionRuleUserList
, but also set the
startDate
and
endDate
of the list.
DateSpecificRuleUserList dateRuleUserList = new DateSpecificRuleUserList();
dateRuleUserList.setStartDate(startDate.toString("20171001"));
dateRuleUserList.setEndDate(endDate.toString("20171231"));
// Set optional attributes of the user list, such as membershipLifeSpan or
// integration code.
...
// Use the same rule defined above.
dateRuleUserList.setRule(rule);
That's all there is to it. The new list will contain all users who meet the same
rules as the previous list, but only if they visit your site between startDate
(inclusive) and endDate
(inclusive). See the
DateSpecificRuleUserList
documentation for other options, such as open start or end dates.
Include past users in the list
You can also include past users in a rule-based user list by setting the
prepopulationStatus
of the user list to REQUESTED
, and monitor the progress of the asynchronous
prepopulation process by periodically checking the status of this field.
Modify bids for users in the list
You've created a user list and set up the remarketing tag on your site. Now you want to specifically target members of the list in your ad groups or campaigns by increasing your bids by 25%.
Let's modify the bids for a set of ad groups:
// Specify the ad group IDs.
List<Long> adGroupIds = Lists.newArrayList(
// ad group ID 1,
// ad group ID 2,
// ...
);
// Create a CriterionUserList that points to the user list created above.
CriterionUserList criterionUserList = new CriterionUserList();
criterionUserList.setUserListId(dateRuleUserList.getId());
List<AdGroupCriterionOperation> operations = Lists.newArrayList();
for(Long adGroupId : adGroupIds) {
// Create a BiddableAdGroupCriterion for the CriterionUserList and set
// its bid modifier to 1.25. Instead of specifying a bid modifier, you
// could set the BiddableAdGroupCriterion's bidding strategy configuration
// to a configuration with specific bids.
BiddableAdGroupCriterion biddableCriterion = new BiddableAdGroupCriterion();
biddableCriterion.setAdGroupId(adGroupId);
biddableCriterion.setCriterion(criterionUserList);
biddableCriterion.setBidModifier(1.25);
// Create an operation to ADD the BiddableAdGroupCriterion.
AdGroupCriterionOperation operation = new AdGroupCriterionOperation();
operation.setOperand(biddableCriterion);
operation.setOperator(Operator.ADD);
operations.add(operation);
}
// Submit the operations.
AdGroupCriterionReturnValue result = adGroupCriterionService.mutate(
operations.toArray(new AdGroupCriterionOperation[operations.size()]));
The process for modifying bids for a campaign is very similar:
// Specify the campaign ID.
Long campaignId = // ID of campaign
// Create a CriterionUserList that points to the user list created above.
CriterionUserList criterionUserList = new CriterionUserList();
criterionUserList.setUserListId(dateRuleUserList.getId());
CampaignCriterion campaignCriterion = new CampaignCriterion();
campaignCriterion.setCampaignId(campaignId);
campaignCriterion.setCriterion(criterionUserList);
campaignCriterion.setBidModifier(1.25);
CampaignCriterionOperation operation = new CampaignCriterionOperation();
operation.setOperand(campaignCriterion);
operation.setOperator(Operator.ADD);
operations.add(operation);
// Submit the operations.
CampaignCriterionReturnValue result = CampaignCriterionService.mutate(
new AdGroupCriterionOperation[] {operation});
Additional user list options
You can take your rule-based user lists one step further and combine them with
other user lists to create even more sophisticated targeting. For example, if
you have a
BasicUserList
that targets a specific conversion type and a
RuleBasedUserList
that targets users based on custom parameters, you can target members in both
lists by creating a
LogicalUserList
.
See Multiple user lists above for an example.
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 using only built-in remarketing tag parameters, you don't need to make any edits to your remarketing tag. If you're using custom parameters, see the following article for how to edit your tag to include them: Advanced strategies for tagging and creating remarketing lists.
Code examples
Complete code examples for adding a rule-based user list are available in the Remarketing folder of each client library: