AdWords API
Hide

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 guide focuses on rule-based lists, it will take you through examples of creating ExpressionRuleUserList and DateSpecificRuleUserList. For other types of user lists, see the Remarketing guide.

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

Rule-based lists created in the AdWords user interface

Rule-based lists created in the AdWords user interface and the AdWords API use different underlying formats that aren't yet compatible with each other.

The difference in formats does not impact how the lists behave. However, if you use the API to retrieve a rule-based list created through the AdWords user interface, the response will not include the rule details. Similarly, you may encounter issues if you attempt to use the user interface to edit rule-based lists created via the AdWords API.

Due to the differences between API and user interface rule-based lists, you should use either the API or the user interface to maintain each list, but not both.

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.

Let's say you have a site where you have configured several custom remarketing tag parameters to capture the following attributes of users:

  • ecomm_pagetype - 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 using the following rules:

  1. Users who visited the checkout page AND had more than one item in their cart

    OR

  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 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 (you guessed it!) RuleBasedUserList. The diagram below shows what the RuleBasedUserList for this use case will look like when we're done.

Diagram of a rule based user list's structure

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. When items are combined into an item group, AdWords will AND their rules together.

RuleItemGroup checkoutMultipleItemGroup = new RuleItemGroup();
checkoutMultipleItemGroup.setItems(new RuleItem[] {checkoutRuleItem, cartSizeRuleItem});

Create the second RuleItemGroup

The RuleItemGroup on the right consists of two RuleItems:

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

// Create the RuleItem for the start date.
DateRuleItem startDateDateRuleItem = new DateRuleItem(
    new DateKey("checkoutdate"),
    DateRuleItemDateOperator.AFTER, "20141031");
RuleItem startDateRuleItem = new RuleItem();
startDateRuleItem.setDateRuleItem(startDateDateRuleItem);

// Create the RuleItem for the end date.
DateRuleItem endDateDateRuleItem = new DateRuleItem(
    new DateKey("checkoutdate"),
    DateRuleItemDateOperator.BEFORE, "20150101");
RuleItem endDateRuleItem = new RuleItem();
endDateRuleItem.setDateRuleItem(endDateDateRuleItem);

As with the group on the left, combine these two RuleItems into a RuleItemGroup to AND them together.

RuleItemGroup checkedOutNovDecItemGroup = new RuleItemGroup();
checkedOutNovDecItemGroup.setItems(new RuleItem[] {startDateRuleItem, endDateRuleItem});

Create the user list

All that's left is to combine the rule item groups above into a new user list.

// 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});
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? Fear not! DateSpecificRuleUserList is here to help!

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("20141001"));
dateRuleUserList.setEndDate(endDate.toString("20141231"));

// 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 documentation for DateSpecificRuleUserList for other options, such as open start or end dates.

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 by increasing your bids by 25%.

To set this up, simply create a BiddableAdGroupCriterion for each ad group that points to the user list and has the desired bid modifier.

// 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()]));

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 the Combining user lists section of the Remarketing guide for an example.

Adding the remarketing tag to your site

All AdWords accounts have exactly one account-level remarketing tag, which is automatically created when the account is opened. For your rule-based user lists to be populated, you need to add your account-level remarketing tag to your site. Follow the instructions in the Remarketing guide to retrieve the tag and install it on your site.

If you are using only built-in remarketing tag parameters, you do not need to make any edits to your remarketing tag. If you are 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 are available in each client library:

Library Rule-based remarketing example
Java AddRuleBasedUserLists.java
Perl add_rule_based_user_lists.pl
PHP AddRuleBasedUserLists.php
Python add_rule-based_user_lists.py
.NET(C#) AddRuleBasedRemarketingList.cs
.NET(VB) AddRuleBasedRemarketingList.vb

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 3.0 License, and code samples are licensed under the Apache 2.0 License. For details, see our Site Policies.

Send feedback about...

This page
Documentation feedback
AdWords API
Product feedback