Remarketing and Audience Targeting

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, or finalMobileUrls fields in Search and Shopping campaigns.

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 - 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 AdWords 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 AdWords 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();
site1StringRuleItem.key = urlStringKey;
site1StringRuleItem.op = StringRuleItemStringOperator.EQUALS;
site1StringRuleItem.value = "example.com/example1";
RuleItem site1RuleItem = new RuleItem();
site1RuleItem.Item = site1StringRuleItem;

StringRuleItem site2StringRuleItem = new StringRuleItem();
site2StringRuleItem.key = (urlStringKey);
site2StringRuleItem.op = (StringRuleItemStringOperator.EQUALS);
site2StringRuleItem.value = ("example.com/example2");
RuleItem site2RuleItem = new RuleItem();
site2RuleItem.Item = (site2StringRuleItem);

// Create two RuleItemGroups to show that a visitor browsed two sites.
RuleItemGroup site1RuleItemGroup = new RuleItemGroup();
site1RuleItemGroup.items = new RuleItem[] { site1RuleItem };
RuleItemGroup site2RuleItemGroup = new RuleItemGroup();
site2RuleItemGroup.items = new RuleItem[] { site2RuleItem };

// Create two rules to show that a visitor browsed two sites.
Rule userVisitedSite1Rule = new Rule();
userVisitedSite1Rule.groups = new RuleItemGroup[] { site1RuleItemGroup };

Rule userVisitedSite2Rule = new Rule();
userVisitedSite2Rule.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::v201802::StringRuleItem->new({
    key => Google::Ads::AdWords::v201802::StringKey->new(
      {name => "url__"}
    ),
    op    => "EQUALS",
    value => "example.com/example1"
  });
my $site1_rule_item = Google::Ads::AdWords::v201802::RuleItem->new(
  {StringRuleItem => $site1_string_rule_item});
my $site2_string_rule_item =
  Google::Ads::AdWords::v201802::StringRuleItem->new({
    key => Google::Ads::AdWords::v201802::StringKey->new(
      {name => "url__"}
    ),
    op    => "EQUALS",
    value => "example.com/example2"
  });
my $site2_rule_item = Google::Ads::AdWords::v201802::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::v201802::RuleItemGroup->new(
  {items => [$site1_rule_item]});
my $site2_item_group = Google::Ads::AdWords::v201802::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::v201802::Rule->new({
    groups => [$site1_item_group]
  });
my $user_visited_site2_rule = Google::Ads::AdWords::v201802::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();
combinedRuleUserList.name = "Combined rule user list created at " + creationTimeString;
combinedRuleUserList.description = "Users who visited two sites.";
combinedRuleUserList.leftOperand = userVisitedSite1Rule;
combinedRuleUserList.rightOperand = userVisitedSite2Rule;
combinedRuleUserList.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::v201802::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.

Note: Despite the name, a ConversionTracker of category REMARKETING does not count conversions.

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

Note: A ConversionTracker of category REMARKETING does not appear in the Conversions section of the AdWords UI. Its status is always set to HIDDEN and cannot be changed.

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.

Note: Don't confuse LogicalUserList with RuleBasedUserList. A LogicalUserList is defined as a custom combination of existing user lists whereas a RuleBasedUserList is based on rules applied to the parameter values of your remarketing tag.

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

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.

Note: Email address data is supported for all users, but uploading address information is only available to users who are on a whitelist.

These audience lists are eligible to serve on Google Search, YouTube, and Gmail but will not be available on 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 an email address you must:

• Remove leading/trailing whitespaces

• Set the email address to be all lowercase

See the Code examples section below for a full demonstration of how to add members, correctly normalized and hashed.

There are different 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 its SimilarUserList are available. Ads will show on Gmail only if there are GSP creatives.

Search network with display select 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 its SimilarUserList are available. Ads will show on YouTube only if there are in-stream TrueView ads.

Caveats

• The API imposes a limit on the number of email addresses in each mutate request.

• The MembershipLifeSpan limit might be different from other user lists.

• It takes 6 to 12 hours for a list to be populated with members, so you'll most likely see an "In Progress" status (on the AdWords UI) if you upload to an audience list more frequently than once every 12 hours.

• Email addresses must be associated with a Google account.

• Only @gmail.com addresses can be used for targeting in Gmail.

• 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 email addresses to the list to ensure that ads start serving.

• A CrmBasedUserList can only be combined with another CrmBasedUserList when using a LogicalUserList. All the policies for CrmBasedUserList will apply to the result user list.

Customer match with phone number

Similar to customer match with emails, you can also perform customer match 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. [phone], [phone]).

Note: 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 match using IDFA (Identifier for Advertising) or AAID (Google Advertising ID) mobile device IDs.

Note: Mobile device IDs cannot be combined with the any other types of customer data.

Note: Starting in v201802, you need to specify the appId property and set uploadKeyType to MOBILE_ADVERTISING_ID prior to using a user list for customer match with mobile device IDs.

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

Note: 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 AdWords remarketing features.

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:

1. Users who visited the checkout page and had more than one item in their cart.
2. 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 RuleItems:

1. Users who visited the checkout page.
2. 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, AdWords 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:

1. Users who checked out after October 31st.
2. 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, AdWords 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:

Java

• Add a rule-based user list
• Add a customer match user list

C#

• Add a rule-based user list
• Add a customer match user list

PHP

• Add a rule-based user list
• Add a customer match user list

Perl

• Add a rule-based user list
• Add a customer match user list

Python

• Add a rule-based user list
• Add a customer match user list

Ruby

• Add a rule-based user list
• Add a customer match user list